## Conf4C Copyright 2004 Jason Barto <jpbarto@freeshell.org>
##
## Conf4C is free software; you can redistribute it and / or modify
## it under the terms of the GNU General Public License as 
## published by the Free Software Foundation; either version 2, or
## (at your option) any later version.
##
## Conf4C is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of 
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public Licese for more details.
##
## You should have received a copy of the GNU General Public License
## along with Conf4C; see the file COPYING.  If not, write to
## the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
## Boston MA 02111-1307 USA
##

## --INTRODUCTION-- ##
Conf4C is an attempt to create a configuration file
reading library (similar to log4j in the java world)
which can be utilized for the reading of non-xml 
configuration files.

This software is still in beta stages and requires 
testing to ensure that it will compile and operate on 
various platforms.  

In order to compile and test execute the following:

'make c4c_test'
./c4c_test

This should read the file 'apache.conf' and logically
display the files contents to the screen.  If it does
not you're welcome to fix the code and send me a patch 
(or you can just send me a constructive email 
whining to me about how it doesn't work).

If you are thinking of using this software as part of an
application you are developing: DON'T.  Like I said ... 
alpha ... exteremely alpha.  At least wait until version 
0.1 is released.

## --DESIGN-- ##
Now for those who have read this far perhaps you would like
to know where to begin to hack / fix / improve the software.
Conf4C is constructed of 5 classes:

ConfValue : contains a single name / value pair
ConfStor : contains a list of ConfValues
ConfSection : contains a list of ConfStors (all of the same section type)
ConfFile : contains a list of ConfSections
Conf4CFile : contains a ConfFile and other user specified variables

Conf4C is designed to parse a 2-level configuration file.  The first level
is the top or all-encompassing section.  The second level is made up of
specified sections which consist of a type and an identifier.  Sections
may not be embedded beyond the second level.  This is similar to the 
layout of the Apache Httpd configuration file (httpd.conf on most systems).

As an example:

name1 value1
name2 value2
<sec-type1 id1>
namea valuea
nameb valueb
</sec-type1>

...

Classes with a prefix of 'Conf*' denote lower level classes which should
not be accessed directly by normal users.  Classes and functions defined by
'Conf4C*' should be used by applications and normal users and should 
provide all necessary functionality.  To create and parse a file include
the following in your code:

Conf4CFile *c4cf;
c4cf = conf4c_file_new ("filename", 
			"comment-marker", 
			"name-value-delimiter", <delimiter-type>,
			<no of section types>,
			<no of section instances>,
			<no of section entries>,
			<no of base entries>);
conf4c_file_parse (c4cf);

The function conf4c_file_new takes 8 parameters, but only one is really 
necessary.  The filename is a string containing the name of the file to be
parsed for configuration information.  The comment-marker is a string 
which informs the parser of what initiates a comment; if this is set to
NULL the parser defaults to "#" indicating the start of a comment.

The name-value delimiter informs the parser of what separates a name
from a value.  As it is a string it can be something like "=" or can be
a long drawn out string such as " =equals= ".  If left NULL the parser
defaults to the string: " \t" (a space and a tab character).  Now a 
delimiter carries with it a modifier, the delimiter type.  At the moment
a delimiter can be of two types: strict (DELIM_STRICT) or lazy (DELIM_LAZY).
A strict delimiter will require that an exact match be made for a 
delimiter to be recognized.  Thus a delimiter of " == " will *NOT* match
with "name ==value", "name = value", or "name==value".  A lazy delimiter
however will use the delimiter string as a list of candidate delimiter
characters which can appear in any order and in any amount: i.e. the 
default value of " \t" will match "name   \t  value", "name value", and
"name\tvalue".  

The next 4 parameters are initial capacity indicators.  As most of the 
structs implementing Conf4C are mostly just vectors they each have
an initial capacity.  The first parameter informs the ConfFile 
object of how many ConfSections to allocate initially (each vector
grows as is necessary).  The second parameter identifies the number
of instances of each section type one expects to find in a configuration
file.  The third: the number of entries per section instance.  The
fourth: the number of top-level entries.  Note that exact selection of
these parameters is unnecessary as each vector grows to meet 
requirements.  Also, unless performance issues are experienced, it is
probably safe to simply set each parameter to '0' as reasonable default
values have been chosen and will probably suffice for most configuration
files.

Once the file has been parsed the data is ready to be extracted.  At the
moment this can be a slightly intensive task.  An example can be found
in the file c4ctest.c.  It contains code which dumps all data contained
within a Conf4CFile.  The same code can be used to iterate through all
captured values.

## --TODO-- ##
o Add proper configure script and Makefile
o Test on multiple platforms
o Add 'Conf4CReader' class

	


