initial/final commitHEADmaster

1 files changed, 207 insertions, 0 deletions

diff --git a/iniparser-4.1/doc/iniparser.main b/iniparser-4.1/doc/iniparser.main
new file mode 100644
index 0000000..47747c1
--- /dev/null
+++ b/iniparser-4.1/doc/iniparser.main
@@ -0,0 +1,207 @@
+
+/**
+
+    @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).
+
+
+*/