type_record.hh

Go to the documentation of this file.

/*!
 *
 * Copyright (C) 2015 Technical University of Liberec.  All rights reserved.
 * 
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License version 3 as published by the
 * Free Software Foundation. (http://www.gnu.org/licenses/gpl-3.0.en.html)
 * 
 * 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.
 *
 * 
 * @file    type_record.hh
 * @brief   
 */
 
#ifndef TYPE_RECORD_HH_
#define TYPE_RECORD_HH_
 
#include "system/exceptions.hh"
//
 
#include <utility>                                     // for pair
#include "system/asserts.hh"                           // for Assert, ASSERT
namespace Input { class StorageBase; }
 
 
#include "type_base.hh"
 
#include <string>
#include <memory>
#include <vector>
#include <map>
 
namespace Input {
namespace Type {
 
 
using namespace std;
 
 
/** *********************************************************************************************************************************
 * @brief Class \p Input::Type::Default specifies default value of keys of a \p Input::Type::Record.
 *
 * It contains type of default value and possibly the value itself stored as \p std::string. Currently we distinguish four
 * cases:
 * - \b Default value given \b at \b declaration time, i.e. the default value is part of the \p Input::Type specification.
 *   This should be preferred way to give the default value since it can by documented as part of
 *   Record type specification.
 * - \b Default value given \b at \b read time, i.e. when you ask for the value through the Input::Record accessor. It should be used only
 *   if the default value is not constant, i.e. is taken from a global setting. In this case you should provide textual description
 *   where the default value comes from. Of course it could be difficult if the value is read on several places with different default values.
 * - \b No \b default value is given and input value is \b obligatory. An exception is thrown when the key is missing on the input.
 * - \b No \b default value is given and input value is \b optional.
 *
 *
 *
 * @ingroup input_types
 */
class Default {
    friend class Record;
    friend class OutputBase;
 
private:
    /// Possible types of default values.
    enum DefaultType {
        default_at_declaration,        ///< Default value given at declaration time.
        default_at_read_time,          ///< Some default value will be given when the key is read. The description of this value should be provided.
        no_default_optional_type,      ///< No default value, optional key. This is default type of the Default.
        no_default_obligatory_type     ///< No default value, obligatory key.
    };
public:
 
    /// Constructor with given default value (at declaration time)
    Default(const std::string & value);
 
    /// Hash of the Default specification, counted of type_ and value_.
    TypeBase::TypeHash content_hash() const;
 
    /**
     * @brief The factory function to make an default value that will be specified at the time when a key will be read.
     *
     * You have to provide a string with description of the default value used at the read time., e.g.
     * the key \p time_governer of an equation can specify default value as
     * @code
     *      Default::read_time("By default the global time governor is used.")
     * @endcode
     * To get the value of such key from the input you have to use non-throwing variant of the method
     * Input::Record::key, which returns the value through reference and allows checking presence of the key on the input.
     *
     * Example of usage:
     * @code
     *      some_record.declare_key("time_governor",TimeGovernor(),Default::optional(),"description");
     * @endcode
     */
    static Default read_time(const std::string & description)
    { return Default(default_at_read_time, description ); }
 
    /**
     * @brief The factory function to make an empty default value which is obligatory.
     *
     * This and following factory functions should be used instead of private constructors.
     *
     * Example of usage:
     * @code
     *      some_record.declare_key("some_key",Integer(),Default::obligatory(),"description");
     * @endcode
     */
    inline static Default obligatory()
    { return Default(no_default_obligatory_type, "OBLIGATORY"); }
 
    /**
     * @brief The factory function to make an empty default value which is optional.
     *
     * To get the value of such key from the input you have to use non-throwing variant of the method
     * Input::Record::key, which returns the value through reference and allows checking presence of the key on the input.
     *
     * Example of usage:
     * @code
     *      some_record.declare_key("some_key",Integer(),Default::optional(),"description");
     * @endcode
     */
    inline static Default optional()
    { return Default(no_default_optional_type, "OPTIONAL"); }
 
    /// Returns true if the default value is or will be available when someone tries to read the value.
    inline bool has_value_at_read_time() const
    { return (type_ == default_at_read_time); }
 
    /// Returns true if the default value is or will be available when someone tries to read the value.
    inline bool has_value_at_declaration() const
    { return (type_ == default_at_declaration); }
 
 
    /// Returns true if the key is obligatory and thus must be specified on input. No default value is given.
    inline bool is_obligatory() const
    { return (type_ == no_default_obligatory_type); }
 
    /// Returns true if the key is optional.
    inline bool is_optional() const
    { return (type_ == no_default_optional_type); }
 
