An ini file is segmented into Sections, declared by the following syntax:
[Section Name]
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. Slashes (/) are also reserved with this parser for hierarchical sections (see below).
In any section are zero or more variables, declared with the following syntax:
Key = value ; comment
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. The following declarations are identical:
Hello = "this is a long string value" ; comment Hello = this is a long string value ; comment
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 (\).
Multiple = Line 1 \ Line 2 \ Line 3 \ Line 4 ; comment
This would yield: "multiple" <- "Line1 Line2 Line3 Line4"
Comments in an ini file are:
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:
#include "iniparser.h"
And link your program with the iniparser library by adding -liniparser.a
to the compile line.
See the file test/initest.c for an example.
[Section] Keyword = value ; comment
is converted to the following key pair:
("section:keyword", "value")
This means that if you want to retrieve the value that was stored in the section called Pizza
, in the keyword Cheese
, you would make a request to the dictionary for "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 dictionary structure. This latter object should remain opaque to the user and only accessed through the following accessor functions:
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_setstring() to insert a string.