Dictionary.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_DICTIONARY_H
#define LSST_PEX_POLICY_DICTIONARY_H
 
#include "lsst/pex/policy/Policy.h"
#include "lsst/pex/policy/exceptions.h"
#include <boost/regex.hpp>
#include <sstream>
 
namespace lsst {
namespace pex {
namespace policy {
 
class PolicySource;
class PolicyFile;
 
class ValidationError : public lsst::pex::exceptions::LogicError {
public:
    enum ErrorType {
        OK = 0,
 
        WRONG_TYPE = 1,
 
        MISSING_REQUIRED = 2,
 
        NOT_AN_ARRAY = 4,
 
        ARRAY_TOO_SHORT = 8,
 
        TOO_FEW_VALUES = 14,
 
        TOO_MANY_VALUES = 16,
 
        WRONG_OCCURRENCE_COUNT = 30,
 
        VALUE_DISALLOWED = 32,
 
        VALUE_OUT_OF_RANGE = 64,
 
        BAD_VALUE = 96,
 
        UNKNOWN_NAME = 128,
 
        BAD_DEFINITION = 256,
 
        NOT_LOADED = 512,
 
        UNKNOWN_ERROR = 1024
    };
 
    static const std::string& getErrorMessageFor(ErrorType err) {
        if (_errmsgs.size() == 0) _loadMessages();
        MsgLookup::iterator it = _errmsgs.find(err);
        if (it != _errmsgs.end())
            return it->second;
        else {
            // if it's a compound error that we don't have a pre-written
            // description of, then compile a description
            static std::string result;  // avoid memory issues
                                        // TODO: at cost of concurrence?
            std::ostringstream os;
            bool first = true;
            for (std::map<int, std::string>::const_iterator j = _errmsgs.begin(); j != _errmsgs.end(); ++j) {
                if (j->first != OK && (err & j->first) == j->first) {
                    os << (first ? "" : "; ") << j->second;
                    first = false;
                }
            }
            result = os.str();
            return result;
        }
    }
 
    static const std::string EMPTY;
 
    ValidationError(std::string const& message) : lsst::pex::exceptions::LogicError(message), _errors() {}
 
    // TODO: create way to change message when an error actually occurs
    ValidationError(char const* ex_file, int ex_line, char const* ex_func)
            : lsst::pex::exceptions::LogicError(ex_file, ex_line, ex_func,
                                                "Policy has unknown validation errors"),
              _errors() {}
 
    virtual lsst::pex::exceptions::Exception* clone() const;
    virtual char const* getType(void) const throw();
 
    ValidationError(const ValidationError& that)
            : lsst::pex::exceptions::LogicError(that), _errors(that._errors) {}
 
    ValidationError& operator=(const ValidationError& that) {
        LogicError::operator=(that);
        _errors = that._errors;
        return *this;
    }
 
    // Swig is having trouble with this macro
    //    ValidationError(POL_EARGS_TYPED)
    //       : lsst::pex::exceptions::LogicError(POL_EARGS_UNTYPED,
    //                                                    "policy has unknown validation errors"),
    //       _errors()
    //    { }
 
    virtual ~ValidationError() throw();
 
    int getParamCount() const { return _errors.size(); }
 
    void paramNames(std::list<std::string>& names) const {
        ParamLookup::const_iterator it;
        for (it = _errors.begin(); it != _errors.end(); it++) names.push_back(it->first);
    }
 
    std::vector<std::string> getParamNames() const;
 
    int getErrors(const std::string& name) const {
        ParamLookup::const_iterator it = _errors.find(name);
        if (it != _errors.end())
            return it->second;
        else
            return 0;
    }
 
    void addError(const std::string& name, ErrorType e) { _errors[name] |= e; }
 
    int getErrors() const {
        int out = 0;
        ParamLookup::const_iterator it;
        for (it = _errors.begin(); it != _errors.end(); it++) out |= it->second;
        return out;
    }
 
    std::string describe(std::string prefix = "") const;
 
    virtual char const* what(void) const throw();
 
protected:
    typedef std::map<int, std::string> MsgLookup;
    typedef std::map<std::string, int> ParamLookup;
 
    static MsgLookup _errmsgs;
 
    static void _loadMessages();
 
    ParamLookup _errors;
};
 
class Definition {
public:
    Definition(const std::string& paramName = "")
            : _type(Policy::UNDETERMINED), _name(paramName), _policy(), _wildcard(false) {
        _policy.reset(new Policy());
    }
 
