  parsecfg - a library for parsing a configuration file
  Yuuki NINOMIYA <gm@debian.or.jp>
  $Date: 2002/02/20 13:51:00 $

  This document is the user's manual for parsecfg library.  It doesn't
  seem to be a good document, so you should also read source codes of a
  sample program and the library. :-p
  ______________________________________________________________________

  Table of Contents


  1. Introduction
     1.1 Overview
     1.2 Features
     1.3 Requirements

  2. Usage
     2.1 Installation
     2.2 Preparation
     2.3 Function References
     2.4 Format of Configuration File

  3. License
  4. Tested Operating Systems
  5. Limitations
  6. Known Bugs
  7. Future Plans
  8. FAQ
  9. Request to Users
  10. Author
  11. The Latest Release
  12. The Latest Source Code
  13. Related Links
  14. Acknowledgement
     14.1 Borrowed Code / Library
     14.2 Contributions of Code or Document
     14.3 Translations
     14.4 Other

  15. History


  ______________________________________________________________________

  1.  Introduction



  1.1.  Overview

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



  1.2.  Features


  o  Support for a simple syntax format (PARAMETER = VALUE) and Windoze
     INI-like (or SAMBA's) file using a section.

  o  Support for numeric, boolean, string and linked-list stored strings
     as parameter type.


  o  A function for fetching value from configuration file.

  o  Writing configurations to a file.

  o  The maximum number of parameters has no limitation.

  o  Support for internationalization of messages by GNU gettext.
     Japanese, Polish and French translations are available now.



  1.3.  Requirements

  Parsecfg requires an ANSI C compiler.  I tested this program with gcc
  version 2.95.4.

  I strongly recommend that your program uses GNU gettext though it is
  non-essential for parsecfg.  It is very helpful for non-native English
  speakers to internationalize messages by gettext.  See
  <http://www.gnu.org/manual/gettext/html_node/gettext_toc.html> for
  details of gettext.



  2.  Usage



  2.1.  Installation

  Just include parsecfg.c and parsecfg.h as a part of your program.



  2.2.  Preparation

  Create and initialize an array of cfgStruct to parse the configuration
  file. Set parameter name, type and address of the variable in each
  element in the array.  (If type of the configuration file is INI,
  specify address of pointer to variable instead of address of the
  variable).

  cfgStruct is declared as the following in parsecfg.h.


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



  `parameterName' is the name of parameter (keyword), `type' is the type
  of parameter, `value` is the address of variable.  (or the address of
  pointer)

  There is the following types as `type'.


     CFG_BOOL
        Store 1 if the value is `True' or `Yes' or `T' or `Y' or `1'.
        Store 0 if the value is `False' or `No' or `F' or `N' or `0'.
        They are not case sensitive.
     CFG_INT
        Store as int.


     CFG_UINT
        Store as unsigned int.


     CFG_LONG
        Store as long.


     CFG_ULONG
        Store as unsigned long.


     CFG_FLOAT
        Store as float.


     CFG_DOUBLE
        Store as double.


     CFG_STRING
        Store as string.


     CFG_STRING_LIST
        Store as linked list for strings.


     CFG_END
        The last element in the array.


  When INT/UINT/LONG/ULONG, the string includes a `0x' prefix, and the
  number will be read in base 16, a `0` prefix in base 8, otherwise base
  10.

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



  2.3.  Function References

  Include parsecfg.h before using the following functions.


     void cfgSetFatalFunc(void (*f)(int, const char *, int, const char
        *))
        Set error handler by this function. Before calls this function,
        parsecfg uses default error handler written in parsecfg.c.


     const char *cfgStrError(cfgErrorCode error_code);
        Return string describing error code The error code is used as
        the first argument in error handler specified by
        cfgSetFatalFunc.


     int cfgParse(const char *file, cfgStruct cfg[], cfgFileType type)
        Call this function to parse the configuration file `file'.

        `type' is type of the configuration file. If it is CFG_SIMPLE,
        the file is parsed as simple format (PARAMETER = VALUE).  If it
        is CFG_INI, this function parses it as Windoze INI-like format
        (using sections).

        Return value is the number of read sections (1,2,3,...).  Return
        0 usually if the type is CFG_SIMPLE. Return -1 on error.


     int cfgDump(const char *file, cfgStruct cfg[], cfgFileType type,
        int max)
        Call this function to output configurations to a file.

        Configurations are written 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.)

        Return 0 if successful, -1 on error.


     int fetchVarFromCfgFile(const char *file, char *parameter_name,
        void *result_value, cfgValueType value_type, cfgFileType
        file_type, int section_num, const char *section_name)
        Call this function to fetch value of `parameter_name' from
        `file'.

        Result is stored in `result_value'. The type of this variable is
        specified by `value_type'.

        `file_type' is type of the configuration file.

        `section_num' is section number you want to fetch from.  If it
        is less than 1, fetch from the section specified in
        `section_name' instead of `section_num'.  If `type' is
        `CFG_SIMPLE', you can specify any value. (Normally, you want to
        specify 0 and NULL.)

        Return 0 if successful, -1 on error.


     int cfgSectionNameToNumber(const char *name)
        Call this function to convert section name to section number.

        Return value is section number (0,1,2,...).  Section name is not
        case sensitive.  Return -1 if name doesn't match.


     char *cfgSectionNumberToName(int num)
        Call this function to convert section number to section name.

        Return NULL if there is no specified section.


     int cfgAllocForNewSection(cfgStruct cfg[], const char *name)
        Call this function to alloc memories for defining a new section.
        The new section is named string specified in `name'.

        Return the maximum number of section if successful, -1 on error.


     int cfgStoreValue(cfgStruct cfg[], const char *parameter, const
        char *value, cfgFileType type, int section)
        Call this function to store `value' according to `cfg'.  `type'
        is type of the configuration file. `section' is section number
        (0,1,2,...) that you want to store value in. If `type' is
        CFG_SIMPLE, you can specify any number. (Normally, you want to
        specify 0.)

        Return 0 if successful, -1 on error.


     void cfgFree(cfgStruct cfg[], cfgFileType type, int numSections)
        Call this function to free memory allocated by cfgParse
        function.  Please free memory by this function if program calls
        cfgParse more than once.  This function does nothing if type is
        CFG_SIMPLE. (not implemented yet)



  2.4.  Format of Configuration File

  White spaces and tabs are always skipped. If you want to use such a
  special character, quote strings with " or '.  If you want to use ",
  use '.  If you want to use ', use ".

  Lines that begin with the # character are ignored as comment.

  Parameter names are not case sensitive.  Basic format is "PARAMETER =
  VALUE".


  ______________________________________________________________________
  # PARAMETER = VALUE

  ParameterINT    = 65535
  ParameterSTRING = GNU/Linux
  QuotedString    = 'I pronounce "Linux" as "Leenooks".'
  TRUEorFALSE     = FaLsE
  ______________________________________________________________________



  If there are same parameters and parameter type is CFG_STRING_LIST ,
  all values are stored. If other type, the last one is stored.


  ______________________________________________________________________
  # multiple parameters

  # CFG_INT
  ParameterINT = 255     # ignored
  ParameterINT = 65535   # stored

  # CFG_STRING_LIST
  ListString   = "Debian GNU/Linux" # stored
  ListString   = "FreeBSD"          # stored
  ______________________________________________________________________



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



  ______________________________________________________________________
  # for linked list

  ListString = {
          Internet
          "Exploder"
  }
  ______________________________________________________________________



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


  ______________________________________________________________________
  # Windoze INI-like file

  [Linux]
  STRING = rule!
  VALUE  = 99999999

  [Windoze]
  STRING = suck!
  VALUE  = -99999999
  ______________________________________________________________________



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



  3.  License

  Copyright (C) 1999-2001 Yuuki NINOMIYA <gm@debian.or.jp>

  This program 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.

  This program 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 License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  USA.



  4.  Tested Operating Systems


  o  Debian GNU/Linux 2.1/2.2/sid

  o  SuSE Linux 6.1

  o  FreeBSD 3.4-RELEASE



  5.  Limitations


  o  Cannot parse more than one CFG_INI type file concurrently.  This
     limitation caused by using static memory for section name list.

  o  cfgFree function does nothing if type is CFG_SIMPLE.



  6.  Known Bugs

  None.



  7.  Future Plans

  None.



  8.  FAQ

  None.



  9.  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 always welcome.
  Please mail them to the following address.



  10.  Author

  Yuuki NINOMIYA <gm@debian.or.jp>
  <http://www.enjoy.ne.jp/~gm/index.html>



  11.  The Latest Release

  The latest official release of parsecfg is available from:
  <http://www.enjoy.ne.jp/~gm/program/parsecfg/index.html>



  12.  The Latest Source Code

  You can get the latest source code with Anonymous CVS.  Specify
  `:pserver:anonymous@linuxlovers.yi.org:/var/cvs' as repository,
  `parsecfg' as project name, `anonymous' as password.


  ______________________________________________________________________
  % cvs -d :pserver:anonymous@linuxlovers.yi.org:/var/cvs login
  (Logging in to anonymous@linuxlovers.yi.org)
  CVS password: anonymous
  % cvs -d :pserver:anonymous@linuxlovers.yi.org:/var/cvs checkout parsecfg
  ______________________________________________________________________


  See <http://www.cvshome.org/docs/manual/index.html> for details about
  CVS.



  13.  Related Links

  A Configuration File Parser Using C++ and STL
  <http://members.tripod.com/toddsgreene/cfgstl.html>



  14.  Acknowledgement



  14.1.  Borrowed Code / Library



  14.2.  Contributions of Code or Document


     Kolb Norbert <nkolb@htl.de>

        o  definition of constant macro PARSECFG_VERSION


     And. Andruikhanov <andy@euinf.dp.ua>

        o  bugfix for detecting end of file


     Andreas Schuldei <schuldei@andrive.de>

        o  support for float parameter type


     Pascal Lengard <pascal.lengard@wanadoo.fr>

        o  default error handler never call exit


     Guillaume Hajduch <Guillaume.Hajduch@enst-bretagne.fr>

        o  support for double parameter type


     Richard Rowell <rrowell@shreve.net>

        o  support for linking with C++ code.


     Padraig Brady <padraig@antefacto.com>

        o  cfgStrError and cfgFree functions.



  14.3.  Translations


     Krzysztof Krzyz.aniak <eloy@transilvania.eu.org>


        o  Polish translations (pl.po)


     Guillaume Hajduch <guillaume.hajduch@free.fr>

        o  French translations (fr.po)


  14.4.  Other

  Thanks to many people who send me comments, bug reports and
  suggestions.

  And thank you for using parsecfg!



  15.  History


     Februay 20, 2002 Ver 3.6.9

        o  Remove free(NULL) for ANSI non-compliant processing system.


     Februay 14, 2002 Ver 3.6.8a

        o  Fixed a typo in the documents.


     Februay 13, 2002 Ver 3.6.8

        o  The code is added for proceeding even if there is
           unrecognized parameter. (commented out by default)
           Thanks to Nemykin, BorisX <borisx.nemykin@intel.com>

        o  Fixed a wrong variable definition.
           Thanks to Gabriele Vedovato
           <Gabriele.Vedovato@lnl.infn.it&gt;

        o  cfgStrError and cfgFree functions are added.
           Thanks to Padraig Brady <padraig@antefacto.com>


     June 27, 2001 Ver 3.6.7

        o  Support for 8 and 16 radix.
           Thanks to Carlos Nieves Onega <cnieves@tsc.uvigo.es>


     February 22, 2001 Ver 3.6.6

        o  Support for linking with C++ code.
           Thanks to Richard Rowell <rrowell@shreve.net>.


     February 15, 2001 Ver 3.6.5

        o  A memory leak is fixed.

        o  Some messages are modified.


     January 16, 2001 Ver 3.6.4


        o  The bug missing `static' declaration is fixed.

        o  Indent of a part of source is modified.


     December 19, 2000 Ver 3.6.3

        o  The bug is fixed that file stream closes twice on error.

        o  The bug is fixed that reading file fails in rare cases.


     December 18, 2000 Ver 3.6.2

        o  Add const qualifier to some arguments.


     December 15, 2000 Ver 3.6.1

        o  The bug is fixed that wrong variable is referred for checking
           the range.
           Thanks to Elliott Church <echurch@gfs.com>.


     December 06, 2000 Ver 3.6.0

        o  Functions for creating a new section and storing value in
           dynamic have been added.


     November 23, 2000 Ver 3.5.0

        o  Support for double parameter type.
           Thanks to Guillaume Hajduch <Guillaume.Hajduch@enst-
           bretagne.fr>.

        o  French translations (fr.po) has been added.
           Thanks to Guillaume Hajduch <guillaume.hajduch@free.fr>.


     October 07, 2000 Ver 3.4.0

        o  * warning *  This version doesn't have compatibility.
           Action of default error handler is changed. Any library
           functions never call exit though critical error happens.
           cfgParse returns -1 on error, so caller should process error
           handling. Or prepare your own error handler and set it by
           calling cfgSetFatalFunc.
           Thanks to Pascal Lengard <pascal.lengard@wanadoo.fr>

        o  The bug is fixed that cfgDump outputs wrong data.

        o  The bug is fixed that cfgDump causes SIGSEGV when string
           pointer is NULL.

        o  Providing SGML documents.


     July 20, 2000 Ver 3.3.0

        o  Polish translations (pl.po) has been added.
           Thanks to Krzysztof Krzyz.aniak <eloy@transilvania.eu.org>.

        o  Support for float parameter type.
           Thanks to Andreas Schuldei <schuldei@andrive.de>.

     February 24, 2000 Ver 3.2.1

        o  Bugfix for using freed memory block in
           parse_values_between_braces().

        o  Bugfix for outputing incorrect line when use braces and
           parameter is unrecognized.


     February 13, 2000 Ver 3.2.0

        o  Move definition of PARSECFG_VERSION to parsecfg.h.

        o  The bug is fixed that if last string in config file doesn't
           contain '\n' symbol, program doesn't detects last value or
           crashes.
           Thanks to And. Andruikhanov <andy@euinf.dp.ua>.

        o  Bugfix for leaving the configuration file opened.

        o  The bug is fixed that when program reads the end of file
           before brace is closed, it outputs incorrect error message.

        o  Add function for fetching value from configuration file by
           input name.


     December 24, 1999 Ver 3.1.2

        o  The bug is fixed that parsecfg crashes when there is a
           parameter before definition of a section.


     December 23, 1999 Ver 3.1.1

        o  Definition of constant macro PARSECFG_VERSION.
           Thanks to Kolb Norbert <nkolb@htl.de>.


     December 22, 1999 Ver 3.1.0

        o  Support for the function writing configurations to a file.


     November 30, 1999 Ver 3.0.4a

        o  Documents are modified.


     November 07, 1999 Ver 3.0.4

        o  Capitalize error messages.


     October 19, 1999 Ver 3.0.3

        o  The buffer for fgets is allocated dynamically.


     October 17, 1999 Ver 3.0.2

        o  Using typedef for enum.


     October 11, 1999 Ver 3.0.1

        o  In INI type configuration file, if there is no parameter, the
           boolean value is initialized by FALSE (-1).

        o  The bug is fixed that causes segmentation fault when calls
           cfgSectionNumberToName with minus value as argument.


     October 10, 1999 Ver 3.0.0

        o  Rewrite most codes. Lose compatibility of functions and the
           format of the configuration file.

        o  Supports the section Window INI-like file (or SAMBA's).

        o  Parameters are not case sensitive.

        o  Supports True/False, Yes/No, T/F, Y/N, 1/0 for boolean value.
           They are not case sensitive.

        o  Supports quotations for using white spaces and tabs in value.

        o  Abandon supporting tree structure.


     September 27, 1999 Ver 2.0.3

        o  Modify a little messages.


     August 12, 1999 Ver 2.0.2a

        o  Change the name.


     August 08, 1999 Ver 2.0.2

        o  Modify around gettext.


     July 01, 1999 Ver 2.0.1b

        o  Uses `int' instead of `void' as return type in main function
           in the sample program.


     June 29, 1999 Ver 2.0.1a

        o  Divide documents.


     June 09, 1999 Ver 2.0.1

        o  The overrun bug is fixed.


     June 02, 1999 Ver 2.0.0

        o  Change the name.

        o  Rewrite from scratch.

        o  Comment begins '#' instead of ';'.


     April 03, 1999 Ver 1.0.1

        o  The overrun bug is fixed.


     April 02, 1999 Ver 1.0.0

        o  Initial release.



