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