/[adonthell]/adonthell/src/base/configuration.h
ViewVC logotype

Diff of /adonthell/src/base/configuration.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.4 by ksterker, Tue Mar 8 09:41:47 2005 UTC revision 1.5 by ksterker, Fri Jun 3 17:29:13 2005 UTC
# Line 1  Line 1 
1  /*  /*
2     $Id$     $Id$
3    
4     Copyright (C) 2004 Kai Sterker <kaisterker@linuxgames.com>     Copyright (C) 2004 Kai Sterker <kaisterker@linuxgames.com>
5     Part of the Adonthell Project http://adonthell.linuxgames.com     Part of the Adonthell Project http://adonthell.linuxgames.com
6    
7     Adonthell is free software; you can redistribute it and/or modify     Adonthell is free software; you can redistribute it and/or modify
8     it under the terms of the GNU General Public License as published by     it under the terms of the GNU General Public License as published by
9     the Free Software Foundation; either version 2 of the License, or     the Free Software Foundation; either version 2 of the License, or
10     (at your option) any later version.     (at your option) any later version.
11    
12     Adonthell is distributed in the hope that it will be useful,     Adonthell is distributed in the hope that it will be useful,
13     but WITHOUT ANY WARRANTY; without even the implied warranty of     but WITHOUT ANY WARRANTY; without even the implied warranty of
14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15     GNU General Public License for more details.     GNU General Public License for more details.
16    
17     You should have received a copy of the GNU General Public License     You should have received a copy of the GNU General Public License
18     along with Adonthell; if not, write to the Free Software     along with Adonthell; if not, write to the Free Software
19     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20  */  */
21    
22  /**  /**
23   * @file        base/configuration.h   * @file        base/configuration.h
24   * @author      Kai Sterker <kaisterker@linuxgames.com>   * @author      Kai Sterker <kaisterker@linuxgames.com>
25   *   *
26   * @brief       Provides access to %configuration file.   * @brief       Provides access to %configuration file.
27   */   */
28    
29  #ifndef BASE_CONFIGURATION_H  #ifndef BASE_CONFIGURATION_H
30  #define BASE_CONFIGURATION_H  #define BASE_CONFIGURATION_H
31    
32  #include <vector>  #include <vector>
33  #include <string>  #include <string>
34  #include <map>  #include <map>
35    
36  #include "base/types.h"  #include "base/types.h"
37    
38  using std::string;  using std::string;
39  #ifndef SWIG  #ifndef SWIG
40  using std::vector;  using std::vector;
41  using std::map;  using std::map;
42  #endif  #endif
43    
44  namespace base  namespace base
45  {  {
46      /**      /**
47       * A single %configuration option, storing a value of arbitrary type. Base class       * A single %configuration option, storing a value of arbitrary type. Base class
48       * for a number of %configuration options that impose some constraints on the       * for a number of %configuration options that impose some constraints on the
49       * value stored.       * value stored.
50       */       */
51      class cfg_option      class cfg_option
52      {      {
53          public:          public:
54              /**              /**
55               * Types of %configuration options.               * Types of %configuration options.
56               */               */
57              enum              enum
58              {              {
59                  UNDEF, BOOL, FREE, RANGE, CHOICE                  UNDEF, BOOL, FREE, RANGE, CHOICE
60              };                          };            
61    
62              /**              /**
63               * Create a new option.               * Create a new option.
64               * @param value value of option.               * @param value value of option.
65               * @param type type of %configuration option.               * @param type type of %configuration option.
66               */               */
67              cfg_option (const string & value, const u_int8 & type = cfg_option::UNDEF);              cfg_option (const string & value, const u_int8 & type = cfg_option::UNDEF);
68                            
69              /**              /**
70               * Destructor.               * Destructor.
71               */               */
72              virtual ~cfg_option () { }              virtual ~cfg_option () { }
73                            
74              /**              /**
75               * Get value of this %configuration option.               * Get value of this %configuration option.
76               * @return value as a string.               * @return value as a string.
77               */               */
78              string value ();              string value ();
79                            
80              /**              /**
81               * Change value of this option.               * Change value of this option.
82               * @param value new value.               * @param value new value.
83               */               */
84              virtual void set_value (const string & value);              virtual void set_value (const string & value);
85                    
86              /**              /**
87               * Return the comment attached to this option.               * Return the comment attached to this option.
88               * @return description of %configuration option.               * @return description of %configuration option.
89               */               */
90              string comment () const { return Comment; }              string comment () const { return Comment; }
91                            
92              /**              /**
93               * Attach a comment attached to this option.               * Attach a comment attached to this option.
94               * @param comment description of %configuration option.               * @param comment description of %configuration option.
95               */               */
96              void set_comment (const string & comment) { Comment = comment; }              void set_comment (const string & comment) { Comment = comment; }
97                            
98              /**              /**
99               * Get type of %configuration option. This can be used by the %configuration               * Get type of %configuration option. This can be used by the %configuration
100               * GUI to generate fitting widgets for this %configuration option.               * GUI to generate fitting widgets for this %configuration option.
101               * @return type of %configuration option (configuration::UNDEF if unknown).               * @return type of %configuration option (configuration::UNDEF if unknown).
102               */               */
103              u_int8 type () const { return Type; }              u_int8 type () const { return Type; }
104    
105          protected:          protected:
106              /// Actual value of the %configuration option              /// Actual value of the %configuration option
107              string Value;              string Value;
108    
109          private:          private:
110              /// Description of this option              /// Description of this option
111              string Comment;              string Comment;
112                            
113              /// Type of the %configuration option (FREE, BOOL, RANGE, CHOICE ...)              /// Type of the %configuration option (FREE, BOOL, RANGE, CHOICE ...)
114              u_int8 Type;              u_int8 Type;
115      };      };
116    
117      /**      /**
118       * Restricts an option to a certain range. Only available for integer options.       * Restricts an option to a certain range. Only available for integer options.
119       */       */
120      class cfg_range : public cfg_option      class cfg_range : public cfg_option
121      {      {
122          public:          public:
123              /**              /**
124               * Create a new range with given value as default setting.               * Create a new range with given value as default setting.
125               * @param value initial setting               * @param value initial setting
126               */               */
127              cfg_range (const string & value);              cfg_range (const string & value);
128                            
129              /**              /**
130               * Specify boundries of range.               * Specify boundries of range.
131               * @param min minimum of range.               * @param min minimum of range.
132               * @param max maximum of range.               * @param max maximum of range.
133               */               */
134              void set_range (const u_int16 & min, const u_int16 & max);              void set_range (const u_int16 & min, const u_int16 & max);
135                            
136              /**              /**
137               * Change value of this option, within the allowed range.               * Change value of this option, within the allowed range.
138               * @param value new value.               * @param value new value.
139               */               */
140              void set_value (const string & value);              void set_value (const string & value);
141    
142              /**              /**
143               * Return left border of range.               * Return left border of range.
144               * @return minimum of range.               * @return minimum of range.
145               */               */
146              u_int16 min () const { return Min; }              u_int16 min () const { return Min; }
147                            
148              /**              /**
149               * Return right border of range.               * Return right border of range.
150               * @return maximum of range.               * @return maximum of range.
151               */               */
152              u_int16 max () const { return Max; }              u_int16 max () const { return Max; }
153                            
154          private:          private:
155              /**              /**
156               * Make sure the options value is within the options range.               * Make sure the options value is within the options range.
157               * Changes the value, if neccessary.               * Changes the value, if neccessary.
158               */               */
159              void validate ();              void validate ();
160                            
161              /// minimum value of range              /// minimum value of range
162              u_int16 Min;              u_int16 Min;
163              /// maximum value of range              /// maximum value of range
164              u_int16 Max;              u_int16 Max;
165      };      };
166            
167      /**      /**
168       * Restricts an option to a given number of choices. That is, valid settings can be       * Restricts an option to a given number of choices. That is, valid settings can be
169       * picked from a list of predefined options.       * picked from a list of predefined options.
170       */       */
171      class cfg_choice : public cfg_option      class cfg_choice : public cfg_option
172      {      {
173          public:          public:
174              /**              /**
175               * Create a new choice.               * Create a new choice.
176               * @param value value of option.               * @param value value of option.
177               */               */
178              cfg_choice (const string & value);              cfg_choice (const string & value);
179                    
180              /**              /**
181               * Add another valid option to chose from.               * Add another valid option to chose from.
182               * @param label name of the option as displayed by the GUI.               * @param label name of the option as displayed by the GUI.
183               * @param value actual value of the option.               * @param value actual value of the option.
184               */               */
185              void add (const string & label, const string & value);              void add (const string & label, const string & value);
186                            
187              /**              /**
188               * Methods for %configuration GUI               * Methods for %configuration GUI
189               */               */
190              //@{              //@{
191              /**              /**
192               * Set the current selection. Updates the current value.               * Set the current selection. Updates the current value.
193               * @param label name of the option as displayed by the GUI.               * @param label name of the option as displayed by the GUI.
194               */               */
195              void select (const string & label);              void select (const string & label);
196                            
197              /**              /**
198               * Get name of currently selected value.               * Get name of currently selected value.
199               * @return label for the selected value to display by GUI.               * @return label for the selected value to display by GUI.
200               */               */
201              string get_selection () const { return Selection; }              string get_selection () const { return Selection; }
202                            
203              /**              /**
204               * Get list of all available labels.               * Get list of all available labels.
205               * @return names of all settings known to this choice.               * @return names of all settings known to this choice.
206               */               */
207              vector<const char*> get_choices () const;              vector<const char*> get_choices () const;
208              //@}              //@}
209                            
210          private:          private:
211              /// label of the currently selected value              /// label of the currently selected value
212              string Selection;              string Selection;
213              /// valid values, each with a unique label              /// valid values, each with a unique label
214              map<string, string> Choices;              map<string, string> Choices;
215      };      };
216    
217      /**      /**
218       * This class provides access to the %configuration file.       * This class provides access to the %configuration file.
219       *       *
220       * It also provides meta information to be used by a graphical user interface.       * It also provides meta information to be used by a graphical user interface.
221       * This meta information needs to be set by each module that stores settings       * This meta information needs to be set by each module that stores settings
222       * in the %configuration file. Each module also needs to check the values returned       * in the %configuration file. Each module also needs to check the values returned
223       * by this class for sanity.       * by this class for sanity.
224       *       *
225       * To allow for a fully dynamic %configuration GUI, the %configuration file is       * To allow for a fully dynamic %configuration GUI, the %configuration file is
226       * divided into different sections. The GUI should create a different page for       * divided into different sections. The GUI should create a different page for
227       * each section. Further, each individual option has to be given meta information,       * each section. Further, each individual option has to be given meta information,
228       * telling the GUI about constraints and style to use for that option. Currently,       * telling the GUI about constraints and style to use for that option. Currently,
229       * the following types of options are available:       * the following types of options are available:
230       *       *
231       * - BOOL: this option allows exactly two settings. On/Off, True/False, etc.       * - BOOL: this option allows exactly two settings. On/Off, True/False, etc.
232       * - FREE: this option has no constraints; it allows the user to enter arbitrary values.       * - FREE: this option has no constraints; it allows the user to enter arbitrary values.
233       * - RANGE: this options accepts values out of given (integer) range.       * - RANGE: this options accepts values out of given (integer) range.
234       * - CHOICE: this option accepts values out of a predefined set of settings.       * - CHOICE: this option accepts values out of a predefined set of settings.
235       *       *
236       * High level methods allow retrieval of %configuration settings, cast to their       * High level methods allow retrieval of %configuration settings, cast to their
237       * expected type. Further methods allow to query for the names of available sections       * expected type. Further methods allow to query for the names of available sections
238       * and the options within a certain section. Finally, low level methods allow       * and the options within a certain section. Finally, low level methods allow
239       * access to the meta data kept by the %configuration class.       * access to the meta data kept by the %configuration class.
240       */       */
241      class configuration      class configuration
242      {      {
243          /**          /**
244           * Class representing one section of the %configuration file.           * Class representing one section of the %configuration file.
245           */           */
246          class cfg_section          class cfg_section
247          {          {
248              public:              public:
249                  /**                  /**
250                   * Destructor.                   * Destructor.
251                   */                   */
252                  ~cfg_section ();                  ~cfg_section ();
253                                    
254                  /**                  /**
255                   * Add option with given label to this section.                   * Add option with given label to this section.
256                   * @param label name of the option to add.                   * @param label name of the option to add.
257                   * @param option actual value with meta information.                   * @param option actual value with meta information.
258                   */                   */
259                  void add (const string & label, cfg_option *option);                  void add (const string & label, cfg_option *option);
260    
261                  /**                  /**
262                   * Remove option with given label from this section.                   * Remove option with given label from this section.
263                   * @param label name of the option to remove.                   * @param label name of the option to remove.
264                   * @return number of options left in the section.                   * @return number of options left in the section.
265                   */                   */
266                  int remove (const string & label);                  int remove (const string & label);
267                                    
268                  /**                  /**
269                   * Return option with the given label.                   * Return option with the given label.
270                   * @param label name of the option to retrieve.                   * @param label name of the option to retrieve.
271                   * @return pointer to option structure.                   * @return pointer to option structure.
272                   */                   */
273                  cfg_option *option (const string & label);                  cfg_option *option (const string & label);
274                                    
275                  /**                  /**
276                   * Return names of options available in that section.                   * Return names of options available in that section.
277                   * @param get_undef unless \c true, only list options with type != UNDEF                   * @param get_undef unless \c true, only list options with type != UNDEF
278                   * @return list of labels for options in that section.                   * @return list of labels for options in that section.
279                   */                   */
280                  vector<const char*> get_options (const bool & undef = false) const;                  vector<const char*> get_options (const bool & undef = false) const;
281                                    
282              private:              private:
283                  /// Options available in that section.                  /// Options available in that section.
284                  map<string, cfg_option*> Options;                  map<string, cfg_option*> Options;
285          };          };
286                    
287          public:          public:
288              /**              /**
289               * Destructor.               * Destructor.
290               */               */
291              ~configuration ();              ~configuration ();
292    
293              /**              /**
294               * @name Value retrieval               * @name Value retrieval
295               */               */
296              //@{              //@{
297              /**              /**
298               * Return the value of given option from given section as an integer. If the option               * Return the value of given option from given section as an integer. If the option
299               * does not exist yet, it will be created and assigned the given default value.               * does not exist yet, it will be created and assigned the given default value.
300               * @param section name of section.               * @param section name of section.
301               * @param option name of %configuration option.               * @param option name of %configuration option.
302               * @param value default value, in case the option does not exist yet.               * @param value default value, in case the option does not exist yet.
303               * @return %configuration setting.               * @return %configuration setting.
304               */               */
305              s_int32 get_int (const string & section, const string & option, const s_int32 & value);              s_int32 get_int (const string & section, const string & option, const s_int32 & value);
306                            
307              /**              /**
308               * Return the value of given option from given section as a double. If the option               * Return the value of given option from given section as a double. If the option
309               * does not exist yet, it will be created and assigned the given default value.               * does not exist yet, it will be created and assigned the given default value.
310               * @param section name of section.               * @param section name of section.
311               * @param option name of %configuration option.               * @param option name of %configuration option.
312               * @param value default value, in case the option does not exist yet.               * @param value default value, in case the option does not exist yet.
313               * @return %configuration setting.               * @return %configuration setting.
314               */               */
315              double get_double (const string & section, const string & option, const double & value);              double get_double (const string & section, const string & option, const double & value);
316                            
317              /**              /**
318               * Return the value of given option from given section as string. If the option               * Return the value of given option from given section as string. If the option
319               * does not exist yet, it will be created and assigned the given default value.               * does not exist yet, it will be created and assigned the given default value.
320               * @param section name of section.               * @param section name of section.
321               * @param option name of %configuration option.               * @param option name of %configuration option.
322               * @param value default value, in case the option does not exist yet.               * @param value default value, in case the option does not exist yet.
323               * @return %configuration setting.               * @return %configuration setting.
324               */               */
325              string get_string (const string & section, const string & option, const string & value);              string get_string (const string & section, const string & option, const string & value);
326              //@}              //@}
327                            
328              /**              /**
329               * @name loading / saving               * @name loading / saving
330               */               */
331              //@{              //@{
332              /**              /**
333               * Read %configuration from file. The exact location of the %configuration               * Read %configuration from file. The exact location of the %configuration
334               * file is determined by the configuration::create_filename method.               * file is determined by the configuration::create_filename method.
335               * @param name usually name of the game, whose %configuration to load.               * @param name usually name of the game, whose %configuration to load.
336               */               */
337              bool read (const string & name);              bool read (const string & name);
338                            
339              /**              /**
340               * Save %configuration to file. The exact location of the %configuration               * Save %configuration to file. The exact location of the %configuration
341               * file is determined by the configuration::create_filename method.               * file is determined by the configuration::create_filename method.
342               * @param name usually name of the game, whose %configuration to save.               * @param name usually name of the game, whose %configuration to save.
343               */               */
344              void write (const string & name) const;              void write (const string & name) const;
345              //@}              //@}
346                            
347              /**              /**
348               * @name Content retrieval               * @name Content retrieval
349               */               */
350              //@{              //@{
351              /**              /**
352               * Return names of available sections.               * Return names of available sections.
353               * @param get_undef unless \c true, only list sections with 'defined' options               * @param get_undef unless \c true, only list sections with 'defined' options
354               * @return list of section names.               * @return list of section names.
355               */               */
356              vector<const char*> get_sections (const bool & get_undef = false) const;              vector<const char*> get_sections (const bool & get_undef = false) const;
357    
358              /**              /**
359               * Return names of options available in given section.               * Return names of options available in given section.
360               * @param section name of section, whose entries to retrieve.               * @param section name of section, whose entries to retrieve.
361               * @param get_undef unless \c true, only list options with type != UNDEF               * @param get_undef unless \c true, only list options with type != UNDEF
362               * @return list of labels for options in given section.               * @return list of labels for options in given section.
363               */               */
364              vector<const char*> get_options (const string & section, const bool & get_undef = false) const;              vector<const char*> get_options (const string & section, const bool & get_undef = false) const;
365              //@}              //@}
366                            
367              /**              /**
368               * @name Low level access               * @name Low level access
369               */               */
370              //@{              //@{
371              /**              /**
372               * Return setting with given name from given section, cast to given option type.               * Return setting with given name from given section, cast to given option type.
373               * @param section name of section.               * @param section name of section.
374               * @param option name of %configuration option.               * @param option name of %configuration option.
375               * @param type type of %configuration option.               * @param type type of %configuration option.
376               * @return value and meta-information of requested option, or NULL on error.               * @return value and meta-information of requested option, or NULL on error.
377               */               */
378              cfg_option *option (const string & section, const string & option, const u_int8 & type) const;              cfg_option *option (const string & section, const string & option, const u_int8 & type) const;
379    
380              /**              /**
381               * Add or replace an option in the given section with the given value. If the               * Add or replace an option in the given section with the given value. If the
382               * value is \c NULL, remove the option instead.               * value is \c NULL, remove the option instead.
383               * @param section name of section.               * @param section name of section.
384               * @param option name of %configuration option.               * @param option name of %configuration option.
385               * @param value actual value and meta information of given option.               * @param value actual value and meta information of given option.
386               */               */
387              void add_option (const string & section, const string & option, cfg_option *value);              void add_option (const string & section, const string & option, cfg_option *value);
388    
389              /**              /**
390               * Remove an option in the given section. Removes the section too, if it is empty               * Remove an option in the given section. Removes the section too, if it is empty
391               * afterwards.               * afterwards.
392               * @param section name of section.               * @param section name of section.
393               * @param option name of %configuration option.               * @param option name of %configuration option.
394               */               */
395              void remove_option (const string & section, const string & option);              void remove_option (const string & section, const string & option);
396              //@}              //@}
397                            
398          private:          private:
399              /**              /**
400               * Calculate name of %configuration file from given string. On UNIX-like               * Calculate name of %configuration file from given string. On UNIX-like
401               * systems, the %configuration file will be $HOME/.adonthell/<name>.xml .               * systems, the %configuration file will be $HOME/.adonthell/<name>.xml .
402               * On Windows it will just be <name>.xml .               * On Windows it will just be <name>.xml .
403               * @param name filename for config file, usually the name of the game.               * @param name filename for config file, usually the name of the game.
404               */               */
405              string create_filename (const string & name) const;              string create_filename (const string & name) const;
406                                            
407              /// sections available in %configuration file              /// sections available in %configuration file
408              map<string, cfg_section*> Sections;              map<string, cfg_section*> Sections;
409      };      };
410  }  }
411    
412  #endif // BASE_CONFIGURATION_H  #endif // BASE_CONFIGURATION_H

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26