Policy.h

Go to the documentation of this file.

// -*- lsst-c++ -*-

/* 
 * LSST Data Management System
 * Copyright 2008, 2009, 2010 LSST Corporation.
 * 
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the LSST License Statement and 
 * the GNU General Public License along with this program.  If not, 
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */
 
#ifndef LSST_PEX_POLICY_POLICY_H
#define LSST_PEX_POLICY_POLICY_H

#include <string>
#include <vector>
#include <list>
#include <map>

#include <boost/shared_ptr.hpp>
#include <boost/filesystem/path.hpp>
#include <boost/filesystem/operations.hpp>

#include "lsst/daf/base/Citizen.h"
#include "lsst/daf/base/Persistable.h"
#include "lsst/daf/base/PropertySet.h"
#include "lsst/pex/policy/exceptions.h"

namespace lsst {
namespace pex {
namespace policy {

// forward declaration
class PolicySource;
class PolicyFile;
class Dictionary;
class ValidationError;

#define POL_GETSCALAR(name, type, vtype) \
    try { \
        return _data->get<type>(name); \
    } catch (lsst::pex::exceptions::NotFoundError&) {   \
        throw LSST_EXCEPT(NameNotFound, name);  \
    } catch (lsst::pex::exceptions::TypeError&) { \
        throw LSST_EXCEPT(TypeError, name, std::string(typeName[vtype])); \
    } catch (boost::bad_any_cast&) { \
        throw LSST_EXCEPT(TypeError, name, std::string(typeName[vtype])); \
    }

#define POL_GETLIST(name, type, vtype) \
    try { \
        return _data->getArray<type>(name); \
    } catch (lsst::pex::exceptions::NotFoundError&) {   \
        throw LSST_EXCEPT(NameNotFound, name);  \
    } catch (lsst::pex::exceptions::TypeError&) { \
        throw LSST_EXCEPT(TypeError, name, std::string(typeName[vtype])); \
    } catch (boost::bad_any_cast&) { \
        throw LSST_EXCEPT(TypeError, name, std::string(typeName[vtype])); \
    } 


class Policy : public lsst::daf::base::Citizen, public lsst::daf::base::Persistable {
public:

    typedef boost::shared_ptr<Policy> Ptr;
    typedef boost::shared_ptr<const Policy> ConstPtr;
    typedef boost::shared_ptr<Dictionary> DictPtr;
    typedef boost::shared_ptr<const Dictionary> ConstDictPtr;
    typedef boost::shared_ptr<PolicyFile> FilePtr;

    typedef std::vector<bool> BoolArray;
    typedef std::vector<int> IntArray;
    typedef std::vector<double> DoubleArray;
    typedef std::vector<std::string> StringArray;
    typedef std::vector<Ptr> PolicyPtrArray;
    typedef std::vector<FilePtr> FilePtrArray;
    typedef std::vector<ConstPtr> ConstPolicyPtrArray;

    enum ValueType {
        UNDETERMINED = -1,
        UNDEF,
        BOOL,
        INT,
        DOUBLE,
        STRING,
        POLICY,
        FILE
    };

    static const char * const typeName[];

    Policy();


    explicit Policy(const std::string& pathOrUrn);
    explicit Policy(const char *pathOrUrn);

    explicit Policy(const PolicySource& source);

    Policy(bool validate, const Dictionary& dict,
           const boost::filesystem::path& repository="");

    Policy(Policy& pol, bool deep=false);

    Policy(const Policy& pol);


    static Policy *createPolicy(PolicySource& input, bool doIncludes=true, 
                                bool validate=true);
    static Policy *createPolicy(const std::string& input, bool doIncludes=true,
                                bool validate=true);

    static Policy *createPolicyFromUrn(const std::string& urn,
                                       bool validate=true);


    static Policy *createPolicy(PolicySource& input,
                                const boost::filesystem::path& repos, 
                                bool validate=true);
    static Policy *createPolicy(PolicySource& input, const std::string& repos, 
                                bool validate=true);
    static Policy *createPolicy(PolicySource& input, const char *repos, 
                                bool validate=true);
    static Policy *createPolicy(const std::string& input, 
                                const boost::filesystem::path& repos,
                                bool validate=true);
    static Policy *createPolicy(const std::string& input, 
                                const std::string& repos, bool validate=true);
    static Policy *createPolicy(const std::string& input, const char *repos, 
                                bool validate=true);

    static FilePtr createPolicyFile(const std::string& pathOrUrn, bool strict=false);

    template <typename T> static ValueType getValueType();

