Merge branch 'release-2.140.101'
[feisty_meow.git] / 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