    /// Returns stored value. Possibly empty string.
    inline const string & value() const
    { return (value_); }
 
    /// Compares values type_ of two Default objects.
    inline bool has_same_type(const Default &other) const
        {return type_ == other.type_; }
 
    /// Check validity of @p value_ using the JSON reader if default type is default_at_declaration.
    bool check_validity(std::shared_ptr<TypeBase> type) const;
 
    /// Return @p storage_, if storage_ is NULL, call check_validity method
    Input::StorageBase *get_storage(std::shared_ptr<TypeBase> type) const;
 
private:
    string value_;                          ///< Stored value.
    enum DefaultType type_;                 ///< Type of the Default.
    mutable Input::StorageBase *storage_;   ///< Storage of default value read by reader
 
    /// Forbids default constructor.
    Default();
 
    /// Constructor for other types then 'declaration'.
    Default(enum DefaultType type, const std::string &value);
};
 
 
class Abstract;
 
 
/** ******************************************************************************************************************************
 * @brief Record type proxy class.
 *
 * To keep consistency, we have to prevent copies of the actual Record data. Therefore this class is just a proxy  that
 * can be freely (and cheaply) copied.
 *
 * @ingroup input_types
 */
class Record : public TypeBase {
    friend class OutputBase;
    friend class Abstract;
 
public:
 
    /*
     * Exceptions specific to this class.
     */
    TYPEDEF_ERR_INFO( EI_Record, Record );
    TYPEDEF_ERR_INFO( EI_RecordName, const string);
    DECLARE_EXCEPTION( ExcRecordKeyNotFound, << "Key " << EI_KeyName::qval <<" not found in Record:\n" <<  EI_Record::val );
 
    /**
     *  @brief Structure for description of one key in record.
     *
     *  The members dflt_type_ and default have reasonable meaning only for
     *  type_ == Scalar
     */
    struct Key {
        unsigned int key_index;                ///< Position inside the record.
        string key_;                           ///< Key identifier.
        string description_;                   ///< Key description in context of particular Record type.
        std::shared_ptr<TypeBase> type_;       ///< Type of the key.
        Default default_;                      ///< Default, type and possibly value itself.
        /**
         * Is true if the key was created through copy_keys method, but not explicitly declared.
         * This is used to check duplicate key declaration while allowing overriding of copied keys.
         */
        bool derived;
        Input::Type::TypeBase::attribute_map attributes;               ///< Key specific attributes.
    };
 
    /// Public typedef of constant iterator into array of keys.
    typedef std::vector<struct Key>::const_iterator KeyIter;
 
    /// Default constructor. Empty handle.
    Record();
 
    /**
     * @brief Copy constructor.
     *
     * We allow only copies of non-empty records.
     */
    Record(const Record & other);
 
 
    /**
     * @brief Basic constructor.
     *
     * You have to provide \p type_name of the new declared Record type and its \p description.
     */
    Record(const string & type_name_in, const string & description);
 
 
    /**
     * @brief Implements @p TypeBase::content_hash.
     *
     * Hash is calculated by type name, description, auto conversion key, hash of keys and attributes.
     */
    virtual TypeHash content_hash() const  override;
 
 
    /**
     * @brief Method to derive new Record from an AbstractRecord @p parent.
     *
     * This register the @p parent to Record. Method checks if TYPE key of Record exists and ensures that Record
     * has assigned one parent only once.
     *
     * Usage of this method:
     *
     * - during creating Record before its closing (optional usage but recommended for better clarity)
     * - in \p Abstract::add_child provides bilateral binding between parent and child
     *
     * See also \p close and \p Abstract::add_child methods
     */
    virtual Record &derive_from(Abstract &parent);
 
    /**
     * @brief Copy keys from other record.
     *
     * Record @p other must be \p closed.
     */
    Record &copy_keys(const Record &other);
 
    /**
     * @brief Allows shorter input of the Record providing only value of the \p from_key given as the parameter.
     *
     * All other keys of the Record must have default values specified at declaration. This is checked when the
     * \p finish method is called.
     *
     * If the input reader come across the Record in declaration tree, but there is not 'record-like' input, it
     * save default values into storage tree and tries to match the input with the type of the \p from_key.
     */
    virtual Record &allow_auto_conversion(const string &from_key);
 
    /**
     * @brief Declares a new key of the Record.
     *
     * Key has name given by parameter @p key, the type given by target of pointer @p type,
     * default value by parameter @p default_value, and with given @p description.
     * The parameter @p type points to a descendant of TypeBase.
     * 
     * If the the function is called with the already existing key name @p key, an assert takes place,
     * Howeverf, if the the function is called with the same key name @p key in the derived Record,
     * the key is overwritten. 
     *
     * The optional attributes map may be provided, e.g.:
     *
     * declare_key("old_key", ..., { {Attribute::obsolete(), "Replaced by 'new_key'."} } )
     */
    Record &declare_key(const string &key, std::shared_ptr<TypeBase> type,
                            const Default &default_value, const string &description,
                            TypeBase::attribute_map key_attributes = TypeBase::attribute_map());
 