    Definition(const std::string& paramName, const Policy::Ptr& defn)
            : _type(Policy::UNDETERMINED), _name(paramName), _policy(defn), _wildcard(false) {}
 
    Definition(const Policy::Ptr& defn)
            : _type(Policy::UNDETERMINED), _name(), _policy(defn), _wildcard(false) {}
 
    Definition(const Definition& that)
            : _type(Policy::UNDETERMINED), _name(that._name), _policy(that._policy), _wildcard(false) {}
 
    Definition& operator=(const Definition& that) {
        _type = Policy::UNDETERMINED;
        _name = that._name;
        _policy = that._policy;
        _prefix = that._prefix;
        _wildcard = that._wildcard;
        return *this;
    }
 
    Definition& operator=(const Policy::Ptr& defdata) {
        setData(defdata);
        return *this;
    }
 
    virtual ~Definition();
 
    const std::string& getName() const { return _name; }
 
 
    const std::string getPrefix() const { return _prefix; }
    void setPrefix(const std::string& prefix) { _prefix = prefix; }
 
 
    const bool isChildDefinition() const { return _wildcard; }
    void setChildDefinition(bool wildcard) { _wildcard = wildcard; }
    const bool isWildcard() const { return _wildcard; }
    void setWildcard(bool wildcard) { _wildcard = wildcard; }
 
    void setName(const std::string& newname) { _name = newname; }
 
    const Policy::Ptr& getData() const { return _policy; }
 
    void setData(const Policy::Ptr& defdata) {
        _type = Policy::UNDETERMINED;
        _policy = defdata;
    }
 
    Policy::ValueType getType() const {
        if (_type == Policy::UNDETERMINED) _type = _determineType();
        return _type;
    }
 
    std::string getTypeName() const { return Policy::typeName[getType()]; }
 
    std::string getDefault() const { return _policy->str("default"); }
 
    const std::string getDescription() const;
 
    const int getMaxOccurs() const;
 
    const int getMinOccurs() const;
 
    void setDefaultIn(Policy& policy, ValidationError* errs = 0) const { setDefaultIn(policy, _name, errs); }
 
    void setDefaultIn(Policy& policy, const std::string& withName, ValidationError* errs = 0) const;
 
    template <typename T>
    void setDefaultIn(Policy& policy, const std::string& withName, ValidationError* errs = 0) const;
 
    void validate(const Policy& policy, const std::string& name, ValidationError* errs = 0) const;
 
    void validate(const Policy& policy, ValidationError* errs = 0) const { validate(policy, _name, errs); }
 
 
    void validate(const std::string& name, bool value, int curcount = -1, ValidationError* errs = 0) const;
    void validate(const std::string& name, int value, int curcount = -1, ValidationError* errs = 0) const;
    void validate(const std::string& name, double value, int curcount = -1, ValidationError* errs = 0) const;
    void validate(const std::string& name, std::string value, int curcount = -1,
                  ValidationError* errs = 0) const;
    void validate(const std::string& name, const Policy& value, int curcount = -1,
                  ValidationError* errs = 0) const;
 
 
    void validate(const std::string& name, const Policy::BoolArray& value, ValidationError* errs = 0) const;
    void validate(const std::string& name, const Policy::IntArray& value, ValidationError* errs = 0) const;
    void validate(const std::string& name, const Policy::DoubleArray& value, ValidationError* errs = 0) const;
    void validate(const std::string& name, const Policy::StringArray& value, ValidationError* errs = 0) const;
    void validate(const std::string& name, const Policy::ConstPolicyPtrArray& value,
                  ValidationError* errs = 0) const;
 
    template <typename T>
    void validateBasic(const std::string& name, const Policy& policy, ValidationError* errs = 0) const;
 
 
    template <typename T>
    void validateBasic(const std::string& name, const T& value, int curcount = -1,
                       ValidationError* errs = 0) const;
    template <typename T>
    void validateBasic(const std::string& name, const std::vector<T>& value, ValidationError* errs = 0) const;
 
 
    void validateRecurse(const std::string& name, Policy::ConstPolicyPtrArray value,
                         ValidationError* errs) const;
 
    void validateRecurse(const std::string& name, const Policy& value, ValidationError* errs) const;
 
    void check() const;
 
protected:
    Policy::ValueType _determineType() const;
 
    void validateCount(const std::string& name, int count, ValidationError* errs) const;
 
