parameter_model.h

Go to the documentation of this file.

/* Author(s)     : Francois Mauger <mauger@lpccaen.in2p3.fr>
 * Creation date : 2014-05-11
 * Last modified : 2016-10-31
 *
 * Copyright (C) 2014-2016 Francois Mauger <mauger@lpccaen.in2p3.fr>
 *
 * 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 GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc. 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 *
 * Description:
 *
 *   The model of a configuration variant parameter.
 *
 */

#ifndef DATATOOLS_CONFIGURATION_PARAMETER_MODEL_H
#define DATATOOLS_CONFIGURATION_PARAMETER_MODEL_H

// Standard library:
#include <string>
#include <set>
#include <vector>
#include <map>

// This project (Bayeux/datatools)
#include <datatools/i_tree_dump.h>
#include <datatools/enriched_base.h>
#include <datatools/types.h>
#include <datatools/configuration/utils.h>
#include <datatools/object_configuration_description.h>
#include <datatools/integer_range.h>
#include <datatools/real_range.h>

namespace datatools {

  // Forward declaration:
  class multi_properties;

  namespace configuration {

    // Forward declaration:
    class variant_model;
    class variant_physical;
    class variant_repository;

    class parameter_model : public datatools::enriched_base
    {
    public:

      enum rst_flags {
        PRINT_RST_NO_TITLE = datatools::bit_mask::bit00,
        PRINT_RST_NO_DESC  = datatools::bit_mask::bit01
      };

      virtual bool is_name_valid(const std::string & name_) const;

      typedef std::map<std::string, variant_physical> variant_dict_type;

      typedef std::map<std::string, std::string> group_dict_type;

      enum mutability_type {
        MUTABILITY_UNDEFINED = 0, 
        MUTABILITY_FIXED     = 1, 
        MUTABILITY_VARIABLE  = 2, 
        MUTABILITY_DEFAULT   = MUTABILITY_VARIABLE  
      };

      static std::string label_from_mutability(const mutability_type);

      static mutability_type mutability_from_label(const std::string &);

      enum variable_mode_type {
        VARIABLE_MODE_UNDEFINED =   0, 
        VARIABLE_MODE_FREE      =   1, 
        VARIABLE_MODE_ENUM      =   2, 
        VARIABLE_MODE_INTERVAL  =   4, 
        VARIABLE_MODE_DEFAULT   = 255  
      };

      static std::string label_from_variable_mode(const variable_mode_type);

      static variable_mode_type variable_mode_from_label(const std::string &);

      static const std::string & aux_prefix();

      enum path_io_type {
        PATH_UNDEFINED    = 0x0, 
        PATH_INPUT        = 0x1, 
        PATH_OUTPUT       = 0x2, 
        PATH_INPUT_OUTPUT = 0x3  
      };

      static std::string label_from_path_io(const path_io_type);

      static path_io_type path_io_from_label(const std::string &);

      struct base_enum_metadata
        : public datatools::i_tree_dumpable
      {
      public:

        enum ctor_flags {
          CTOR_NO_GROUP_SUPPORT = datatools::bit_mask::bit00 
        };

        base_enum_metadata(uint32_t flags_ = 0);

        bool has_documentation() const;

        void set_documentation(const std::string &);

        const std::string & get_documentation() const;

        bool has_variants() const;

        bool has_variant(const std::string & variant_name_) const;

        void add_variant(const std::string & variant_name_);

        void remove_variant(const std::string & variant_name_);

        void remove_variants();

        const std::set<std::string> & get_variants() const;

        bool has_group() const;

        void set_group(const std::string & group_name_);

        const std::string & get_group() const;

        bool match_group(const std::string & group_name_) const;

        void initialize(const datatools::properties & config_,
                        parameter_model & parmod_);

        void reset();

        virtual void tree_dump(std::ostream & out_ = std::clog,
                               const std::string & title_ = "",
                               const std::string & indent_ = "",
                               bool inherit_ = false) const;

        enum rst_flags {
          PRINT_RST_NO_DOC = datatools::bit_mask::bit00
        };

        void print_rst(std::ostream & out_,
                       const std::string & indent_ = "",
                       const uint32_t flags_ = 0) const;

        bool has_group_support() const;

      protected:

        std::string _documentation;      
        std::set<std::string> _variants; 
        std::string _group;              

      private:
        bool _no_group_support_ = false;
      };

