1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
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).
*/
|
