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 359