Configuration.h

Go to the documentation of this file.
00001 //
00002 // Configuration.h
00003 //
00004 // NAME
00005 // 
00006 // reads the configuration file and manages it in memory.
00007 //
00008 // SYNOPSIS
00009 // 
00010 // #include <Configuration.h>
00011 // 
00012 // Configuration config;
00013 // 
00014 // ConfigDefault config_defaults = {
00015 //   { "verbose", "true" },
00016 //   { 0, 0 }
00017 // };
00018 //
00019 // config.Defaults(config_defaults);
00020 //
00021 // config.Read("/spare2/myconfig") ;
00022 //
00023 // config.Add("sync", "false");
00024 //
00025 // if(config["sync"]) ...
00026 // if(config.Value("rate") < 50) ...
00027 // if(config.Boolean("sync")) ...
00028 // 
00029 // DESCRIPTION
00030 //
00031 // The primary purpose of the <b>Configuration</b> class is to parse
00032 // a configuration file and allow the application to modify the internal
00033 // data structure produced. All values are strings and are converted by the 
00034 // appropriate accessors. For instance the <b>Boolean</b> method will 
00035 // return numerical true (not zero) if the string either contains 
00036 // a number that is different from zero or the string <i>true</i>.
00037 //
00038 // The <i>ConfigDefaults</i> type is a structure of two char pointers:
00039 // the name of the configuration attribute and it's value. The end of
00040 // the array is the first entry that contains a null pointer instead of
00041 // the attribute name. Numerical
00042 // values must be in strings. For instance:
00043 // <pre>
00044 // ConfigDefault* config_defaults = {
00045 //   { "wordlist_compress", "true" },
00046 //   { "wordlist_page_size", "8192" },
00047 //   { 0, 0 }
00048 // };
00049 // </pre>
00050 // The additional
00051 // fields of the <b>ConfigDefault</b> are purely informative. 
00052 //
00053 // FILE FORMAT
00054 //
00055 // The configuration file is a plain ASCII text file. Each line in
00056 // the file is either a comment or an attribute.
00057 // Comment lines are blank lines or lines that start with a '#'.
00058 // Attributes consist of a variable name and an associated
00059 // value:
00060 //
00061 // <pre>
00062 // &lt;name&gt;:&lt;whitespace&gt;&lt;value&gt;&lt;newline&gt;
00063 // </pre>
00064 //
00065 // The &lt;name&gt; contains any alphanumeric character or
00066 // underline (_) The &lt;value&gt; can include any character
00067 // except newline. It also cannot start with spaces or tabs since
00068 // those are considered part of the whitespace after the colon. It
00069 // is important to keep in mind that any trailing spaces or tabs
00070 // will be included.
00071 //
00072 // It is possible to split the &lt;value&gt; across several
00073 // lines of the configuration file by ending each line with a
00074 // backslash (\). The effect on the value is that a space is
00075 // added where the line split occurs.
00076 //
00077 // A configuration file can include another file, by using the special
00078 // &lt;name&gt;, <tt>include</tt>. The &lt;value&gt; is taken as
00079 // the file name of another configuration file to be read in at
00080 // this point. If the given file name is not fully qualified, it is
00081 // taken relative to the directory in which the current configuration
00082 // file is found. Variable expansion is permitted in the file name.
00083 // Multiple include statements, and nested includes are also permitted.
00084 //
00085 // <pre>
00086 // include: common.conf
00087 // </pre>
00088 // 
00089 //
00090 // END
00091 //
00092 // Part of the ht://Dig package   <http://www.htdig.org/>
00093 // Copyright (c) 1999, 2000, 2001 The ht://Dig Group
00094 // For copyright details, see the file COPYING in your distribution
00095 // or the GNU General Public License version 2 or later 
00096 // <http://www.gnu.org/copyleft/gpl.html>
00097 //
00098 // $Id: Configuration_8h-source.html,v 1.1 2008/06/08 10:12:53 sebdiaz Exp $
00099 //
00100 
00101 #ifndef _Configuration_h_
00102 #define _Configuration_h_
00103 
00104 #include "Dictionary.h"
00105 #include "htString.h"
00106 
00107 struct ConfigDefaults
00108 {
00109   char  *name;                  // Name of the attribute
00110   char  *value;                 // Default value
00111   char  *type;                  // Type of the value (string, integer, boolean)
00112   char  *programs;              // Whitespace separated list of programs/modules using this attribute
00113   char  *block;                 // Configuration block this can be used in (can be blank)
00114   char  *version;               // Version that introduced the attribute
00115   char  *category;              // Attribute category (to split documentation)
00116   char  *example;               // Example usage of the attribute (HTML)
00117   char  *description;           // Long description of the attribute (HTML)
00118 };
00119 
00120 
00121 class Configuration : public Object
00122 {
00123 public:
00124     //-
00125     // Constructor
00126     //
00127     Configuration();
00128 #ifndef SWIG
00129     Configuration(const Configuration& config);
00130 #endif /* SWIG */
00131     //-
00132     // Destructor
00133     //
00134     ~Configuration() {}
00135 
00136     //
00137     // Adding and deleting items to and from the Configuration
00138     //
00139 #ifndef SWIG
00140     //-
00141     // Add configuration item <b>str</b> to the configuration. The value
00142     // associated with it is undefined.
00143     //
00144     void                Add(const String& str);
00145 #endif /* SWIG */
00146     //-
00147     // Add configuration item <b>name</b> to the configuration and associate
00148     // it with <b>value</b>.
00149     //
00150     void                Add(const String& name, const String& value);
00151     void                AddParsed(const String& name, const String& value);
00152     //-
00153     // Remove the <b>name</b> from the configuration.
00154     //
00155     int                 Remove(const String& name);
00156 
00157     //-
00158     // Let the Configuration know how to parse name value pairs.
00159     // Each character of string <b>s</b> is a valid separator between
00160     // the <i>name</i> and the <i>value.</i>
00161     //
00162     void                NameValueSeparators(const String& s);
00163         
00164     //-
00165     // Read name/value configuration pairs from the file <b>filename</b>.
00166     //
00167     virtual int         Read(const String& filename);
00168 
00169     //-
00170     // Return the value of configuration attribute <b>name</b> as a
00171     // <i>String</i>.
00172     //
00173     const String        Find(const String& name) const;
00174 #ifndef SWIG
00175     //-
00176     // Alias to the <b>Find</b> method.
00177     //
00178     const String        operator[](const String& name) const;
00179 #endif /* SWIG */
00180     //-
00181     // Return the value associated with the configuration attribute
00182     // <b>name</b>, converted to integer using the atoi(3) function.
00183     // If the attribute is not found in the configuration and 
00184     // a <b>default_value</b> is provided, return it. 
00185     //
00186     int         Value(const String& name, int default_value = 0) const;
00187     //-
00188     // Return the value associated with the configuration attribute
00189     // <b>name</b>, converted to double using the atof(3) function.
00190     // If the attribute is not found in the configuration and 
00191     // a <b>default_value</b> is provided, return it. 
00192     //
00193     double      Double(const String& name, double default_value = 0) const;
00194     //-
00195     // Return 1 if the value associated to <b>name</b> is 
00196     // either <b>1, yes</b> or <b>true</b>.
00197     // Return 0 if the value associated to <b>name</b> is 
00198     // either <b>0, no</b> or <b>false</b>.
00199     //
00200     int         Boolean(const String& name, int default_value = 0) const;
00201     Object     *Get_Object(char *name);
00202 
00203     //-
00204     // Load configuration attributes from the <i>name</i> and <i>value</i>
00205     // members of the <b>array</b> argument. 
00206     //
00207     void                Defaults(const ConfigDefaults *array);
00208 
00209 protected:
00210     Dictionary          dcGlobalVars;
00211     String              separators;
00212     int                 allow_multiple;
00213 };
00214 
00215 #endif

Generated on Sun Jun 8 10:56:39 2008 for GNUmifluz by  doxygen 1.5.5