/[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.3 by ksterker, Mon Aug 23 06:33:47 2004 UTC revision 1.4 by ksterker, Tue Mar 8 09:41:47 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               * @param valType type of given value.               */
178               */              cfg_choice (const string & value);
179              cfg_choice (const string & value);          
180                        /**
181              /**               * Add another valid option to chose from.
182               * Add another valid option to chose from.               * @param label name of the option as displayed by the GUI.
183               * @param label name of the option as displayed by the GUI.               * @param value actual value of the option.
184               * @param value actual value of the option.               */
185               */              void add (const string & label, const string & value);
186              void add (const string & label, const string & value);              
187                            /**
188              /**               * Methods for %configuration GUI
189               * Methods for %configuration GUI               */
190               */              //@{
191              //@{              /**
192              /**               * Set the current selection. Updates the current value.
193               * Set the current selection. Updates the current value.               * @param label name of the option as displayed by the GUI.
194               * @param label name of the option as displayed by the GUI.               */
195               */              void select (const string & label);
196              void select (const string & label);              
197                            /**
198              /**               * Get name of currently selected value.
199               * Get name of currently selected value.               * @return label for the selected value to display by GUI.
200               * @return label for the selected value to display by GUI.               */
201               */              string get_selection () const { return Selection; }
202              string get_selection () const { return Selection; }              
203                            /**
204              /**               * Get list of all available labels.
205               * Get list of all available labels.               * @return names of all settings known to this choice.
206               * @return names of all settings known to this choice.               */
207               */              vector<const char*> get_choices () const;
208              vector<const char*> get_choices () const;              //@}
209              //@}              
210                        private:
211          private:              /// label of the currently selected value
212              /// label of the currently selected value              string Selection;
213              string Selection;              /// valid values, each with a unique label
214              /// valid values, each with a unique label              map<string, string> Choices;
215              map<string, string> Choices;      };
216      };  
217        /**
218      /**       * This class provides access to the %configuration file.
219       * This class provides access to the %configuration file.       *
220       *       * It also provides meta information to be used by a graphical user interface.
221       * It also provides meta information to be used by a graphical user interface.       * This meta information needs to be set by each module that stores settings
222       * This meta information needs to be set by each module that stores settings       * in the %configuration file. Each module also needs to check the values returned
223       * in the %configuration file. Each module also needs to check the values returned       * by this class for sanity.
224       * by this class for sanity.       *
225       *       * To allow for a fully dynamic %configuration GUI, the %configuration file is
226       * To allow for a fully dynamic %configuration GUI, the %configuration file is       * divided into different sections. The GUI should create a different page for
227       * divided into different sections. The GUI should create a different page for       * each section. Further, each individual option has to be given meta information,
228       * each section. Further, each individual option has to be given meta information,       * telling the GUI about constraints and style to use for that option. Currently,
229       * telling the GUI about constraints and style to use for that option. Currently,       * the following types of options are available:
230       * the following types of options are available:       *
231       *       * - BOOL: this option allows exactly two settings. On/Off, True/False, etc.
232       * - BOOL: this option allows exactly two settings. On/Off, True/False, etc.       * - FREE: this option has no constraints; it allows the user to enter arbitrary values.
233       * - FREE: this option has no constraints; it allows the user to enter arbitrary values.       * - RANGE: this options accepts values out of given (integer) range.
234       * - RANGE: this options accepts values out of given (integer) range.       * - CHOICE: this option accepts values out of a predefined set of settings.
235       * - CHOICE: this option accepts values out of a predefined set of settings.       *
236       *       * High level methods allow retrieval of %configuration settings, cast to their
237       * High level methods allow retrieval of %configuration settings, cast to their       * expected type. Further methods allow to query for the names of available sections
238       * expected type. Further methods allow to query for the names of available sections       * and the options within a certain section. Finally, low level methods allow
239       * and the options within a certain section. Finally, low level methods allow       * access to the meta data kept by the %configuration class.
240       * access to the meta data kept by the %configuration class.       */
241       */      class configuration
242      class configuration      {
243      {          /**
244          /**           * Class representing one section of the %configuration file.
245           * Class representing one section of the %configuration file.           */
246           */          class cfg_section
247          class cfg_section          {
248          {              public:
249              public:                  /**
250                  /**                   * Destructor.
251                   * Destructor.                   */
252                   */                  ~cfg_section ();
253                  ~cfg_section ();                  
254                                    /**
255                  /**                   * Add option with given label to this section.
256                   * Add option with given label to this section.                   * @param label name of the option to add.
257                   * @param label name of the option to add.                   * @param option actual value with meta information.
258                   * @param option actual value with meta information.                   */
259                   */                  void add (const string & label, cfg_option *option);
260                  void add (const string & label, cfg_option *option);  
261                    /**
262                  /**                   * Remove option with given label from this section.
263                   * Remove option with given label from this section.                   * @param label name of the option to remove.
264                   * @param label name of the option to remove.                   * @return number of options left in the section.
265                   * @return number of options left in the section.                   */
266                   */                  int remove (const string & label);
267                  int remove (const string & label);                  
268                                    /**
269                  /**                   * Return option with the given label.
270                   * Return option with the given label.                   * @param label name of the option to retrieve.
271                   * @param label name of the option to retrieve.                   * @return pointer to option structure.
272                   * @return pointer to option structure.                   */
273                   */                  cfg_option *option (const string & label);
274                  cfg_option *option (const string & label);                  
275                                    /**
276                  /**                   * Return names of options available in that section.
277                   * Return names of options available in that section.                   * @param get_undef unless \c true, only list options with type != UNDEF
278                   * @param get_undef unless \c true, only list options with type != UNDEF                   * @return list of labels for options in that section.
279                   * @return list of labels for options in that section.                   */
280                   */                  vector<const char*> get_options (const bool & undef = false) const;
281                  vector<const char*> get_options (const bool & undef = false) const;                  
282                                private:
283              private:                  /// Options available in that section.
284                  /// Options available in that section.                  map<string, cfg_option*> Options;
285                  map<string, cfg_option*> Options;          };
286          };          
287                    public:
288          public:              /**
289              /**               * Destructor.
290               * Destructor.               */
291               */              ~configuration ();
292              ~configuration ();  
293                /**
294              /**               * @name Value retrieval
295               * @name Value retrieval               */
296               */              //@{
297              //@{              /**
298              /**               * Return the value of given option from given section as an integer. If the option
299               * Return the value of given option from given section as an integer. If the option               * does not exist yet, it will be created and assigned the given default value.
300               * does not exist yet, it will be created and assigned the given default value.               * @param section name of section.
301               * @param section name of section.               * @param option name of %configuration option.
302               * @param option name of %configuration option.               * @param value default value, in case the option does not exist yet.
303               * @param value default value, in case the option does not exist yet.               * @return %configuration setting.
304               * @return %configuration setting.               */
305               */              s_int32 get_int (const string & section, const string & option, const s_int32 & value);
306              s_int32 get_int (const string & section, const string & option, const s_int32 & value);              
307                            /**
308              /**               * Return the value of given option from given section as a double. If the option
309               * Return the value of given option from given section as a double. If the option               * does not exist yet, it will be created and assigned the given default value.
310               * does not exist yet, it will be created and assigned the given default value.               * @param section name of section.
311               * @param section name of section.               * @param option name of %configuration option.
312               * @param option name of %configuration option.               * @param value default value, in case the option does not exist yet.
313               * @param value default value, in case the option does not exist yet.               * @return %configuration setting.
314               * @return %configuration setting.               */
315               */              double get_double (const string & section, const string & option, const double & value);
316              double get_double (const string & section, const string & option, const double & value);              
317                            /**
318              /**               * Return the value of given option from given section as string. If the option
319               * Return the value of given option from given section as string. If the option               * does not exist yet, it will be created and assigned the given default value.
320               * does not exist yet, it will be created and assigned the given default value.               * @param section name of section.
321               * @param section name of section.               * @param option name of %configuration option.
322               * @param option name of %configuration option.               * @param value default value, in case the option does not exist yet.
323               * @param value default value, in case the option does not exist yet.               * @return %configuration setting.
324               * @return %configuration setting.               */
325               */              string get_string (const string & section, const string & option, const string & value);
326              string get_string (const string & section, const string & option, const string & value);              //@}
327              //@}              
328                            /**
329              /**               * @name loading / saving
330               * @name loading / saving               */
331               */              //@{
332              //@{              /**
333              /**               * Read %configuration from file. The exact location of the %configuration
334               * Read %configuration from file. The exact location of the %configuration               * file is determined by the configuration::create_filename method.
335               * file is determined by the configuration::create_filename method.               * @param name usually name of the game, whose %configuration to load.
336               * @param name usually name of the game, whose %configuration to load.               */
337               */              bool read (const string & name);
338              bool read (const string & name);              
339                            /**
340              /**               * Save %configuration to file. The exact location of the %configuration
341               * Save %configuration to file. The exact location of the %configuration               * file is determined by the configuration::create_filename method.
342               * file is determined by the configuration::create_filename method.               * @param name usually name of the game, whose %configuration to save.
343               * @param name usually name of the game, whose %configuration to save.               */
344               */              void write (const string & name) const;
345              void write (const string & name) const;              //@}
346              //@}              
347                            /**
348              /**               * @name Content retrieval
349               * @name Content retrieval               */
350               */              //@{
351              //@{              /**
352              /**               * Return names of available sections.
353               * Return names of available sections.               * @param get_undef unless \c true, only list sections with 'defined' options
354               * @param get_undef unless \c true, only list sections with 'defined' options               * @return list of section names.
355               * @return list of section names.               */
356               */              vector<const char*> get_sections (const bool & get_undef = false) const;
357              vector<const char*> get_sections (const bool & get_undef = false) const;  
358                /**
359              /**               * Return names of options available in given section.
360               * Return names of options available in given section.               * @param section name of section, whose entries to retrieve.
361               * @param section name of section, whose entries to retrieve.               * @param get_undef unless \c true, only list options with type != UNDEF
362               * @param get_undef unless \c true, only list options with type != UNDEF               * @return list of labels for options in given section.
363               * @return list of labels for options in given section.               */
364               */              vector<const char*> get_options (const string & section, const bool & get_undef = false) const;
365              vector<const char*> get_options (const string & section, const bool & get_undef = false) const;              //@}
366              //@}              
367                            /**
368              /**               * @name Low level access
369               * @name Low level access               */
370               */              //@{
371              //@{              /**
372              /**               * Return setting with given name from given section, cast to given option type.
373               * Return setting with given name from given section, cast to given option type.               * @param section name of section.
374               * @param section name of section.               * @param option name of %configuration option.
375               * @param option name of %configuration option.               * @param type type of %configuration option.
376               * @param type type of %configuration option.               * @return value and meta-information of requested option, or NULL on error.
377               * @return value and meta-information of requested option, or NULL on error.               */
378               */              cfg_option *option (const string & section, const string & option, const u_int8 & type) const;
379              cfg_option *option (const string & section, const string & option, const u_int8 & type) const;  
380                /**
381              /**               * Add or replace an option in the given section with the given value. If the
382               * Add or replace an option in the given section with the given value. If the               * value is \c NULL, remove the option instead.
383               * value is \c NULL, remove the option instead.               * @param section name of section.
384               * @param section name of section.               * @param option name of %configuration option.
385               * @param option name of %configuration option.               * @param value actual value and meta information of given option.
386               * @param value actual value and meta information of given option.               */
387               */              void add_option (const string & section, const string & option, cfg_option *value);
388              void add_option (const string & section, const string & option, cfg_option *value);  
389                /**
390              /**               * Remove an option in the given section. Removes the section too, if it is empty
391               * Remove an option in the given section. Removes the section too, if it is empty               * afterwards.
392               * afterwards.               * @param section name of section.
393               * @param section name of section.               * @param option name of %configuration option.
394               * @param option name of %configuration option.               */
395               */              void remove_option (const string & section, const string & option);
396              void remove_option (const string & section, const string & option);              //@}
397              //@}              
398                        private:
399          private:              /**
400              /**               * Calculate name of %configuration file from given string. On UNIX-like
401               * Calculate name of %configuration file from given string. On UNIX-like               * systems, the %configuration file will be $HOME/.adonthell/<name>.xml .
402               * systems, the %configuration file will be $HOME/.adonthell/<name>.xml .               * On Windows it will just be <name>.xml .
403               * On Windows it will just be <name>.xml .               * @param name filename for config file, usually the name of the game.
404               * @param name filename for config file, usually the name of the game.               */
405               */              string create_filename (const string & name) const;
406              string create_filename (const string & name) const;                      
407                                    /// sections available in %configuration file
408              /// sections available in %configuration file              map<string, cfg_section*> Sections;
409              map<string, cfg_section*> Sections;      };
410      };  }
411  }  
412    #endif // BASE_CONFIGURATION_H
 #endif // BASE_CONFIGURATION_H  

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

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