Varconf - STAGE Configuration System (c)1999-2003 1. Overview ----------- Varconf is a configuration system designed for the STAGE server. Varconf can parse configuration files, command-line arguments and environment variables. It supports callbacks and can store its configuration information in separate Config objects or in one global configuration instance. 2. Disclaimer ------------- None of the authors of this package nor anyone involved with the World Forge project is liable for any damages caused by the use of varconf. If your computer, you, or anyone around you self-combusts as a result of running this program, locate the nearest fire-extinguisher and don't call us. :) 3. Installation --------------- The libsigc++ callback library needs to be compiled and installed before compiling varconf. The library can be aquired at http://sourceforge.net/projects/libsigc/. This version requires SigC++ 1.2 series and pkgconfig. If you want to use SigC++ 1.0 series, or the legacy varconf-config script, please try a version of varconf from the 0.5 series. 3.1 Basic Installation ---------------------- cd forge/libs/varconf sh autogen.sh ./configure make make install This will place the libraries in /usr/local/lib/varconf and the header files in /usr/local/include/varconf 4. Definitions -------------- Configuration data refers to varconf's internal handling of section names, item names and item values. Each of these components has the same meaning as they would in any standard configuration file. Each of these components comes from configuration files, environment variables or command-line arguments. 4.1 Configuration Data ----------------------- The configuration is a database that consists of sections. Sections contain configuration items and each section has a section identifier. A section identifier is a lower case name, consisting of the characters 'a'-'z', '0'-'9', '-' and '_'. A configuration item consists of a name and a value. A configuration item name is a lower-case identifier, consisting of the characters 'a'-'z', '0'-'9', '-' and '_'. A configuration item value is a piece of information stored internally as a string value that may be represented as at least one of the configuration types. The configuration types include - boolean, i.e. 2 possible values, either true or false - integer, i.e. a positive or negative whole number - double, i.e. a double-precision positive or negative real number - string, i.e. a free-form string of characters including all characters in the ASCII character set from characters 32-255 4.2 Configuration File Format ----------------------------- A line in a configuration file can either be the start of a section, a configuration item or a comment. \n denotes the end of a line or the end of the file {ws} denotes any (0 or more) amount of whitespace {nm} denotes a name consisting of a-z, A-Z, 0-9, '_' or '-' {ac} denotes any character other than '"' {cm} denotes any character other than \n Syntax for section start: {ws}[{nm}]{ws}\n Syntax for configuration item: {ws}{nm}{ws}={ws}{nm{ws}\n or {ws}{nm}{ws}={ws}"{ac}"{ws}\n Syntax for comment: {ws}#{cm}\n Note that upper case characters (A-Z) in configuration item names and section names get converted to their lower case equivalents (a-z) automatically. A configuration item may be followed by a comment. Empty lines (lines with 0 or more whitespaces and no other characters) are ignored. 4.3 - Command-Line Arguments ---------------------------- A single command-line argument can be a short-form argument or short-form argument value, a long-form argument or ignored data. {sn} denotes a short-name of one of either 'a'-'z', 'A'-'Z' or '0'-'9'. {nm} denotes a name consisting of 'a'-'z', 'A'-'Z', '0'-'9', '_' or '-'. {ac} any character other than '"'. Syntax for short-form argument: -{sn} Syntax for short-form argument value: {nm} or "{ac}" Syntax for long-form argument: --{nm}:{nm}={nm} or --{section_name}:{item_name}={item_value} --{nm}:{nm}="{ac}" 4.4 - Environment Variables --------------------------- To allow varconf to input an environmental variable as configuration data, precede its name with a prefix and then specify that prefix when calling the function. ie: Variables: WF_ONE=Oh WF_TWO=Happy WF_THREE=Day Use prefix 'WF_' to retrieve the three variables as configuration data. They will be stored as items 'one', 'two' and 'three' respectively. 5. Library Usage ---------------- Varconf is not very verbose about errors. Typically, malformed config data is either completely ignored or converted into a compatible form. A typo won't crash the library but it might lead to some very odd configuration items. ie: Command-line argument: --section_name:: second colon treated as item name and converted to '_'; item '_' would be created without value under section "section_name" While this makes reporting typos to the user difficult, it makes parsing of configuration data more efficient in the library. A future solution to this might be the addition of warnings when the configuration data set method receives erroneous data. 5.1 Configuration Instance -------------------------- Configuration data can be stored in separate configuration objects or in a single global instance. Separate Objects: Config my_config; Global Instance: *Config::inst() Note that the method Config::inst() will automatically initialize the global data if not already created. 5.2 libsigc++ ------------- Varconf uses libsigc++ for its callback routines and error reporting. Please see the libsigc++ documentation for specific details on interacting with libsigc++ signals. Four libsigc++ signals are provided by varconf. .sig - callback method with no details. Indicates that configuration data has been changed but does not specify what has been changed. .sigv - callback method that reports section and item name that has been changed. Only useful when working with a single configuration instance.A .sigsv - callback method that reports section, item name and the address of the configuration object under which the change was made. Useful when using multiple configuration instances. .sige - reports error messages in a single string. 5.3 Configuration Files ----------------------- Varconf can read file-formed config data either directly from a file or from any input stream. It can also write configuration data directly to a file or to an output stream. To read from a file: config_object.readFromFile( file_name); To read from an input stream: config_object.parseStream( istream&); Note that this method may throw an error of type ParseError. See the parse_error.cpp file or the parse_error.h file for more information. To write to a file: config_object.writeToFile( file_name); To write to a stream: config_object.writeToStream( ostream&); 5.4 Command-line Arguments -------------------------- To parse a set of command-line arguments call the following method with the number of arguments and multi-dimension array of command-line arguments. config_object.getCmdline( int argc, char** argv); Note that before shortname arguments ('-a') can be used, each must be registered with a long name using the setParameterLookup method. ie: config_object.setParameterLookup( 'f', "foo", true); The last argument is a bool specifying whether the argument requires a value or not. If true, varconf will look at the command-line argument directly following the shortform argument to see if there is a value there. If false, varconf will store the argument with no value. Note that if a shortform argument is found but does not exist in the table, it will be ignored without warning. 5.5 Environment Variables ------------------------- To read in all environment variables with a specific prefix, call the following function with that prefix: config_object.getEnv( prefix); ie: config_object.getEnv( "WF_"); reads in all environment variables starting with "WF_"