diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 16 | ||||
| -rw-r--r-- | doc/iniparser.dox | 81 | ||||
| -rw-r--r-- | doc/iniparser.main | 207 |
3 files changed, 304 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..db925ec --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,16 @@ +# +# iniparser doc Makefile +# + +all: html + +html: + doxygen iniparser.dox + rm -f ../html/annotated.html + rm -f ../html/classes.html + rm -f ../html/doxygen.gif + rm -f ../html/files.html + rm -f ../html/functions.html + rm -f ../html/globals.html + rm -f ../html/iniparser_main.html + diff --git a/doc/iniparser.dox b/doc/iniparser.dox new file mode 100644 index 0000000..ee59555 --- /dev/null +++ b/doc/iniparser.dox @@ -0,0 +1,81 @@ +PROJECT_NAME = iniparser +PROJECT_NUMBER = 3.1 +OUTPUT_DIRECTORY = .. +OUTPUT_LANGUAGE = English +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +HIDE_UNDOC_MEMBERS = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +INTERNAL_DOCS = NO +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +VERBATIM_HEADERS = NO +SHOW_INCLUDE_FILES = NO +JAVADOC_AUTOBRIEF = NO +INHERIT_DOCS = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 4 +ENABLED_SECTIONS = +GENERATE_TODOLIST = NO +GENERATE_TESTLIST = NO +ALIASES = +MAX_INITIALIZER_LINES = 30 +OPTIMIZE_OUTPUT_FOR_C = YES +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +INPUT = iniparser.main ../src +FILE_PATTERNS = iniparser.h +RECURSIVE = NO +EXCLUDE = +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +IMAGE_PATH = +INPUT_FILTER = +FILTER_SOURCE_FILES = NO +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +DISABLE_INDEX = YES +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 + +GENERATE_LATEX = NO +GENERATE_RTF = NO +GENERATE_MAN = NO + +ENABLE_PREPROCESSING = NO +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = NO +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +PERL_PATH = /usr/bin/perl +HAVE_DOT = NO +SEARCHENGINE = NO diff --git a/doc/iniparser.main b/doc/iniparser.main new file mode 100644 index 0000000..47747c1 --- /dev/null +++ b/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). + + +*/ |