      struct boolean_enum_value_metadata : public base_enum_metadata  {
        boolean_enum_value_metadata();
      };

      struct integer_enum_value_metadata : public base_enum_metadata  {
      };
      typedef std::map<int, integer_enum_value_metadata> integer_enum_dict_type;

      struct integer_range_enum_metadata : public base_enum_metadata {
      };
      typedef std::map<integer_range, integer_range_enum_metadata> integer_range_enum_dict_type;

      struct real_enum_value_metadata : public base_enum_metadata  {
      };
      typedef std::map<double, real_enum_value_metadata> real_enum_dict_type;

      struct string_enum_value_metadata : public base_enum_metadata {
      };
      typedef std::map<std::string, string_enum_value_metadata> string_enum_dict_type;

      struct real_range_enum_metadata : public base_enum_metadata {
      };
      typedef std::map<real_range, real_range_enum_metadata> real_range_enum_dict_type;

      parameter_model();

      virtual ~parameter_model();

      bool has_documentation() const;

      void set_documentation(const std::string & documentation_);

      const std::string & get_documentation() const;

      bool has_type() const;

      void set_type(const basic_type type_);

      basic_type get_type() const;

      bool is_boolean() const;

      bool is_integer() const;

      bool is_real() const;

      bool is_string() const;

      bool is_path() const;

      void set_path(const bool is_path_);

      void reset_path();

      bool has_path_io() const;

      void set_path_io(const path_io_type path_io_);

      bool is_path_input() const;

      bool is_path_output() const;

      bool is_path_input_output() const;

      void set(const basic_type type_, const variable_mode_type variable_mode_);

      bool has_variable_mode() const;

      void set_variable_mode(const variable_mode_type variable_mode_);

      variable_mode_type get_variable_mode() const;

      bool has_mutability() const;

      void set_mutability(const mutability_type mutability_);

      mutability_type get_mutability() const;

      bool is_fixed() const;

      bool is_variable() const;

      bool has_fixed_value() const;

      bool get_fixed_boolean() const;

      int get_fixed_integer() const;

      double get_fixed_real() const;

      const std::string & get_fixed_string() const;

      void set_fixed_boolean(const bool value_);

      void set_fixed_integer(const int value_);

      void set_fixed_real(const double value_);

      void set_fixed_string(const std::string & value_);

      bool is_free() const;

      bool is_interval() const;

      bool is_enumeration() const;

      bool has_integer_domain() const;

      void set_integer_domain(const integer_range & ir_);

      const integer_range & get_integer_domain() const;

      bool has_real_domain() const;

      // Set real interval
      void set_real_domain(const real_range & ir_);

      const real_range & get_real_domain() const;

      bool has_default_value() const;

      void reset_default_value();

      void set_default_boolean(const bool value_);

      bool get_default_boolean() const;

      void set_default_integer(const int value_);

      int get_default_integer() const;

      bool has_real_precision() const;

      void set_real_precision(const double prec_);

      void reset_real_precision();

      double get_real_precision() const;

      double get_real_effective_precision() const;

      void set_default_real(const double value_);

      double get_default_real() const;

      void set_default_string(const std::string & value_);

      const std::string & get_default_string() const;

      bool has_real_unit_label() const;

      void set_real_unit_label(const std::string & unit_label_);

      const std::string & get_real_unit_label() const;

      bool has_real_preferred_unit() const;

      void set_real_preferred_unit(const std::string & value_);

      const std::string & get_real_preferred_unit() const;

      bool fetch_real_display_unit(std::string & display_unit_symbol_, double & unit_value_) const;

      //
      // Boolean
      //

      void set_enumerated_boolean_value_metadata(const bool value_, const boolean_enum_value_metadata & metadata_);

      const boolean_enum_value_metadata & get_enumerated_boolean_value_metadata(const bool value_) const;

      boolean_enum_value_metadata & grab_enumerated_boolean_value_metadata(const bool value_);

      bool enumerated_boolean_value_has_group(const bool value_) const;