    /**
     * @brief Declares a new key of the Record.
     *
     * Key has name given by parameter @p key, the type given by parameter @p type,
     * default value by parameter @p default_value, and with given @p description.
     * The parameter @p type has a descendant of TypeBase.
     */
    template <class KeyType>
    Record &declare_key(const string &key, const KeyType &type,
                            const Default &default_value,
                            const string &description,
                            TypeBase::attribute_map key_attributes = TypeBase::attribute_map());
 
 
    /**
     * @brief Declares a new key of the Record.
     *
     * Same as previous method but without given default value (same as Default() - optional key )
     */
    template <class KeyType>
    Record &declare_key(const string &key, const KeyType &type,
                            const string &description,
                            TypeBase::attribute_map key_attributes = TypeBase::attribute_map());
 
 
    /**
     * @brief Close the Record for further declarations of keys.
     *
     * Adds Record to type repository (see @p TypeRepository::add_type) and provides correct bindings
     * between parent Abstract and child Record if Record is derived from one or more Abstracts.
     *
     * Mechanism of set parent to derived Record and child to parent Abstract is provided with
     * \p Abstract::add_child method.
     *
     * See also \p derive_from and \p Abstract::add_child methods
     */
    Record &close() const;
 
 
    /// Implements @p TypeBase::finish_status.
    FinishStatus finish_status() const override;
 
    /// Implements @p TypeBase::is_finished.
    bool is_finished() const override;
 
    /// Returns true if @p data_ is closed.
    bool is_closed() const override;
 
    /**
     * @brief Implements @p Type::TypeBase::type_name.
     *
     * Name corresponds to @p data->type_name_.
     */
    string type_name() const override;
    /// Override @p Type::TypeBase::class_name.
    virtual string class_name() const override;
 
    /// Class comparison and Record type name comparision.
    bool operator==(const TypeBase &other) const override;
 
    /**
     * @brief Interface to mapping key -> index in record.
     *
     * Returns index (in continuous array) for given key.
     *
     * Works also for unfinished Record.
     */
    inline unsigned int key_index(const string& key) const;
 
    /// Returns iterator to the key struct for given key string.
    inline KeyIter key_iterator(const string& key) const;
 
    /**
     * @brief Returns iterator to auto-conversion key.
     *
     * See Record::allow_auto_conversion. If the auto conversion is not allowed, returns end().
     */
    KeyIter auto_conversion_key_iter() const;
 
    /// Returns iterator to the key struct for given key string.
    inline bool has_key_iterator(const string& key, KeyIter &it) const;
 
    /**
     * @brief Container-like access to the keys of the Record.
     *
     * Returns iterator to the first key.
     */
    inline KeyIter begin() const;
 
    /**
     * @brief Container-like access to the keys of the Record.
     *
     * Returns iterator to the last key.
     */
    inline KeyIter end() const;
 
    /// Returns true if the Record contains key with given name.
    inline bool has_key(const string& key) const;
 
    /// Returns number of keys in the Record.
    inline unsigned int size() const;
 
    /**
     * @brief Finish declaration of the Record type.
     *
     * Checks if Record is closed and completes Record (check auto convertible key, parameters of generic types etc).
     */
    FinishStatus finish(FinishStatus finish_type = FinishStatus::regular_) override;
 
    /**
     * @brief Add TYPE key as obligatory.
     *
     * This method can't be used for derived record.
     */
    //Record &has_obligatory_type_key();
 
    Record &add_attribute(std::string key, TypeBase::json_string value);
 
    /// Implements @p TypeBase::make_instance.
    virtual MakeInstanceReturnType make_instance(std::vector<ParameterPair> vec = std::vector<ParameterPair>()) override;
 
    /// Create deep copy of Record (copy all data stored in shared pointers etc.)
    Record deep_copy() const;
 
    /**
     *  Mark the type to be root of a generic subtree.
     *  Such type can not appear in IST directly but only as the internal type
     *  of the Instance auxiliary object.
     */
    virtual Record &root_of_generic_subtree();
 
 
protected:
 
    /// Assertion for finished Type::Record.
    inline void finished_check() const {
        ASSERT(is_finished())(this->type_name()).error();
    }
 
    /// Auxiliary method that actually makes the copy of keys.
    void make_copy_keys(Record &origin);
 
