Varconf - STAGE Configuration System (c)1999-2001


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/.  Varconf requires version 1.0.0 or greater of libsigc++.


3.1 Basic Installation
----------------------
cd forge/libs/varconf
sh autogen.sh (will automatically execute ./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 either a configuration file, 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 Callbacks
-------------
Varconf uses libsigc++ for its callback routines.  Please see the libsigc++ documentation for specific details on interacting with these callback methods.

Two callback signals are available, .sig and .sigv .  .sig is a non-verbose callback - it returns no value and simply informs the application that a change has been made.  .sigv is verbose and returns both the section and name (in that order) of the configuration item that has been changed.  


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 ParseError.cc file or the ParseError.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_"





