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