    /**
     * @brief Declares a TYPE key of the Record.
     *
     * TYPE key must be declared as first key of Record.
     */
    //Record &declare_type_key();
 
    /**
     * @brief Set parent Abstract of Record.
     *
     * This method is created for correct functionality of generic types. It must be called
     * in Abstract::finish() and refill @p parent_vec_ vector of correct parents (for complete
     * mechanism of set parent and descendant see \p derive_from)
     */
    //const Record &add_parent(Abstract &parent) const;
 
    /**
     * @brief Set data of Instance of generic type.
     *
     * Called from make_instance method and set data of Record or its descendants.
     */
    ParameterMap set_instance_data(Record &rec,  std::vector<ParameterPair> vec);
 
    /**
     * @brief Internal data class.
     *
     * Stores data of the Record.
     */
    class RecordData  {
    public:
        /// Constructor
        RecordData(const string & type_name_in, const string & description);
 
        /**
         * @brief Declares a key and stores its type.
         *
         * The type parameter has to be finished at the call of declare_key().
         * If the parameter @p type_temporary is NULL, the parameter @p type provides pointer to
         * already finished type that will be assigned to the key. On the other hand, if @p type_temporary is not NULL,
         * only this raw pointer is stored and key is fully completed later through TypeBase::lazy_finish().
         */
        void declare_key(const string &key,
                         std::shared_ptr<TypeBase> type,
                         const Default &default_value,
                         const string &description,
                         TypeBase::attribute_map key_attributes);
 
        /// Returns iterator to auto-conversion key.
        Record::KeyIter auto_conversion_key_iter() const;
 
        /// Count hash of RecordData.
        void content_hash(TypeBase::TypeHash &seed) const;
 
        /// Database of valid keys
        std::map<KeyHash, unsigned int> key_to_index;
        /// Container-like access to the database of valid keys
        typedef std::map<KeyHash, unsigned int>::const_iterator key_to_index_const_iter;
 
        /// Keys in order as they where declared.
        std::vector<struct Key> keys;
 
        /// Description of the whole record type.
        const string description_;
        /// Name of the whole record type.
        const string type_name_;
 
        /// Permanent pointer to parent Abstract, necessary for output.
        std::vector< std::shared_ptr<Abstract> > parent_vec_;
 
        /// Record is finished when it is correctly derived (optional) and have correct shared pointers to types in all keys.
        FinishStatus finish_status_;
 
        /// If record is closed, we do not allow any further declare_key calls.
        bool closed_;
 
        /// True for derived records after make_derived.
        bool derived_;
 
        /**
         * @brief Index of auto convertible key.
         *
         * Initial value is = -1, when allow_auto_conversion is called we set this to 0.
         * Final value can be assigned just after possible inheritance copy of keys from parent Abstract.
         */
        int auto_conversion_key_idx;
 
        /// Name of key to use for auto conversion.
        std::string auto_conversion_key;
 
    };
 
    /// Data handle.
    std::shared_ptr<RecordData> data_;
};
 
 
/*********************************************************
 * Implementation
 */
 
 
 
 
inline unsigned int Record::key_index(const string& key) const
{
    KeyHash key_h = key_hash(key);
    RecordData::key_to_index_const_iter it = data_->key_to_index.find(key_h);
    if (it != data_->key_to_index.end()) return it->second;
    else
        THROW( ExcRecordKeyNotFound() << EI_KeyName(key) << EI_Record(*this) );
 
    return size();
}
 
 
 
inline Record::KeyIter Record::key_iterator(const string& key) const
{
 
    finished_check();
    return begin() + key_index(key);
}
 
 
 
inline bool Record::has_key_iterator(const string& key, KeyIter &it) const
{
    finished_check();
    KeyHash key_h = key_hash(key);
    RecordData::key_to_index_const_iter data_it = data_->key_to_index.find(key_h);
    if (data_it == data_->key_to_index.end()) {
        return false;
    } else {
        it = begin()+data_it->second;
        return true;
    }
}
 
 
 
inline Record::KeyIter Record::begin() const
{
    finished_check();
    return data_->keys.begin();
}
 
 
 
inline Record::KeyIter Record::end() const
{
    finished_check();
    return data_->keys.end();
}
 
 
 
inline bool Record::has_key(const string& key) const
{
    return key_iterator(key) != end();
}
 
 
 
inline unsigned int Record::size() const {
    ASSERT(is_closed())(this->type_name()).error();
    ASSERT_EQ(data_->keys.size(), data_->key_to_index.size()).error();
    return data_->keys.size();
}
 
 
 
 
 
 
} // closing namespace Type
} // closing namespace Input
 
 
 
 
#endif /* TYPE_RECORD_HH_ */