1Varconf - STAGE Configuration System (c)1999-2003 2 3 41. Overview 5----------- 6Varconf is a configuration system designed for the STAGE server. 7Varconf can parse configuration files, command-line arguments and environment 8variables. It supports callbacks and can store its configuration information 9in separate Config objects or in one global configuration instance. 10 11 122. Disclaimer 13------------- 14None of the authors of this package nor anyone involved with the World Forge 15project is liable for any damages caused by the use of varconf. If your 16computer, you, or anyone around you self-combusts as a result of running this 17program, locate the nearest fire-extinguisher and don't call us. :) 18 19 203. Installation 21--------------- 22The libsigc++ callback library needs to be compiled and installed before 23compiling varconf. The library can be aquired at 24 25http://sourceforge.net/projects/libsigc/. 26 27This version requires SigC++ 1.2 series and pkgconfig. If you want to use 28SigC++ 1.0 series, or the legacy varconf-config script, please try a 29version of varconf from the 0.5 series. 30 31 323.1 Basic Installation 33---------------------- 34cd forge/libs/varconf 35sh autogen.sh 36./configure 37make 38make install 39 40This will place the libraries in /usr/local/lib/varconf 41and the header files in /usr/local/include/varconf 42 43 444. Definitions 45-------------- 46Configuration data refers to varconf's internal handling of section names, 47item names and item values. Each of these components has the same meaning 48as they would in any standard configuration file. Each of these components 49comes from configuration files, environment variables or command-line 50arguments. 51 52 534.1 Configuration Data 54----------------------- 55The configuration is a database that consists of sections. 56 57Sections contain configuration items and each section has a section identifier. 58 59A section identifier is a lower case name, consisting of the characters 60'a'-'z', '0'-'9', '-' and '_'. 61 62A configuration item consists of a name and a value. 63 64A configuration item name is a lower-case identifier, consisting of the 65characters 'a'-'z', '0'-'9', '-' and '_'. 66 67A configuration item value is a piece of information stored internally as a 68string value that may be represented as at least one of the configuration 69types. 70 71The configuration types include 72 - boolean, i.e. 2 possible values, either true or false 73 - integer, i.e. a positive or negative whole number 74 - double, i.e. a double-precision positive or negative real number 75 - string, i.e. a free-form string of characters including all characters in 76 the ASCII character set from characters 32-255 77 78 794.2 Configuration File Format 80----------------------------- 81A line in a configuration file can either be the start of a section, a 82configuration item or a comment. 83 84\n denotes the end of a line or the end of the file 85{ws} denotes any (0 or more) amount of whitespace 86{nm} denotes a name consisting of a-z, A-Z, 0-9, '_' or '-' 87{ac} denotes any character other than '"' 88{cm} denotes any character other than \n 89 90Syntax for section start: 91 92{ws}[{nm}]{ws}\n 93 94Syntax for configuration item: 95 96{ws}{nm}{ws}={ws}{nm{ws}\n 97 or 98{ws}{nm}{ws}={ws}"{ac}"{ws}\n 99 100Syntax for comment: 101 102{ws}#{cm}\n 103 104Note that upper case characters (A-Z) in configuration item names and section 105names get converted to their lower case equivalents (a-z) automatically. 106 107A configuration item may be followed by a comment. 108 109Empty lines (lines with 0 or more whitespaces and no other characters) are 110ignored. 111 112 1134.3 - Command-Line Arguments 114---------------------------- 115A single command-line argument can be a short-form argument or short-form 116argument value, a long-form argument or ignored data. 117 118{sn} denotes a short-name of one of either 'a'-'z', 'A'-'Z' or '0'-'9'. 119{nm} denotes a name consisting of 'a'-'z', 'A'-'Z', '0'-'9', '_' or '-'. 120{ac} any character other than '"'. 121 122Syntax for short-form argument: 123 124-{sn} 125 126Syntax for short-form argument value: 127 128{nm} 129 or 130"{ac}" 131 132Syntax for long-form argument: 133 134--{nm}:{nm}={nm} 135 or --{section_name}:{item_name}={item_value} 136--{nm}:{nm}="{ac}" 137 138 1394.4 - Environment Variables 140--------------------------- 141To allow varconf to input an environmental variable as configuration data, 142precede its name with a prefix and then specify that prefix when calling 143the function. ie: 144 145Variables: 146 WF_ONE=Oh 147 WF_TWO=Happy 148 WF_THREE=Day 149 150Use prefix 'WF_' to retrieve the three variables as configuration data. 151They will be stored as items 'one', 'two' and 'three' respectively. 152 153 1545. Library Usage 155---------------- 156Varconf is not very verbose about errors. Typically, malformed config data 157is either completely ignored or converted into a compatible form. 158A typo won't crash the library but it might lead to some very odd 159configuration items. ie: 160 161Command-line argument: 162 --section_name:: second colon treated as item name and converted to 163 '_'; item '_' would be created without value under 164 section "section_name" 165 166While this makes reporting typos to the user difficult, it makes parsing 167of configuration data more efficient in the library. A future solution to 168this might be the addition of warnings when the configuration data set method 169receives erroneous data. 170 171 1725.1 Configuration Instance 173-------------------------- 174Configuration data can be stored in separate configuration objects or in a 175single global instance. 176 177Separate Objects: 178 179 Config my_config; 180 181Global Instance: 182 183 *Config::inst() 184 185Note that the method Config::inst() will automatically initialize the 186global data if not already created. 187 188 1895.2 libsigc++ 190------------- 191Varconf uses libsigc++ for its callback routines and error reporting. 192Please see the libsigc++ documentation for specific details on interacting 193with libsigc++ signals. 194 195Four libsigc++ signals are provided by varconf. 196 197 .sig - callback method with no details. Indicates that configuration data 198 has been changed but does not specify what has been changed. 199 200 .sigv - callback method that reports section and item name that 201 has been changed. Only useful when working with a single 202 configuration instance.A 203 204 .sigsv - callback method that reports section, item name and the address of 205 the configuration object under which the change was made. Useful 206 when using multiple configuration instances. 207 208 .sige - reports error messages in a single string. 209 210 2115.3 Configuration Files 212----------------------- 213Varconf can read file-formed config data either directly from a file or from 214any input stream. It can also write configuration data directly to a file 215or to an output stream. 216 217To read from a file: 218 219 config_object.readFromFile( file_name); 220 221To read from an input stream: 222 223 config_object.parseStream( istream&); 224 225 Note that this method may throw an error of type ParseError. 226 See the parse_error.cpp file or the parse_error.h file for more information. 227 228 229To write to a file: 230 231 config_object.writeToFile( file_name); 232 233To write to a stream: 234 235 config_object.writeToStream( ostream&); 236 237 2385.4 Command-line Arguments 239-------------------------- 240To parse a set of command-line arguments call the following method with the 241number of arguments and multi-dimension array of command-line arguments. 242 243 config_object.getCmdline( int argc, char** argv); 244 245Note that before shortname arguments ('-a') can be used, each must be 246registered with a long name using the setParameterLookup method. ie: 247 248 config_object.setParameterLookup( 'f', "foo", true); 249 250The last argument is a bool specifying whether the argument requires a value 251or not. If true, varconf will look at the command-line argument directly 252following the shortform argument to see if there is a value there. If false, 253varconf will store the argument with no value. 254 255Note that if a shortform argument is found but does not exist in the table, 256it will be ignored without warning. 257 258 2595.5 Environment Variables 260------------------------- 261To read in all environment variables with a specific prefix, call the 262following function with that prefix: 263 264 config_object.getEnv( prefix); 265 266 ie: config_object.getEnv( "WF_"); reads in all environment variables 267 starting with "WF_" 268