    static ValueType getTypeByName(const std::string& name);
    // throw(BadNameError) // swig doesn't like this

    virtual ~Policy();

    int nameCount() const {
        return _data->nameCount();
    }


    int names(std::list<std::string>& names, 
              bool topLevelOnly=false, 
              bool append=false) const;                      // inlined below
    int paramNames(std::list<std::string>& names, 
                   bool topLevelOnly=false, 
                   bool append=false) const;                 // inlined below
    int policyNames(std::list<std::string>& names, 
                    bool topLevelOnly=false, 
                    bool append=false) const;                // inlined below
    int fileNames(std::list<std::string>& names, 
                  bool topLevelOnly=false, 
                  bool append=false) const;                  // inlined below


    StringArray names(bool topLevelOnly=false) const;        // inlined below
    StringArray paramNames(bool topLevelOnly=false) const;   // inlined below
    StringArray policyNames(bool topLevelOnly=false) const;  // inlined below
    StringArray fileNames(bool topLevelOnly=false) const;    // inlined below

    bool isDictionary() const { return exists("definitions");  }

    bool canValidate() const;

    const ConstDictPtr getDictionary() const;

    void setDictionary(const Dictionary& dict);

    void validate(ValidationError *errs=0) const;

    size_t valueCount(const std::string& name) const;        // inlined below

    bool isArray(const std::string& name) const;             // inlined below

    bool exists(const std::string& name) const;              // inlined below

    bool isBool(const std::string& name) const;               // inlined below

    bool isInt(const std::string& name) const;               // inlined below

    bool isDouble(const std::string& name) const;            // inlined below

    bool isString(const std::string& name) const;            // inlined below

    bool isPolicy(const std::string& name) const;            // inlined below

    bool isFile(const std::string& name) const;              // inlined below

    const std::type_info& getTypeInfo(const std::string& name) const; //inlined

    const std::type_info& typeOf(const std::string& name) const;     // inlined

    ValueType getValueType(const std::string& name) const;

    const char *getTypeName(const std::string& name) const {
        try { return typeName[getValueType(name)]; }
        catch (NameNotFound&) { return typeName[UNDEF]; }
    }

    template <typename T> T getValue(const std::string& name) const;

    template <typename T> std::vector<T> getValueArray(const std::string& name) const;


    ConstPtr getPolicy(const std::string& name) const;       // inlined below
    Ptr getPolicy(const std::string& name);                  // inlined below

    FilePtr getFile(const std::string& name) const;

    bool getBool(const std::string& name) const { 
        POL_GETSCALAR(name, bool, BOOL) 
    }

    int getInt(const std::string& name) const { 
        POL_GETSCALAR(name, int, INT) 
    }

    double getDouble(const std::string& name) const { 
        POL_GETSCALAR(name, double, DOUBLE) 
    }

    const std::string getString(const std::string& name) const { 
        POL_GETSCALAR(name, std::string, STRING) 
    }


    PolicyPtrArray getPolicyArray(const std::string& name) const;
    ConstPolicyPtrArray getConstPolicyArray(const std::string& name) const;

    FilePtrArray getFileArray(const std::string& name) const; 


    BoolArray getBoolArray(const std::string& name) const;  // inlined
    IntArray getIntArray(const std::string& name) const;    // inlined
    DoubleArray getDoubleArray(const std::string& name) const; // inlined
    StringArray getStringArray(const std::string& name) const;  //inlined


    template <typename T> void setValue(const std::string& name, const T& value);
    void set(const std::string& name, const Ptr& value);      // inlined below
    void set(const std::string& name, const FilePtr& value);  // inlined below
    void set(const std::string& name, bool value);            // inlined below
    void set(const std::string& name, int value);             // inlined below
    void set(const std::string& name, double value);          // inlined below
    void set(const std::string& name, const std::string& value);  // inlined
    void set(const std::string& name, const char *value);     // inlined below


    // avoid name confusion with appended T
    template <typename T> void addValue(const std::string& name, const T& value);
    void add(const std::string& name, const Ptr& value);      // inlined below
    void add(const std::string& name, const FilePtr& value);  // inlined below
    void add(const std::string& name, bool value);            // inlined below
    void add(const std::string& name, int value);             // inlined below
    void add(const std::string& name, double value);          // inlined below
    void add(const std::string& name, const std::string& value);    // inlined
    void add(const std::string& name, const char *value);     // inlined below

    void remove(const std::string& name); // inlined below

    int loadPolicyFiles(bool strict=true) {
        return loadPolicyFiles(boost::filesystem::path(), strict);
    }

