+--------------------------------------------------------------------+
|                                                                    |
|       parsecfg - a library for parsing a configuration file        |
|                                                                    |
|                 Copyright (C) 1999 Yuuki NINOMIYA                  |
|                                                                    |
+--------------------------------------------------------------------+

* Description

 parsecfg is a library for parsing a configuration file. Values
are stored in dynamically-allocated memory.


* Features

 + It supports a simple syntax format (PARAMETER = VALUE) and Windows-like
   INI file (or SAMBA's) using a section.

 + You can use numeric, boolean, string and linked-list stored strings
   as parameter types.

 + It can write configurations to a file.

 + The maximum number of parameters has no limitation.
 
 + Gettext is supported.


* How to use

 Install `parsecfg.c' and `parsecfg.h' to your program, and compile
them.


* Usage

 To parse the configuration file, you need to create and initialize
an array of cfgStruct's. Each element in the array describes a parameter
name and its type and address of variable stored got value (If type of
the cconfiguration file is INI, address of pointer of variable stored
got value).

 cfgStruct is declared the following in parsecfg.h.

typedef struct{
        char *parameterName;
        enum cfgValueType type;
        void *value;
} cfgStruct;

 `type' is the following.

CFG_BOOL ............. Record `1' if the value is `True' or `Yes' or `T' or `Y' `1'.
                       Record `0' if the value is `False' or `No' or `F' or `N' `0'.
                       They are not case sensitive.
CFG_INT .............. Record as `int'.
CFG_UINT ............. Record as `unsigned int'.
CFG_LONG ............. Record as `long'.
CFG_ULONG ............ Record as `unsigned long'.
CFG_STRING ........... Record as string.
CFG_STRING_LIST ...... Record as linked list for strings.
CFG_END .............. It flags the last element in the array.

 See the sample program (sample.c) for more details.
 Type `make' to compile the sample program.


* Usage of functions

 Include `parsecfg.h' before using the following functions.


void cfgSetFatalFunc(void (*f)(int,char *,int,char *));

 Set error handler by this function. Before calls this function,
uses default error handler in parsecfg.c.


int cfgParse(char *file,cfgStruct cfg[],int type);

 Call this function to parse the configuration file `file'.
`type' is type of the configuration file. If it is `CFG_SIMPLE',
parse the configuration file as simple format (PARAMETER = VALUE).
 If it is `CFG_INI', parse it as like Windows INI format (use section).
 Return value is the number of read sections (1,2,3,...).
If `type' is CFG_SIMPLE, always return 0.


int cfgDump(char *file,cfgStruct cfg[],cfgFileType type,int max);

 This function is for writing configurations to `file'.
 `type' is type of the configuration file.
 `max' is the number of sections. If `type' is `CFG_SIMPLE',
you can specify any number (Normally, you want to specify 0).


int cfgSectionNameToNumber(const char *name);

 This function is for converting section name to section number.
Return value is the section number (0,1,2,...).
 Section name is not case sensitive.
 If no match, return -1.


char *cfgSectionNumberToName(int num);

 This function is for convertion section number to section name.
If there is no relative section, return NULL.


* Format of a configuration file

 White space and tab are always skipped. If you use their special
character, quote with " or '.
 If you use ", quote with '. If you use ', quote with ".
 Lines that begin with the "#" character are safely ignored
as comments.

 Parameters are not case sensitive.
 Basic format is `PARAMETER = VALUE'.

-----------------------------------------------------
# PARAMETER = VALUE

ParameterINT    = 255
ParameterSTRING = GNU/Linux
QuotedString    = 'I pronounce "Linux" as "Linux".'
TRUEorFALSE     = FaLsE
-----------------------------------------------------


 If there is same parameters, and if value type is `CFG_STRING_LIST'
, all are stored, else the lastest is stored.

-----------------------------------------------------
# multiple parameters

ParameterINT = 255     # ignored
ParameterINT = 65535   # stored
ListString   = "Linux"   # stored
ListString   = "FreeBSD" # stored
-----------------------------------------------------


 If you want to specify multiple values to linked list,
the following format is available, as well.

-----------------------------------------------------
# for linked list

ListString = {
	Internet
	"Exploder"
}
-----------------------------------------------------


 If the configuration file type is `CFG_INI', quote
section name with '[' and ']'.

-----------------------------------------------------
# like Windows INI file

[Linux]
STRING = cool!
VALUE  = 99999999

[Winblows]
STRING = suck!
VALUE  = -99999999
-----------------------------------------------------

 See sample.cfg and sample.ini for more details.


* Limits

 None.


* Tested OS

 + Debian GNU/Linux 2.1
 + SuSE Linux 6.1


* Copying

 The copyright of this software belongs to Yuuki NINOMIYA.
 It is released 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.
 You can redistribute it and/or modify it under the GPL.


* Request to users

 I have an incomplete mastery of the English language, so please help
correct the text of the documents and messages in this program.
 Comments, suggestions, bug reports and patches are welcome.
Please mail them to me at the following address.


* Contact me

 e-mail : gm@smn.enjoy.ne.jp


* The latest version

 http://www.enjoy.ne.jp/~gm/program/parsecfg/


* My webpage

 Yuuki NINOMIYA's webpage
 http://www.enjoy.ne.jp/~gm/


-----------------------------------
Yuuki NINOMIYA <gm@smn.enjoy.ne.jp>

