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;

    // 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 lsst::daf::base::Citizen {
public:

    Definition(const std::string& paramName = "")
        : lsst::daf::base::Citizen(typeid(*this)), _type(Policy::UNDETERMINED), 
        _name(paramName), _policy(), _wildcard(false)
    {
        _policy.reset(new Policy());
    }

    Definition(const std::string& paramName, const Policy::Ptr& defn) 
        : lsst::daf::base::Citizen(typeid(*this)), _type(Policy::UNDETERMINED), 
          _name(paramName), _policy(defn), _wildcard(false)
    { }

    Definition(const Policy::Ptr& defn) 
        : lsst::daf::base::Citizen(typeid(*this)), _type(Policy::UNDETERMINED), 
          _name(), _policy(defn), _wildcard(false)
    { }

    Definition(const Definition& that) 
        : lsst::daf::base::Citizen(typeid(*this)), _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;
}

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

#endif // LSST_PEX_POLICY_POLICY_H