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 <memory>
#include <boost/filesystem/path.hpp>
#include <boost/filesystem/operations.hpp>

#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::Persistable {
public:
    typedef std::shared_ptr<Policy> Ptr;
    typedef std::shared_ptr<const Policy> ConstPtr;
    typedef std::shared_ptr<Dictionary> DictPtr;
    typedef std::shared_ptr<const Dictionary> ConstDictPtr;
    typedef std::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) : 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 {
    StringArray out;
    _names(out, topLevelOnly, true, 7);
    return out;
}
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 {
    StringArray out;
    _names(out, topLevelOnly, true, 1);
    return out;
}
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->isPropertySetPtr(name);
    } 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);

}  // namespace policy
}  // namespace pex
}  // namespace lsst

#endif  // LSST_PEX_POLICY_POLICY_H