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