    virtual int loadPolicyFiles(const boost::filesystem::path& repository,
                                bool strict=true);

    int mergeDefaults(const Policy& defaultPol, bool keepForValidation=true,
                      ValidationError *errs=0);

    virtual std::string str(const std::string& name, 
                            const std::string& indent="") const;

    virtual void print(std::ostream& out, const std::string& label="Policy", 
                       const std::string& indent="") const;

    std::string toString() const;

    lsst::daf::base::PropertySet::Ptr asPropertySet();             // inlined below

protected:
    Policy(const lsst::daf::base::PropertySet::Ptr ps) 
        : Citizen(typeid(this)), lsst::daf::base::Persistable(), _data(ps) 
    { }

private:
    lsst::daf::base::PropertySet::Ptr _data;

    DictPtr _dictionary;

    int _names(std::list<std::string>& names, bool topLevelOnly=false, 
               bool append=false, int want=3) const;
    int _names(std::vector<std::string>& names, bool topLevelOnly=false, 
               bool append=false, int want=3) const;

    template <typename T> 
    void _validate(const std::string& name, const T& value, int curCount=0);

    std::vector<lsst::daf::base::Persistable::Ptr> 
        _getPersistList(const std::string& name) const 
    {
        POL_GETLIST(name, Persistable::Ptr, FILE)
    }
    std::vector<lsst::daf::base::PropertySet::Ptr> 
        _getPropSetList(const std::string& name) const 
    {
        POL_GETLIST(name, lsst::daf::base::PropertySet::Ptr, POLICY)
    }