      const std::string & get_enumerated_boolean_value_group(const bool value_) const;

      void build_list_of_enumerated_boolean_groups(std::set<std::string> & groups_) const;

      void build_list_of_enumerated_boolean_values_in_group(const std::string & group_,
                                                            std::set<bool> & values_) const;

      void build_list_of_enumerated_boolean_values(std::set<bool> & values_) const;

      //
      // Integer enumerated
      //

      void add_enumerated_integer_value(const int value_,
                                        const integer_enum_value_metadata & metadata,
                                        const bool default_ = false);

      void add_enumerated_integer_value(const int value_,
                                        const bool default_ = false);

      bool has_enumerated_integer_value(const int value_) const;

      void fetch_integer_enumeration(std::vector<int> & values_) const;

      bool enumerated_integer_value_has_group(const int value_) const;

      const std::string & get_enumerated_integer_value_group(const int value_) const;

      const integer_enum_value_metadata & get_enumerated_integer_value_metadata(const int value_) const;

      integer_enum_value_metadata & grab_enumerated_integer_value_metadata(const int value_);

      void build_list_of_enumerated_integer_groups(std::set<std::string> & groups_) const;

      void build_list_of_enumerated_integer_values_in_group(const std::string & group_,
                                                            std::set<int> & values_) const;

      void build_list_of_enumerated_integer_values(std::set<int> & values_) const;

      //
      // Real enumerated
      //

      bool has_enumerated_real_value(const double value_) const;

      bool find_enumerated_real_value(const double value_, double & enum_value_) const;

      void add_enumerated_real_value(const double value_,
                                     const real_enum_value_metadata & metadata_,
                                     const bool default_ = false);

      void add_enumerated_real_value(const double value_,
                                     const bool default_ = false);

      bool enumerated_real_value_has_group(const double value_) const;

      const std::string & get_enumerated_real_value_group(const double value_) const;

      const real_enum_value_metadata & get_enumerated_real_value_metadata(const double value_) const;

      real_enum_value_metadata & grab_enumerated_real_value_metadata(const double value_);

      void fetch_real_enumeration(std::vector<double> & values_) const;

      void build_list_of_enumerated_real_groups(std::set<std::string> & groups_) const;

      void build_list_of_enumerated_real_values_in_group(const std::string & group_,
                                                         std::set<double> & values_) const;

      void build_list_of_enumerated_real_values(std::set<double> & values_) const;

      //
      // String enumerated
      //

      bool has_enumerated_string_value(const std::string & value_) const;

      void add_enumerated_string_value(const std::string & value_,
                                       const string_enum_value_metadata & metadata_,
                                       const bool default_ = false);

      bool enumerated_string_value_has_group(const std::string & value_) const;

      const std::string & get_enumerated_string_value_group(const std::string & value_) const;

      void add_enumerated_string_value(const std::string & value_,
                                       const bool default_ = false);

      const string_enum_value_metadata & get_enumerated_string_value_metadata(const std::string & value_) const;

      string_enum_value_metadata & grab_enumerated_string_value_metadata(const std::string & value_);

      void build_list_of_enumerated_string_groups(std::set<std::string> & groups_) const;

      void build_list_of_enumerated_string_values_in_group(const std::string & group_,
                                                           std::set<std::string> & values_) const;

      void build_list_of_enumerated_string_values(std::set<std::string> & values_) const;

      //
      // Group

      bool has_groups() const;

      bool has_group(const std::string & group_name_) const;

      void add_group(const std::string & group_name_,
                     const std::string & doc_ = "");

      void build_set_of_groups(std::set<std::string> & group_) const;

      //
      // Variant
      //

      bool has_variant(const std::string & variant_name_) const;

      void add_variant(const std::string &    variant_name_,
                       const vm_handle_type & variant_model_handle_,
                       const std::string &    description_ = "");

      void remove_variant(const std::string & variant_name_);

      const std::string & get_variant_description(const std::string & variant_name_) const;

      const variant_model & get_variant_model(const std::string & variant_name_) const;

      vm_handle_type get_variant_model_handle(const std::string & variant_name_) const;

      // Variant associations:

      void associate_variant_to_boolean(const bool value_, const std::string & variant_name_);

