pool/stratum/iniparser/doc/iniparser.main

/**

    @mainpage   iniparser documentation


    @section welcome    Introduction

    iniParser is a simple C library offering ini file parsing services.
    The library is pretty small (less than 1500 lines of C) and robust, and
    does not depend on any other external library to compile. It is written
    in ANSI C and should compile on most platforms without difficulty.


    @section inidef     What is an ini file?

    An ini file is an ASCII file describing simple parameters
    (character strings, integers, floating-point values or booleans)
    in an explicit format, easy to use and modify for users.

    An ini file is segmented into Sections, declared by the following
    syntax:

    @verbatim
    [Section Name]
    @endverbatim

    i.e. the section name enclosed in square brackets, alone on a
    line. Sections names are allowed to contain any character but
    square brackets or linefeeds.

    In any section are zero or more variables, declared with the
    following syntax:

    @verbatim
    Key = value ; comment
    @endverbatim

    The key is any string (possibly containing blanks). The value is
    any character on the right side of the equal sign. Values can be
    given enclosed with quotes. If no quotes are present, the value is
    understood as containing all characters between the first and the
    last non-blank characters before the comment. The following
    declarations are identical:

    @verbatim
    Hello = "this is a long string value" ; comment
    Hello = this is a long string value ; comment
    @endverbatim

    The semicolon and comment at the end of the line are optional. If
    there is a comment, it starts from the first character after the
    semicolon up to the end of the line.

    Multi-line values can be provided by ending the line with a
    backslash (\).

    @verbatim
    Multiple = Line 1 \
    Line 2 \
    Line 3 \
    Line 4 ; comment
    @endverbatim

    This would yield: "multiple" <- "Line1 Line2 Line3 Line4"

    Comments in an ini file are:

    - Lines starting with a hash sign
    - Blank lines (only blanks or tabs)
    - Comments given on value lines after the semicolon (if present)


    @section install    Compiling/installing the library

    Edit the Makefile to indicate the C compiler you want to use, the
    options to provide to compile ANSI C, and possibly the options to pass
    to the ar program on your machine to build a library (.a) from a set
    of object (.o) files.

    Defaults are set for the gcc compiler and the standard ar library
    builder.

    Type 'make', that should do it.

    To use the library in your programs, add the following line on top
    of your module:

    @code
    #include "iniparser.h"
    @endcode

    And link your program with the iniparser library by adding
    @c -liniparser.a to the compile line.

    See the file test/initest.c for an example.

    iniparser is an ANSI C library. If you want to compile it
    with a C++ compiler you will likely run into compatibility
    issues. Headers probably have to include the extern "C"
    hack and function prototypes will want to add some const
    here and there to keep the compiler happy. This job is left
    to the reader as there are too many C++ compilers around, each
    with its own requirements as to what represents acceptable
    C code in a C++ environment. You have been warned.


    @section reference  Library reference

    The library is completely documented in its header file. On-line
    documentation has been generated and can be consulted here:

    - iniparser.h


    @section usage      Using the parser

    Comments are discarded by the parser. Then sections are
    identified, and in each section a new entry is created for every
    keyword found. The keywords are stored with the following syntax:

    @verbatim
    [Section]
    Keyword = value ; comment
    @endverbatim

    is converted to the following key pair:

    @verbatim
    ("section:keyword", "value")
    @endverbatim

    This means that if you want to retrieve the value that was stored
    in the section called @c Pizza, in the keyword @c Cheese,
    you would make a request to the dictionary for
    @c "pizza:cheese". All section and keyword names are converted
    to lowercase before storage in the structure. The value side is
    conserved as it has been parsed, though.

    Section names are also stored in the structure. They are stored
    using as key the section name, and a NULL associated value. They
    can be queried through iniparser_find_entry().

    To launch the parser, use the function called iniparser_load(), which
    takes an input file name and returns a newly allocated @e dictionary
    structure. This latter object should remain opaque to the user and only
    accessed through the following accessor functions:

    - iniparser_getstring()
    - iniparser_getint()
    - iniparser_getdouble()
    - iniparser_getboolean()

    Finally, discard this structure using iniparser_freedict().

    All values parsed from the ini file are stored as strings. The
    accessors are just converting these strings to the requested type on
    the fly, but you could basically perform this conversion by yourself
    after having called the string accessor.

    Notice that iniparser_getboolean() will return an integer (0 or 1),
    trying to make sense of what was found in the file. Strings starting
    with "y", "Y", "t", "T" or "1" are considered true values (return 1),
    strings starting with "n", "N", "f", "F", "0" are considered false
    (return 0). This allows some flexibility in handling of boolean
    answers.

    If you want to add extra information into the structure that was not
    present in the ini file, you can use iniparser_set() to insert a
    string.

    If you want to add a section to the structure, add a key
    with a NULL value. Example:
    @verbatim
    iniparser_set(ini, "section", NULL);
    iniparser_set(ini, "section:key1", NULL);
    iniparser_set(ini, "section:key2", NULL);
    @endverbatim


    @section implementation     A word about the implementation

    The dictionary structure is a pretty simple dictionary
    implementation which might find some uses in other applications.
    If you are curious, look into the source.


    @section defects            Known defects

    The dictionary structure is extremely unefficient for searching
    as keys are sorted in the same order as they are read from the
    ini file, which is convenient when dumping back to a file. The
    simplistic first-approach linear search implemented there can
    become a bottleneck if you have a very large number of keys.

    People who need to load large amounts of data from an ini file
    should definitely turn to more appropriate solutions: sqlite3 or
    similar. There are otherwise many other dictionary implementations
    available on the net to replace this one.


    @section authors    Authors

    Nicolas Devillard (ndevilla AT free DOT fr).


*/