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 308