      void associate_variant_to_integer(const int value_, const std::string & variant_name_);

      void associate_variant_to_real(const double value_, const std::string & variant_name_);

      void associate_variant_to_string(const std::string & value_,
                                       const std::string & variant_name_);

      //
      // Management
      //

      bool is_initialized() const;

      void initialize(const properties & setup_, model_item_dict_type & items_);

      void initialize_standalone(const properties &);

      void initialize_simple();

      void reset();

      virtual void tree_dump(std::ostream & out_ = std::clog,
                             const std::string & title_ = "",
                             const std::string & indent_ = "",
                             bool inherit_ = false) const;

      bool is_boolean_valid(const bool) const;

      bool is_integer_valid(const int) const;

      bool is_real_valid(const double) const;

      bool is_string_valid(const std::string &) const;

      const variant_dict_type & get_variants() const;

      bool find_variants_associated_to_boolean(const bool value_, std::set<std::string> & variants_) const;

      bool find_variants_associated_to_integer(const int value_, std::set<std::string> & variants_) const;

      bool find_variants_associated_to_real(const double value_, std::set<std::string> & variants_) const;

      bool find_variants_associated_to_string(const std::string & value_, std::set<std::string> & variants_) const;

      //
      // Ranges of interest (available for integer and real parameters)
      //

      void associate_variant_to_integer_range(const integer_range & range_,
                                              const std::string & variant_name_);

      void associate_variant_to_real_range(const real_range & range_,
                                           const std::string & variant_name_);

      void add_integer_range(const integer_range &, const integer_range_enum_metadata &);

      void add_real_range(const real_range &, const real_range_enum_metadata &);

      const integer_range_enum_dict_type & get_integer_ranges() const;

      const real_range_enum_dict_type & get_real_ranges() const;

      //
      // Miscellaneous
      //

      static void init_ocd(datatools::object_configuration_description &);

      void print_rst(std::ostream & out_,
                     const std::string & indent_ = "",
                     const uint32_t flags_ = 0) const;

    protected:

      void _set_variable_mode(const variable_mode_type);

      void _set_default();

      void _parse_string_enumeration_from_csv_file(const std::string & csv_filename_,
                                                   const char csv_separator_ = ':',
                                                   const char csv_subseparator_ = ';',
                                                   const std::string & value_regex_ = "",
                                                   const std::string & group_regex_ = "");

    private:

      void _update_real_domain_();

    private:

      bool        _initialized_;   
      std::string _documentation_; 

      // Basic traits:
      basic_type          _type_;              
      mutability_type     _mutability_;        
      bool                _has_default_value_; 
      bool                _has_fixed_value_;   
      variable_mode_type  _variable_mode_;     
      variant_dict_type   _variants_;          
      group_dict_type     _groups_;            

      // Boolean property:
      bool _boolean_default_;      
      bool _boolean_fixed_;        
      boolean_enum_value_metadata _false_metadata_; 
      boolean_enum_value_metadata _true_metadata_;  

      // Integer property:
      integer_range _integer_domain_; 
      int _integer_default_;          
      int _integer_fixed_;            
      integer_enum_dict_type _integer_enumeration_; 
      integer_range_enum_dict_type _integer_ranges_; 

      // Real property:
      std::string _real_unit_label_;     
      std::string _real_preferred_unit_; 
      double _real_precision_;  
      double _real_default_;    
      double _real_fixed_;      
      real_range _real_domain_; 
      real_enum_dict_type _real_enumeration_; 
      real_range_enum_dict_type _real_ranges_; 

      // String property:
      std::string  _string_default_; 
      std::string  _string_fixed_;   
      bool         _path_;           
      path_io_type _path_io_;        
      string_enum_dict_type _string_enumeration_; 

    };

  }  // end of namespace configuration

}  // end of namespace datatools

// OCD support:
#include <datatools/ocd_macros.h>

DOCD_CLASS_DECLARATION(datatools::configuration::parameter_model)

#endif // DATATOOLS_CONFIGURATION_PARAMETER_MODEL_H

// Local Variables: --
// mode: c++ --
// c-file-style: "gnu" --
// tab-width: 2 --
// End: --