    static const std::string EMPTY;
 
private:
    mutable Policy::ValueType _type;
    std::string _prefix;  // for recursive validation, eg "foo.bar."
    std::string _name;
    Policy::Ptr _policy;
    bool _wildcard;
};
 
inline std::ostream& operator<<(std::ostream& os, const Definition& d) {
    d.getData()->print(os, d.getName());
    return os;
}
 
class Dictionary : public Policy {
public:
    // keywords
    static const char* KW_DICT;
    static const char* KW_DICT_FILE;
    static const char* KW_TYPE;
    static const char* KW_DESCRIPTION;
    static const char* KW_DEFAULT;
    static const char* KW_DEFINITIONS;
    static const char* KW_CHILD_DEF;
    static const char* KW_ALLOWED;
    static const char* KW_MIN_OCCUR;
    static const char* KW_MAX_OCCUR;
    static const char* KW_MIN;
    static const char* KW_MAX;
    static const char* KW_VALUE;
 
    Dictionary() : Policy() {}
 
    Dictionary(const Policy& pol)
            : Policy((pol.isPolicy("dictionary")) ? *(pol.getPolicy("dictionary")) : pol) {
        check();
    }
 
    Dictionary(const Dictionary& dict) : Policy(dict) { check(); }
 
 
    explicit Dictionary(const char* filePath);
    explicit Dictionary(const std::string& filePath);
    explicit Dictionary(const PolicyFile& filePath);
 
 
    Policy::ConstPtr getDefinitions() const { return getPolicy("definitions"); }
    Policy::Ptr getDefinitions() { return getPolicy("definitions"); }
 
    void check() const;
 
    int definedNames(std::list<std::string>& names, bool append = false) const {
        return getDefinitions()->names(names, true, append);
    }
 
    StringArray definedNames() const { return getDefinitions()->names(true); }
 
    Definition getDef(const std::string& name) {
        Definition* def = makeDef(name);
        Definition out(*def);
        delete def;
        return out;
    }
 
    Definition* makeDef(const std::string& name) const;
 
    bool hasSubDictionary(const std::string& name) const {
        std::string key = std::string("definitions.") + name + "." + KW_DICT;
        // could also check isPolicy(key), but we would rather have
        // getSubDictionary(name) fail with a DictionaryError if the
        // sub-dictionary is the wrong type
        return exists(key);
    }
 
 
    DictPtr getSubDictionary(const std::string& name) const;
    // DictPtr getSubDictionary(const std::string& name) const;
 
    void validate(const Policy& pol, ValidationError* errs = 0) const;
 
    // C++ inheritance & function overloading limitations require us to
    // re-declare this here, even though an identical function is declared in
    // Policy
    int loadPolicyFiles(bool strict = true) { return loadPolicyFiles(boost::filesystem::path(), strict); }
 
    virtual int loadPolicyFiles(const boost::filesystem::path& repository, bool strict = true);
 
 
    const std::string getPrefix() const { return _prefix; }
    void setPrefix(const std::string& prefix) { _prefix = prefix; }
 
protected:
    static const boost::regex FIELDSEP_RE;
 
private:
    std::string _prefix;  // for recursive validation, eg "foo.bar."
};
 
template <typename T>
void Definition::validateBasic(const std::string& name, const Policy& policy, ValidationError* errs) const {
    validateBasic(name, policy.getValueArray<T>(name), errs);
}
 
template <typename T>
void Definition::validateBasic(const std::string& name, const std::vector<T>& value,
                               ValidationError* errs) const {
    ValidationError ve(LSST_EXCEPT_HERE);
    ValidationError* use = &ve;
    if (errs != 0) use = errs;
 
    validateCount(name, value.size(), use);
 
    for (typename std::vector<T>::const_iterator i = value.begin(); i != value.end(); ++i)
        validateBasic<T>(name, *i, -1, use);
 
    if (errs == 0 && ve.getParamCount() > 0) throw ve;
}
 
template <typename T>
void Definition::setDefaultIn(Policy& policy, const std::string& withName, ValidationError* errs) const {
    ValidationError ve(LSST_EXCEPT_HERE);
    ValidationError* use = (errs == 0 ? &ve : errs);
 
    if (_policy->exists("default")) {
        const std::vector<T> defs = _policy->getValueArray<T>("default");
        validateBasic(withName, defs, use);
        if (use->getErrors(withName) == ValidationError::OK) {
            policy.remove(withName);
            for (typename std::vector<T>::const_iterator i = defs.begin(); i != defs.end(); ++i)
                policy.addValue<T>(withName, *i);
        }
    }
 
    if (errs == 0 && ve.getParamCount() > 0) throw ve;
}
 
}  // namespace policy
}  // namespace pex
}  // namespace lsst
 
#endif  // LSST_PEX_POLICY_POLICY_H