    static Policy *_createPolicy(PolicySource& input, bool doIncludes,
                                 const boost::filesystem::path& repos,
                                 bool validate);
    static Policy *_createPolicy(const std::string& input, bool doIncludes,
                                 const boost::filesystem::path& repos,
                                 bool validate);
};

inline std::ostream& operator<<(std::ostream& os, const Policy& p) {
    p.print(os);
    return os;
}

/*  ************** Inline Class functions ********************  */

inline int Policy::names(std::list<std::string>& names, bool topLevelOnly, 
                         bool append) const
{
    return _names(names, topLevelOnly, append, 7);
}
inline int Policy::paramNames(std::list<std::string>& names, bool topLevelOnly,
                              bool append) const
{
    return _names(names, topLevelOnly, append, 4);
}
inline int Policy::policyNames(std::list<std::string>& names, 
                               bool topLevelOnly,
                               bool append) const
{
    return _names(names, topLevelOnly, append, 1);
}
inline int Policy::fileNames(std::list<std::string>& names, bool topLevelOnly, 
                             bool append) const
{
    return _names(names, topLevelOnly, append, 2);
}

inline Policy::StringArray Policy::names(bool topLevelOnly) const { 
    return _data->names(); 
}
inline Policy::StringArray Policy::paramNames(bool topLevelOnly) const {
    StringArray out;
    _names(out, topLevelOnly, true, 4);
    return out;
}
inline Policy::StringArray Policy::policyNames(bool topLevelOnly) const {
    return _data->propertySetNames(topLevelOnly);
}
inline Policy::StringArray Policy::fileNames(bool topLevelOnly) const {
    StringArray out;
    _names(out, topLevelOnly, true, 2);
    return out;
}

inline size_t Policy::valueCount(const std::string& name) const { 
    return _data->valueCount(name); 
}

inline bool Policy::isArray(const std::string& name) const { 
    return _data->isArray(name); 
}

inline bool Policy::exists(const std::string& name) const { 
    return _data->exists(name); 
}

inline bool Policy::isBool(const std::string& name) const {
    try {
        return (_data->typeOf(name) == typeid(bool));
    }
    catch (...) {
        return false;
    }
}

inline bool Policy::isInt(const std::string& name) const {
    try {
        return (_data->typeOf(name) == typeid(int));
    }
    catch (...) {
        return false;
    }
}

inline bool Policy::isDouble(const std::string& name) const {
    try {
        return (_data->typeOf(name) == typeid(double));
    }
    catch (...) {
        return false;
    }
}

inline bool Policy::isString(const std::string& name) const {
    try {
        return (_data->typeOf(name) == typeid(std::string));
    }
    catch (...) {
        return false;
    }
}

inline bool Policy::isPolicy(const std::string& name) const {
    try {
        return (_data->typeOf(name) == typeid(lsst::daf::base::PropertySet::Ptr));
    }
    catch (...) {
        return false;
    }
}

inline bool Policy::isFile(const std::string& name) const {
    
    try {
        return (getValueType(name) == FILE);
    }
    catch (...) {
        return false;
    }
}

inline const std::type_info& Policy::getTypeInfo(const std::string& name) const
{
    try {  return _data->typeOf(name); }
    catch (lsst::pex::exceptions::NotFoundError& e) {
        throw LSST_EXCEPT(NameNotFound, name);
    }
}

inline const std::type_info& Policy::typeOf(const std::string& name) const {
    return getTypeInfo(name); 
}

inline Policy::ConstPtr Policy::getPolicy(const std::string& name) const {
    return ConstPtr(new Policy(_data->get<lsst::daf::base::PropertySet::Ptr>(name)));
}
inline Policy::Ptr Policy::getPolicy(const std::string& name) {
    return Ptr(new Policy(_data->get<lsst::daf::base::PropertySet::Ptr>(name)));
}

inline 
Policy::StringArray Policy::getStringArray(const std::string& name) const {
    return _data->getArray<std::string>(name);
}

inline Policy::BoolArray Policy::getBoolArray(const std::string& name) const {
    POL_GETLIST(name, bool, BOOL) 
}

inline Policy::IntArray Policy::getIntArray(const std::string& name) const {
    POL_GETLIST(name, int, INT) 
}

inline 
Policy::DoubleArray Policy::getDoubleArray(const std::string& name) const {
    POL_GETLIST(name, double, DOUBLE) 
}

inline void Policy::set(const std::string& name, const Ptr& value) {
    _validate(name, value);
    _data->set(name, value->asPropertySet());
}
inline void Policy::set(const std::string& name, bool value) { 
    _validate(name, value);
    _data->set(name, value); 
}
inline void Policy::set(const std::string& name, int value) { 
    _validate(name, value);
    _data->set(name, value); 
}
inline void Policy::set(const std::string& name, double value) { 
    _validate(name, value);
    _data->set(name, value); 
}
inline void Policy::set(const std::string& name, const std::string& value) { 
    _validate(name, value);
    _data->set(name, value); 
}
inline void Policy::set(const std::string& name, const char *value) { 
    if (value == NULL)
        throw LSST_EXCEPT(lsst::pex::exceptions::InvalidParameterError,
                          std::string("Attempted to assign NULL value to ")
                          + name + ".");
    _validate(name, std::string(value));
    _data->set(name, std::string(value)); 
}

#define POL_ADD(name, value) \
    try {  _data->add(name, value);  } \
    catch(lsst::pex::exceptions::TypeError&) { \
        throw LSST_EXCEPT(TypeError, name, getTypeName(name));  \
    }

inline void Policy::add(const std::string& name, const Ptr& value) {
    _validate(name, value, valueCount(name));
    POL_ADD(name, value->asPropertySet())
}
inline void Policy::add(const std::string& name, bool value) { 
    _validate(name, value, valueCount(name));
    POL_ADD(name, value); 
}
inline void Policy::add(const std::string& name, int value) { 
    _validate(name, value, valueCount(name));
    POL_ADD(name, value); 
}
inline void Policy::add(const std::string& name, double value) { 
    _validate(name, value, valueCount(name));
    POL_ADD(name, value); 
}
inline void Policy::add(const std::string& name, const std::string& value) { 
    _validate(name, value, valueCount(name));
    POL_ADD(name, value); 
}
inline void Policy::add(const std::string& name, const char *value) { 
    std::string v(value);
    _validate(name, v, valueCount(name));
    POL_ADD(name, v); 
}

// TODO: validate if required value?
inline void Policy::remove(const std::string& name) {
    _data->remove(name);
}

inline Policy* Policy::createPolicy(PolicySource& input, bool doIncludes, 
                                    bool validate) 
{
    return _createPolicy(input, doIncludes, boost::filesystem::path(), validate);
} 

inline Policy* Policy::createPolicy(const std::string& input, bool doIncludes, 
                                    bool validate) 
{
    return _createPolicy(input, doIncludes, boost::filesystem::path(), validate);
} 

inline Policy* Policy::createPolicy(PolicySource& input, 
                                    const boost::filesystem::path& repository,
                                    bool validate) 
{
    return _createPolicy(input, true, repository, validate);
}

inline Policy* Policy::createPolicy(PolicySource& input, 
                                    const std::string& repository, 
                                    bool validate) 
{
    return _createPolicy(input, true, boost::filesystem::path(repository), validate);
}

inline Policy* Policy::createPolicy(PolicySource& input, 
                                    const char *repository, 
                                    bool validate) 
{
    return _createPolicy(input, true, boost::filesystem::path(repository), validate);
}

inline Policy* Policy::createPolicy(const std::string& input, 
                                    const boost::filesystem::path& repository,
                                    bool validate) 
{
    return _createPolicy(input, true, repository, validate);
}

inline Policy* Policy::createPolicy(const std::string& input, 
                                    const std::string& repository, 
                                    bool validate) 
{
    return _createPolicy(input, true, boost::filesystem::path(repository), validate);
}

inline Policy* Policy::createPolicy(const std::string& input, 
                                    const char *repository, 
                                    bool validate) 
{
    return _createPolicy(input, true, boost::filesystem::path(repository), validate);
}

inline lsst::daf::base::PropertySet::Ptr Policy::asPropertySet() { return _data; }

// general case is disallowed; known types are specialized
template <typename T> T Policy::getValue(const std::string& name) const {
    throw LSST_EXCEPT(TypeError, name, "not implemented for this type");
}
template <> bool Policy::getValue<bool>(const std::string& name) const;
template <> int Policy::getValue<int>(const std::string& name) const;
template <> double Policy::getValue<double>(const std::string& name) const;
template <> std::string Policy::getValue<std::string>(const std::string& name) const;
template <> Policy::FilePtr Policy::getValue<Policy::FilePtr>(const std::string& name) const;
template <> Policy::ConstPtr Policy::getValue<Policy::ConstPtr>(const std::string& name) const;

// general case is disallowed; known types are specialized
template <typename T> std::vector<T> Policy::getValueArray(const std::string& name) const {
    throw LSST_EXCEPT(TypeError, name, "not implemented for this type");
}
template <> std::vector<bool> Policy::getValueArray<bool>(const std::string& name) const;
template <> std::vector<int> Policy::getValueArray<int>(const std::string& name) const;
template <> std::vector<double> Policy::getValueArray<double>(const std::string& name) const;
template <> std::vector<std::string> Policy::getValueArray<std::string>(const std::string& name) const;
template <> Policy::FilePtrArray Policy::getValueArray<Policy::FilePtr>(const std::string& name) const;
template <> Policy::PolicyPtrArray Policy::getValueArray<Policy::Ptr>(const std::string& name) const;
template <> Policy::ConstPolicyPtrArray Policy::getValueArray<Policy::ConstPtr>(const std::string& name) const;

// general case is disallowed; known types are specialized
template <typename T> Policy::ValueType Policy::getValueType() {
    throw LSST_EXCEPT(TypeError, "unknown", "not implemented for this type");
}
template <> Policy::ValueType Policy::getValueType<bool>();
template <> Policy::ValueType Policy::getValueType<int>();
template <> Policy::ValueType Policy::getValueType<double>();
template <> Policy::ValueType Policy::getValueType<std::string>();
template <> Policy::ValueType Policy::getValueType<Policy>();
template <> Policy::ValueType Policy::getValueType<Policy::FilePtr>();
template <> Policy::ValueType Policy::getValueType<Policy::Ptr>();
template <> Policy::ValueType Policy::getValueType<Policy::ConstPtr>();

// general case is disallowed; known types are specialized
template <typename T> void Policy::setValue(const std::string& name, const T& value) {
    throw LSST_EXCEPT(TypeError, name, "not implemented for this type");
}
template <> void Policy::setValue<bool>(const std::string& name, const bool& value);
template <> void Policy::setValue<int>(const std::string& name, const int& value);
template <> void Policy::setValue<double>(const std::string& name, const double& value);
template <> void Policy::setValue<std::string>(const std::string& name, const std::string& value);
template <> void Policy::setValue<Policy::Ptr>(const std::string& name, const Policy::Ptr& value);
template <> void Policy::setValue<Policy::FilePtr>(const std::string& name, const Policy::FilePtr& value);

// general case is disallowed; known types are specialized
template <typename T> void Policy::addValue(const std::string& name, const T& value) {
    throw LSST_EXCEPT(TypeError, name, "not implemented for this type");
}
template <> void Policy::addValue<bool>(const std::string& name, const bool& value);
template <> void Policy::addValue<int>(const std::string& name, const int& value);
template <> void Policy::addValue<double>(const std::string& name, const double& value);
template <> void Policy::addValue<std::string>(const std::string& name, const std::string& value);
template <> void Policy::addValue<Policy::Ptr>(const std::string& name, const Policy::Ptr& value);
template <> void Policy::addValue<Policy::FilePtr>(const std::string& name, const Policy::FilePtr& value);

}}}  // end namespace lsst::pex::policy

#endif // LSST_PEX_POLICY_POLICY_H