nucleus/library/configuration/configurator.h

   1 #ifndef CONFIGURATOR_CLASS
   2 #define CONFIGURATOR_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : configurator                                                      *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/contracts.h>
  20 #include <structures/set.h>
  21 #include <structures/string_array.h>
  22 #include <structures/string_table.h>
  23
  24 namespace configuration {
  25
  26 //! Provides a base class for configuration repositories.
  27 /*!
  28   All items that can be stored are modelled as having an entry name and a
  29   value.  Groups of entries are stored in sections, in which the data
  30   usually have some relation to each other or share a common purpose.
  31 */
  32
  33 class configurator : public virtual basis::root_object
  34 {
  35 public:
  36   enum treatment_of_defaults { AUTO_STORE, RETURN_ONLY };
  37     //!< Governs how missing items are treated.
  38     /*!< When the default value is used in the get() method below, it can
  39     either be written to the ini file automatically (AUTO_STORE) or it can
  40     just be returned (RETURN_ONLY). */
  41
  42   configurator(treatment_of_defaults behavior = RETURN_ONLY) : _behavior(behavior) {}
  43   virtual ~configurator();
  44
  45   //! observes the behavior chosen for the load() function.
  46   treatment_of_defaults behavior() const { return _behavior; }
  47   //! modifies the behavior of the load() function.
  48   void behavior(treatment_of_defaults new_behavior) {
  49     _behavior = (new_behavior == RETURN_ONLY)? RETURN_ONLY : AUTO_STORE;
  50   }
  51
  52   virtual bool get(const basis::astring &section, const basis::astring &entry,
  53           basis::astring &found) = 0;
  54     //!< Retrieves an item from the configuration store.
  55     /*!< This retrieves a string into "found" that is listed in the "section"
  56     specified under the "entry" name.  if the string is not found, false is
  57     returned. */
  58
  59   virtual bool put(const basis::astring &section, const basis::astring &entry,
  60           const basis::astring &to_store) = 0;
  61     //!< Places an item into the configuration store.
  62     /*!< places an entry into the "section" under the "entry" name using the
  63     string "to_store".  if the storage was successful, true is returned.
  64     reasons for failure depend on the derived class implementations. */
  65
  66   bool store(const basis::astring &section, const basis::astring &entry,
  67           const basis::astring &to_store);
  68     //!< a synonym for put.
  69
  70   //! a synonym for get that implements the auto-store behavior.
  71   /*! if the behavior is set to auto-store, then the default value will be
  72   written when no value existed prior to the load() invocation. */
  73   basis::astring load(const basis::astring &section, const basis::astring &entry,
  74           const basis::astring &default_value);
  75
  76   //! stores an integer value from the configuration store.
  77   bool store(const basis::astring &section, const basis::astring &entry, int value);
  78   //! loads an integer value from the configuration store.
  79   int load(const basis::astring &section, const basis::astring &entry, int def_value);
  80
  81   // the various methods below that operate on sections and entries might not
  82   // be provided by all configurators.  that is why there are empty default
  83   // (or simplistic and slow) implementations provided below.
  84
  85   virtual void sections(structures::string_array &list);
  86     //!< retrieves the section names into "list".
  87
  88   void section_set(structures::string_set &list);
  89     //!< similar to above, but stores section names into a set.
  90     /*!< this never needs to be overridden; it's simply a set instead
  91     of an array.  the real sections method is above for string_array. */
  92
  93   virtual bool delete_entry(const basis::astring & formal(section),
  94           const basis::astring & formal(entry)) { return false; }
  95     //!< eliminates the entry specified by the "section" and "entry" name.
  96
  97   virtual bool delete_section(const basis::astring & formal(section) )
  98           { return false; }
  99     //!< whacks the entire "section" specified.
 100
 101   virtual bool section_exists(const basis::astring &section);
 102     //!< returns true if the "section" is found in the configurator.
 103     /*!< the default implementation is quite slow; if there is a swifter means
 104     for a particular type of configurator, then this should be overridden. */
 105
 106   virtual bool get_section(const basis::astring & formal(section),
 107           structures::string_table & formal(found) ) { return false; }
 108     //!< retrieves an entire "section", if supported by the derived object.
 109     /*!< the symbol table "found" gets the entries from the "section".
 110     see symbol_table.h for more details about string_tables.  true is
 111     returned if the section existed and its contents were put in "found". */
 112
 113   virtual bool put_section(const basis::astring & formal(section),
 114           const structures::string_table & formal(to_store) ) { return false; }
 115     //!< stores an entire "section" from the table in "to_store", if supported.
 116     /*!< if any entries already exist in the "section", then they are
 117     eliminated before the new entries are stored.  true is returned if the
 118     write was successful. */
 119
 120 private:
 121   treatment_of_defaults _behavior;  //!< records the treatment for defaults.
 122 };
 123
 124 } //namespace.
 125
 126 #endif
 127