Commit | Line | Data |
---|---|---|
33858ce2 AT |
1 | |
2 | /*-------------------------------------------------------------------------*/ | |
3 | /** | |
4 | @file iniparser.h | |
5 | @author N. Devillard | |
6 | @brief Parser for ini files. | |
7 | */ | |
8 | /*--------------------------------------------------------------------------*/ | |
9 | ||
10 | #ifndef _INIPARSER_H_ | |
11 | #define _INIPARSER_H_ | |
12 | ||
13 | /*--------------------------------------------------------------------------- | |
14 | Includes | |
15 | ---------------------------------------------------------------------------*/ | |
16 | ||
17 | #include <stdio.h> | |
18 | #include <stdlib.h> | |
19 | #include <string.h> | |
20 | ||
21 | /* | |
22 | * The following #include is necessary on many Unixes but not Linux. | |
23 | * It is not needed for Windows platforms. | |
24 | * Uncomment it if needed. | |
25 | */ | |
26 | /* #include <unistd.h> */ | |
27 | ||
28 | #include "dictionary.h" | |
29 | ||
30 | #ifdef __cplusplus | |
31 | extern "C" { | |
32 | #endif | |
33 | ||
34 | /*-------------------------------------------------------------------------*/ | |
35 | /** | |
36 | @brief Configure a function to receive the error messages. | |
37 | @param errback Function to call. | |
38 | ||
39 | By default, the error will be printed on stderr. If a null pointer is passed | |
40 | as errback the error callback will be switched back to default. | |
41 | */ | |
42 | /*--------------------------------------------------------------------------*/ | |
43 | ||
44 | void iniparser_set_error_callback(int (*errback)(const char *, ...)); | |
45 | ||
46 | /*-------------------------------------------------------------------------*/ | |
47 | /** | |
48 | @brief Get number of sections in a dictionary | |
49 | @param d Dictionary to examine | |
50 | @return int Number of sections found in dictionary | |
51 | ||
52 | This function returns the number of sections found in a dictionary. | |
53 | The test to recognize sections is done on the string stored in the | |
54 | dictionary: a section name is given as "section" whereas a key is | |
55 | stored as "section:key", thus the test looks for entries that do not | |
56 | contain a colon. | |
57 | ||
58 | This clearly fails in the case a section name contains a colon, but | |
59 | this should simply be avoided. | |
60 | ||
61 | This function returns -1 in case of error. | |
62 | */ | |
63 | /*--------------------------------------------------------------------------*/ | |
64 | ||
65 | int iniparser_getnsec(const dictionary * d); | |
66 | ||
67 | ||
68 | /*-------------------------------------------------------------------------*/ | |
69 | /** | |
70 | @brief Get name for section n in a dictionary. | |
71 | @param d Dictionary to examine | |
72 | @param n Section number (from 0 to nsec-1). | |
73 | @return Pointer to char string | |
74 | ||
75 | This function locates the n-th section in a dictionary and returns | |
76 | its name as a pointer to a string statically allocated inside the | |
77 | dictionary. Do not free or modify the returned string! | |
78 | ||
79 | This function returns NULL in case of error. | |
80 | */ | |
81 | /*--------------------------------------------------------------------------*/ | |
82 | ||
83 | const char * iniparser_getsecname(const dictionary * d, int n); | |
84 | ||
85 | ||
86 | /*-------------------------------------------------------------------------*/ | |
87 | /** | |
88 | @brief Save a dictionary to a loadable ini file | |
89 | @param d Dictionary to dump | |
90 | @param f Opened file pointer to dump to | |
91 | @return void | |
92 | ||
93 | This function dumps a given dictionary into a loadable ini file. | |
94 | It is Ok to specify @c stderr or @c stdout as output files. | |
95 | */ | |
96 | /*--------------------------------------------------------------------------*/ | |
97 | ||
98 | void iniparser_dump_ini(const dictionary * d, FILE * f); | |
99 | ||
100 | /*-------------------------------------------------------------------------*/ | |
101 | /** | |
102 | @brief Save a dictionary section to a loadable ini file | |
103 | @param d Dictionary to dump | |
104 | @param s Section name of dictionary to dump | |
105 | @param f Opened file pointer to dump to | |
106 | @return void | |
107 | ||
108 | This function dumps a given section of a given dictionary into a loadable ini | |
109 | file. It is Ok to specify @c stderr or @c stdout as output files. | |
110 | */ | |
111 | /*--------------------------------------------------------------------------*/ | |
112 | ||
113 | void iniparser_dumpsection_ini(const dictionary * d, const char * s, FILE * f); | |
114 | ||
115 | /*-------------------------------------------------------------------------*/ | |
116 | /** | |
117 | @brief Dump a dictionary to an opened file pointer. | |
118 | @param d Dictionary to dump. | |
119 | @param f Opened file pointer to dump to. | |
120 | @return void | |
121 | ||
122 | This function prints out the contents of a dictionary, one element by | |
123 | line, onto the provided file pointer. It is OK to specify @c stderr | |
124 | or @c stdout as output files. This function is meant for debugging | |
125 | purposes mostly. | |
126 | */ | |
127 | /*--------------------------------------------------------------------------*/ | |
128 | void iniparser_dump(const dictionary * d, FILE * f); | |
129 | ||
130 | /*-------------------------------------------------------------------------*/ | |
131 | /** | |
132 | @brief Get the number of keys in a section of a dictionary. | |
133 | @param d Dictionary to examine | |
134 | @param s Section name of dictionary to examine | |
135 | @return Number of keys in section | |
136 | */ | |
137 | /*--------------------------------------------------------------------------*/ | |
138 | int iniparser_getsecnkeys(const dictionary * d, const char * s); | |
139 | ||
140 | /*-------------------------------------------------------------------------*/ | |
141 | /** | |
142 | @brief Get the number of keys in a section of a dictionary. | |
143 | @param d Dictionary to examine | |
144 | @param s Section name of dictionary to examine | |
145 | @param keys Already allocated array to store the keys in | |
146 | @return The pointer passed as `keys` argument or NULL in case of error | |
147 | ||
148 | This function queries a dictionary and finds all keys in a given section. | |
149 | The keys argument should be an array of pointers which size has been | |
150 | determined by calling `iniparser_getsecnkeys` function prior to this one. | |
151 | ||
152 | Each pointer in the returned char pointer-to-pointer is pointing to | |
153 | a string allocated in the dictionary; do not free or modify them. | |
154 | */ | |
155 | /*--------------------------------------------------------------------------*/ | |
156 | const char ** iniparser_getseckeys(const dictionary * d, const char * s, const char ** keys); | |
157 | ||
158 | ||
159 | /*-------------------------------------------------------------------------*/ | |
160 | /** | |
161 | @brief Get the string associated to a key | |
162 | @param d Dictionary to search | |
163 | @param key Key string to look for | |
164 | @param def Default value to return if key not found. | |
165 | @return pointer to statically allocated character string | |
166 | ||
167 | This function queries a dictionary for a key. A key as read from an | |
168 | ini file is given as "section:key". If the key cannot be found, | |
169 | the pointer passed as 'def' is returned. | |
170 | The returned char pointer is pointing to a string allocated in | |
171 | the dictionary, do not free or modify it. | |
172 | */ | |
173 | /*--------------------------------------------------------------------------*/ | |
174 | const char * iniparser_getstring(const dictionary * d, const char * key, const char * def); | |
175 | ||
176 | /*-------------------------------------------------------------------------*/ | |
177 | /** | |
178 | @brief Get the string associated to a key, convert to an int | |
179 | @param d Dictionary to search | |
180 | @param key Key string to look for | |
181 | @param notfound Value to return in case of error | |
182 | @return integer | |
183 | ||
184 | This function queries a dictionary for a key. A key as read from an | |
185 | ini file is given as "section:key". If the key cannot be found, | |
186 | the notfound value is returned. | |
187 | ||
188 | Supported values for integers include the usual C notation | |
189 | so decimal, octal (starting with 0) and hexadecimal (starting with 0x) | |
190 | are supported. Examples: | |
191 | ||
192 | - "42" -> 42 | |
193 | - "042" -> 34 (octal -> decimal) | |
194 | - "0x42" -> 66 (hexa -> decimal) | |
195 | ||
196 | Warning: the conversion may overflow in various ways. Conversion is | |
197 | totally outsourced to strtol(), see the associated man page for overflow | |
198 | handling. | |
199 | ||
200 | Credits: Thanks to A. Becker for suggesting strtol() | |
201 | */ | |
202 | /*--------------------------------------------------------------------------*/ | |
203 | int iniparser_getint(const dictionary * d, const char * key, int notfound); | |
204 | ||
205 | /*-------------------------------------------------------------------------*/ | |
206 | /** | |
207 | @brief Get the string associated to a key, convert to an long int | |
208 | @param d Dictionary to search | |
209 | @param key Key string to look for | |
210 | @param notfound Value to return in case of error | |
211 | @return integer | |
212 | ||
213 | This function queries a dictionary for a key. A key as read from an | |
214 | ini file is given as "section:key". If the key cannot be found, | |
215 | the notfound value is returned. | |
216 | ||
217 | Supported values for integers include the usual C notation | |
218 | so decimal, octal (starting with 0) and hexadecimal (starting with 0x) | |
219 | are supported. Examples: | |
220 | ||
221 | - "42" -> 42 | |
222 | - "042" -> 34 (octal -> decimal) | |
223 | - "0x42" -> 66 (hexa -> decimal) | |
224 | ||
225 | Warning: the conversion may overflow in various ways. Conversion is | |
226 | totally outsourced to strtol(), see the associated man page for overflow | |
227 | handling. | |
228 | */ | |
229 | /*--------------------------------------------------------------------------*/ | |
230 | long int iniparser_getlongint(const dictionary * d, const char * key, long int notfound); | |
231 | ||
232 | ||
233 | /*-------------------------------------------------------------------------*/ | |
234 | /** | |
235 | @brief Get the string associated to a key, convert to a double | |
236 | @param d Dictionary to search | |
237 | @param key Key string to look for | |
238 | @param notfound Value to return in case of error | |
239 | @return double | |
240 | ||
241 | This function queries a dictionary for a key. A key as read from an | |
242 | ini file is given as "section:key". If the key cannot be found, | |
243 | the notfound value is returned. | |
244 | */ | |
245 | /*--------------------------------------------------------------------------*/ | |
246 | double iniparser_getdouble(const dictionary * d, const char * key, double notfound); | |
247 | ||
248 | /*-------------------------------------------------------------------------*/ | |
249 | /** | |
250 | @brief Get the string associated to a key, convert to a boolean | |
251 | @param d Dictionary to search | |
252 | @param key Key string to look for | |
253 | @param notfound Value to return in case of error | |
254 | @return integer | |
255 | ||
256 | This function queries a dictionary for a key. A key as read from an | |
257 | ini file is given as "section:key". If the key cannot be found, | |
258 | the notfound value is returned. | |
259 | ||
260 | A true boolean is found if one of the following is matched: | |
261 | ||
262 | - A string starting with 'y' | |
263 | - A string starting with 'Y' | |
264 | - A string starting with 't' | |
265 | - A string starting with 'T' | |
266 | - A string starting with '1' | |
267 | ||
268 | A false boolean is found if one of the following is matched: | |
269 | ||
270 | - A string starting with 'n' | |
271 | - A string starting with 'N' | |
272 | - A string starting with 'f' | |
273 | - A string starting with 'F' | |
274 | - A string starting with '0' | |
275 | ||
276 | The notfound value returned if no boolean is identified, does not | |
277 | necessarily have to be 0 or 1. | |
278 | */ | |
279 | /*--------------------------------------------------------------------------*/ | |
280 | int iniparser_getboolean(const dictionary * d, const char * key, int notfound); | |
281 | ||
282 | ||
283 | /*-------------------------------------------------------------------------*/ | |
284 | /** | |
285 | @brief Set an entry in a dictionary. | |
286 | @param ini Dictionary to modify. | |
287 | @param entry Entry to modify (entry name) | |
288 | @param val New value to associate to the entry. | |
289 | @return int 0 if Ok, -1 otherwise. | |
290 | ||
291 | If the given entry can be found in the dictionary, it is modified to | |
292 | contain the provided value. If it cannot be found, the entry is created. | |
293 | It is Ok to set val to NULL. | |
294 | */ | |
295 | /*--------------------------------------------------------------------------*/ | |
296 | int iniparser_set(dictionary * ini, const char * entry, const char * val); | |
297 | ||
298 | ||
299 | /*-------------------------------------------------------------------------*/ | |
300 | /** | |
301 | @brief Delete an entry in a dictionary | |
302 | @param ini Dictionary to modify | |
303 | @param entry Entry to delete (entry name) | |
304 | @return void | |
305 | ||
306 | If the given entry can be found, it is deleted from the dictionary. | |
307 | */ | |
308 | /*--------------------------------------------------------------------------*/ | |
309 | void iniparser_unset(dictionary * ini, const char * entry); | |
310 | ||
311 | /*-------------------------------------------------------------------------*/ | |
312 | /** | |
313 | @brief Finds out if a given entry exists in a dictionary | |
314 | @param ini Dictionary to search | |
315 | @param entry Name of the entry to look for | |
316 | @return integer 1 if entry exists, 0 otherwise | |
317 | ||
318 | Finds out if a given entry exists in the dictionary. Since sections | |
319 | are stored as keys with NULL associated values, this is the only way | |
320 | of querying for the presence of sections in a dictionary. | |
321 | */ | |
322 | /*--------------------------------------------------------------------------*/ | |
323 | int iniparser_find_entry(const dictionary * ini, const char * entry) ; | |
324 | ||
325 | /*-------------------------------------------------------------------------*/ | |
326 | /** | |
327 | @brief Parse an ini file and return an allocated dictionary object | |
328 | @param ininame Name of the ini file to read. | |
329 | @return Pointer to newly allocated dictionary | |
330 | ||
331 | This is the parser for ini files. This function is called, providing | |
332 | the name of the file to be read. It returns a dictionary object that | |
333 | should not be accessed directly, but through accessor functions | |
334 | instead. | |
335 | ||
336 | The returned dictionary must be freed using iniparser_freedict(). | |
337 | */ | |
338 | /*--------------------------------------------------------------------------*/ | |
339 | dictionary * iniparser_load(const char * ininame); | |
340 | ||
341 | /*-------------------------------------------------------------------------*/ | |
342 | /** | |
343 | @brief Free all memory associated to an ini dictionary | |
344 | @param d Dictionary to free | |
345 | @return void | |
346 | ||
347 | Free all memory associated to an ini dictionary. | |
348 | It is mandatory to call this function before the dictionary object | |
349 | gets out of the current context. | |
350 | */ | |
351 | /*--------------------------------------------------------------------------*/ | |
352 | void iniparser_freedict(dictionary * d); | |
353 | ||
354 | #ifdef __cplusplus | |
355 | } | |
356 | #endif | |
357 | ||
358 | #endif |