|
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 /*-------------------------------------------------------------------------*/ |
|
31 /** |
|
32 @brief Get number of sections in a dictionary |
|
33 @param d Dictionary to examine |
|
34 @return int Number of sections found in dictionary |
|
35 |
|
36 This function returns the number of sections found in a dictionary. |
|
37 The test to recognize sections is done on the string stored in the |
|
38 dictionary: a section name is given as "section" whereas a key is |
|
39 stored as "section:key", thus the test looks for entries that do not |
|
40 contain a colon. |
|
41 |
|
42 This clearly fails in the case a section name contains a colon, but |
|
43 this should simply be avoided. |
|
44 |
|
45 This function returns -1 in case of error. |
|
46 */ |
|
47 /*--------------------------------------------------------------------------*/ |
|
48 |
|
49 int iniparser_getnsec(dictionary * d); |
|
50 |
|
51 |
|
52 /*-------------------------------------------------------------------------*/ |
|
53 /** |
|
54 @brief Get name for section n in a dictionary. |
|
55 @param d Dictionary to examine |
|
56 @param n Section number (from 0 to nsec-1). |
|
57 @return Pointer to char string |
|
58 |
|
59 This function locates the n-th section in a dictionary and returns |
|
60 its name as a pointer to a string statically allocated inside the |
|
61 dictionary. Do not free or modify the returned string! |
|
62 |
|
63 This function returns NULL in case of error. |
|
64 */ |
|
65 /*--------------------------------------------------------------------------*/ |
|
66 |
|
67 char * iniparser_getsecname(dictionary * d, int n); |
|
68 |
|
69 |
|
70 /*-------------------------------------------------------------------------*/ |
|
71 /** |
|
72 @brief Save a dictionary to a loadable ini file |
|
73 @param d Dictionary to dump |
|
74 @param f Opened file pointer to dump to |
|
75 @return void |
|
76 |
|
77 This function dumps a given dictionary into a loadable ini file. |
|
78 It is Ok to specify @c stderr or @c stdout as output files. |
|
79 */ |
|
80 /*--------------------------------------------------------------------------*/ |
|
81 |
|
82 void iniparser_dump_ini(dictionary * d, FILE * f); |
|
83 |
|
84 /*-------------------------------------------------------------------------*/ |
|
85 /** |
|
86 @brief Save a dictionary section to a loadable ini file |
|
87 @param d Dictionary to dump |
|
88 @param s Section name of dictionary to dump |
|
89 @param f Opened file pointer to dump to |
|
90 @return void |
|
91 |
|
92 This function dumps a given section of a given dictionary into a loadable ini |
|
93 file. It is Ok to specify @c stderr or @c stdout as output files. |
|
94 */ |
|
95 /*--------------------------------------------------------------------------*/ |
|
96 |
|
97 void iniparser_dumpsection_ini(dictionary * d, char * s, FILE * f); |
|
98 |
|
99 /*-------------------------------------------------------------------------*/ |
|
100 /** |
|
101 @brief Dump a dictionary to an opened file pointer. |
|
102 @param d Dictionary to dump. |
|
103 @param f Opened file pointer to dump to. |
|
104 @return void |
|
105 |
|
106 This function prints out the contents of a dictionary, one element by |
|
107 line, onto the provided file pointer. It is OK to specify @c stderr |
|
108 or @c stdout as output files. This function is meant for debugging |
|
109 purposes mostly. |
|
110 */ |
|
111 /*--------------------------------------------------------------------------*/ |
|
112 void iniparser_dump(dictionary * d, FILE * f); |
|
113 |
|
114 /*-------------------------------------------------------------------------*/ |
|
115 /** |
|
116 @brief Get the number of keys in a section of a dictionary. |
|
117 @param d Dictionary to examine |
|
118 @param s Section name of dictionary to examine |
|
119 @return Number of keys in section |
|
120 */ |
|
121 /*--------------------------------------------------------------------------*/ |
|
122 int iniparser_getsecnkeys(dictionary * d, char * s); |
|
123 |
|
124 /*-------------------------------------------------------------------------*/ |
|
125 /** |
|
126 @brief Get the number of keys in a section of a dictionary. |
|
127 @param d Dictionary to examine |
|
128 @param s Section name of dictionary to examine |
|
129 @return pointer to statically allocated character strings |
|
130 |
|
131 This function queries a dictionary and finds all keys in a given section. |
|
132 Each pointer in the returned char pointer-to-pointer is pointing to |
|
133 a string allocated in the dictionary; do not free or modify them. |
|
134 |
|
135 This function returns NULL in case of error. |
|
136 */ |
|
137 /*--------------------------------------------------------------------------*/ |
|
138 char ** iniparser_getseckeys(dictionary * d, char * s); |
|
139 |
|
140 /*-------------------------------------------------------------------------*/ |
|
141 /** |
|
142 @brief Get the string associated to a key |
|
143 @param d Dictionary to search |
|
144 @param key Key string to look for |
|
145 @param def Default value to return if key not found. |
|
146 @return pointer to statically allocated character string |
|
147 |
|
148 This function queries a dictionary for a key. A key as read from an |
|
149 ini file is given as "section:key". If the key cannot be found, |
|
150 the pointer passed as 'def' is returned. |
|
151 The returned char pointer is pointing to a string allocated in |
|
152 the dictionary, do not free or modify it. |
|
153 */ |
|
154 /*--------------------------------------------------------------------------*/ |
|
155 char * iniparser_getstring(dictionary * d, const char * key, char * def); |
|
156 |
|
157 /*-------------------------------------------------------------------------*/ |
|
158 /** |
|
159 @brief Get the string associated to a key, convert to an int |
|
160 @param d Dictionary to search |
|
161 @param key Key string to look for |
|
162 @param notfound Value to return in case of error |
|
163 @return integer |
|
164 |
|
165 This function queries a dictionary for a key. A key as read from an |
|
166 ini file is given as "section:key". If the key cannot be found, |
|
167 the notfound value is returned. |
|
168 |
|
169 Supported values for integers include the usual C notation |
|
170 so decimal, octal (starting with 0) and hexadecimal (starting with 0x) |
|
171 are supported. Examples: |
|
172 |
|
173 - "42" -> 42 |
|
174 - "042" -> 34 (octal -> decimal) |
|
175 - "0x42" -> 66 (hexa -> decimal) |
|
176 |
|
177 Warning: the conversion may overflow in various ways. Conversion is |
|
178 totally outsourced to strtol(), see the associated man page for overflow |
|
179 handling. |
|
180 |
|
181 Credits: Thanks to A. Becker for suggesting strtol() |
|
182 */ |
|
183 /*--------------------------------------------------------------------------*/ |
|
184 int iniparser_getint(dictionary * d, const char * key, int notfound); |
|
185 |
|
186 /*-------------------------------------------------------------------------*/ |
|
187 /** |
|
188 @brief Get the string associated to a key, convert to a double |
|
189 @param d Dictionary to search |
|
190 @param key Key string to look for |
|
191 @param notfound Value to return in case of error |
|
192 @return double |
|
193 |
|
194 This function queries a dictionary for a key. A key as read from an |
|
195 ini file is given as "section:key". If the key cannot be found, |
|
196 the notfound value is returned. |
|
197 */ |
|
198 /*--------------------------------------------------------------------------*/ |
|
199 double iniparser_getdouble(dictionary * d, const char * key, double notfound); |
|
200 |
|
201 /*-------------------------------------------------------------------------*/ |
|
202 /** |
|
203 @brief Get the string associated to a key, convert to a boolean |
|
204 @param d Dictionary to search |
|
205 @param key Key string to look for |
|
206 @param notfound Value to return in case of error |
|
207 @return integer |
|
208 |
|
209 This function queries a dictionary for a key. A key as read from an |
|
210 ini file is given as "section:key". If the key cannot be found, |
|
211 the notfound value is returned. |
|
212 |
|
213 A true boolean is found if one of the following is matched: |
|
214 |
|
215 - A string starting with 'y' |
|
216 - A string starting with 'Y' |
|
217 - A string starting with 't' |
|
218 - A string starting with 'T' |
|
219 - A string starting with '1' |
|
220 |
|
221 A false boolean is found if one of the following is matched: |
|
222 |
|
223 - A string starting with 'n' |
|
224 - A string starting with 'N' |
|
225 - A string starting with 'f' |
|
226 - A string starting with 'F' |
|
227 - A string starting with '0' |
|
228 |
|
229 The notfound value returned if no boolean is identified, does not |
|
230 necessarily have to be 0 or 1. |
|
231 */ |
|
232 /*--------------------------------------------------------------------------*/ |
|
233 int iniparser_getboolean(dictionary * d, const char * key, int notfound); |
|
234 |
|
235 |
|
236 /*-------------------------------------------------------------------------*/ |
|
237 /** |
|
238 @brief Set an entry in a dictionary. |
|
239 @param ini Dictionary to modify. |
|
240 @param entry Entry to modify (entry name) |
|
241 @param val New value to associate to the entry. |
|
242 @return int 0 if Ok, -1 otherwise. |
|
243 |
|
244 If the given entry can be found in the dictionary, it is modified to |
|
245 contain the provided value. If it cannot be found, -1 is returned. |
|
246 It is Ok to set val to NULL. |
|
247 */ |
|
248 /*--------------------------------------------------------------------------*/ |
|
249 int iniparser_set(dictionary * ini, const char * entry, const char * val); |
|
250 |
|
251 |
|
252 /*-------------------------------------------------------------------------*/ |
|
253 /** |
|
254 @brief Delete an entry in a dictionary |
|
255 @param ini Dictionary to modify |
|
256 @param entry Entry to delete (entry name) |
|
257 @return void |
|
258 |
|
259 If the given entry can be found, it is deleted from the dictionary. |
|
260 */ |
|
261 /*--------------------------------------------------------------------------*/ |
|
262 void iniparser_unset(dictionary * ini, const char * entry); |
|
263 |
|
264 /*-------------------------------------------------------------------------*/ |
|
265 /** |
|
266 @brief Finds out if a given entry exists in a dictionary |
|
267 @param ini Dictionary to search |
|
268 @param entry Name of the entry to look for |
|
269 @return integer 1 if entry exists, 0 otherwise |
|
270 |
|
271 Finds out if a given entry exists in the dictionary. Since sections |
|
272 are stored as keys with NULL associated values, this is the only way |
|
273 of querying for the presence of sections in a dictionary. |
|
274 */ |
|
275 /*--------------------------------------------------------------------------*/ |
|
276 int iniparser_find_entry(dictionary * ini, const char * entry) ; |
|
277 |
|
278 /*-------------------------------------------------------------------------*/ |
|
279 /** |
|
280 @brief Parse an ini file and return an allocated dictionary object |
|
281 @param ininame Name of the ini file to read. |
|
282 @return Pointer to newly allocated dictionary |
|
283 |
|
284 This is the parser for ini files. This function is called, providing |
|
285 the name of the file to be read. It returns a dictionary object that |
|
286 should not be accessed directly, but through accessor functions |
|
287 instead. |
|
288 |
|
289 The returned dictionary must be freed using iniparser_freedict(). |
|
290 */ |
|
291 /*--------------------------------------------------------------------------*/ |
|
292 dictionary * iniparser_load(const char * ininame); |
|
293 |
|
294 /*-------------------------------------------------------------------------*/ |
|
295 /** |
|
296 @brief Free all memory associated to an ini dictionary |
|
297 @param d Dictionary to free |
|
298 @return void |
|
299 |
|
300 Free all memory associated to an ini dictionary. |
|
301 It is mandatory to call this function before the dictionary object |
|
302 gets out of the current context. |
|
303 */ |
|
304 /*--------------------------------------------------------------------------*/ |
|
305 void iniparser_freedict(dictionary * d); |
|
306 |
|
307 #endif |