iniparser.h
Go to the documentation of this file.00001 00002 /*-------------------------------------------------------------------------*/ 00003 /** 00004 @file iniparser.h 00005 @author N. Devillard 00006 @date Mar 2000 00007 @version $Revision: 1.23 $ 00008 @brief Parser for ini files. 00009 */ 00010 /*--------------------------------------------------------------------------*/ 00011 00012 /* 00013 $Id: iniparser.h,v 1.23 2006-09-27 11:03:35 ndevilla Exp $ 00014 $Author: ndevilla $ 00015 $Date: 2006-09-27 11:03:35 $ 00016 $Revision: 1.23 $ 00017 */ 00018 00019 #ifndef _INIPARSER_H_ 00020 #define _INIPARSER_H_ 00021 00022 /*--------------------------------------------------------------------------- 00023 Includes 00024 ---------------------------------------------------------------------------*/ 00025 00026 #include <stdio.h> 00027 #include <stdlib.h> 00028 #include <string.h> 00029 00030 /* 00031 * The following #include is necessary on many Unixes but not Linux. 00032 * It is not needed for Windows platforms. 00033 * Uncomment it if needed. 00034 */ 00035 /* #include <unistd.h> */ 00036 00037 #include "dictionary.h" 00038 00039 /*-------------------------------------------------------------------------*/ 00040 /** 00041 @brief Get number of sections in a dictionary 00042 @param d Dictionary to examine 00043 @return int Number of sections found in dictionary 00044 00045 This function returns the number of sections found in a dictionary. 00046 The test to recognize sections is done on the string stored in the 00047 dictionary: a section name is given as "section" whereas a key is 00048 stored as "section:key", thus the test looks for entries that do not 00049 contain a colon. 00050 00051 This clearly fails in the case a section name contains a colon, but 00052 this should simply be avoided. 00053 00054 This function returns -1 in case of error. 00055 */ 00056 /*--------------------------------------------------------------------------*/ 00057 00058 int iniparser_getnsec(dictionary * d); 00059 00060 00061 /*-------------------------------------------------------------------------*/ 00062 /** 00063 @brief Get name for section n in a dictionary. 00064 @param d Dictionary to examine 00065 @param n Section number (from 0 to nsec-1). 00066 @return Pointer to char string 00067 00068 This function locates the n-th section in a dictionary and returns 00069 its name as a pointer to a string statically allocated inside the 00070 dictionary. Do not free or modify the returned string! 00071 00072 This function returns NULL in case of error. 00073 */ 00074 /*--------------------------------------------------------------------------*/ 00075 00076 char * iniparser_getsecname(dictionary * d, int n); 00077 00078 00079 /*-------------------------------------------------------------------------*/ 00080 /** 00081 @brief Save a dictionary to a loadable ini file 00082 @param d Dictionary to dump 00083 @param f Opened file pointer to dump to 00084 @return void 00085 00086 This function dumps a given dictionary into a loadable ini file. 00087 It is Ok to specify @c stderr or @c stdout as output files. 00088 */ 00089 /*--------------------------------------------------------------------------*/ 00090 00091 void iniparser_dump_ini(dictionary * d, FILE * f); 00092 00093 /*-------------------------------------------------------------------------*/ 00094 /** 00095 @brief Dump a dictionary to an opened file pointer. 00096 @param d Dictionary to dump. 00097 @param f Opened file pointer to dump to. 00098 @return void 00099 00100 This function prints out the contents of a dictionary, one element by 00101 line, onto the provided file pointer. It is OK to specify @c stderr 00102 or @c stdout as output files. This function is meant for debugging 00103 purposes mostly. 00104 */ 00105 /*--------------------------------------------------------------------------*/ 00106 void iniparser_dump(dictionary * d, FILE * f); 00107 00108 /*-------------------------------------------------------------------------*/ 00109 /** 00110 @brief Get the string associated to a key, return NULL if not found 00111 @param d Dictionary to search 00112 @param key Key string to look for 00113 @return pointer to statically allocated character string, or NULL. 00114 00115 This function queries a dictionary for a key. A key as read from an 00116 ini file is given as "section:key". If the key cannot be found, 00117 NULL is returned. 00118 The returned char pointer is pointing to a string allocated in 00119 the dictionary, do not free or modify it. 00120 00121 This function is only provided for backwards compatibility with 00122 previous versions of iniparser. It is recommended to use 00123 iniparser_getstring() instead. 00124 */ 00125 /*--------------------------------------------------------------------------*/ 00126 char * iniparser_getstr(dictionary * d, const char * key); 00127 00128 00129 /*-------------------------------------------------------------------------*/ 00130 /** 00131 @brief Get the string associated to a key 00132 @param d Dictionary to search 00133 @param key Key string to look for 00134 @param def Default value to return if key not found. 00135 @return pointer to statically allocated character string 00136 00137 This function queries a dictionary for a key. A key as read from an 00138 ini file is given as "section:key". If the key cannot be found, 00139 the pointer passed as 'def' is returned. 00140 The returned char pointer is pointing to a string allocated in 00141 the dictionary, do not free or modify it. 00142 */ 00143 /*--------------------------------------------------------------------------*/ 00144 char * iniparser_getstring(dictionary * d, const char * key, char * def); 00145 00146 /*-------------------------------------------------------------------------*/ 00147 /** 00148 @brief Get the string associated to a key, convert to an int 00149 @param d Dictionary to search 00150 @param key Key string to look for 00151 @param notfound Value to return in case of error 00152 @return integer 00153 00154 This function queries a dictionary for a key. A key as read from an 00155 ini file is given as "section:key". If the key cannot be found, 00156 the notfound value is returned. 00157 00158 Supported values for integers include the usual C notation 00159 so decimal, octal (starting with 0) and hexadecimal (starting with 0x) 00160 are supported. Examples: 00161 00162 - "42" -> 42 00163 - "042" -> 34 (octal -> decimal) 00164 - "0x42" -> 66 (hexa -> decimal) 00165 00166 Warning: the conversion may overflow in various ways. Conversion is 00167 totally outsourced to strtol(), see the associated man page for overflow 00168 handling. 00169 00170 Credits: Thanks to A. Becker for suggesting strtol() 00171 */ 00172 /*--------------------------------------------------------------------------*/ 00173 int iniparser_getint(dictionary * d, const char * key, int notfound); 00174 00175 /*-------------------------------------------------------------------------*/ 00176 /** 00177 @brief Get the string associated to a key, convert to a double 00178 @param d Dictionary to search 00179 @param key Key string to look for 00180 @param notfound Value to return in case of error 00181 @return double 00182 00183 This function queries a dictionary for a key. A key as read from an 00184 ini file is given as "section:key". If the key cannot be found, 00185 the notfound value is returned. 00186 */ 00187 /*--------------------------------------------------------------------------*/ 00188 double iniparser_getdouble(dictionary * d, char * key, double notfound); 00189 00190 /*-------------------------------------------------------------------------*/ 00191 /** 00192 @brief Get the string associated to a key, convert to a boolean 00193 @param d Dictionary to search 00194 @param key Key string to look for 00195 @param notfound Value to return in case of error 00196 @return integer 00197 00198 This function queries a dictionary for a key. A key as read from an 00199 ini file is given as "section:key". If the key cannot be found, 00200 the notfound value is returned. 00201 00202 A true boolean is found if one of the following is matched: 00203 00204 - A string starting with 'y' 00205 - A string starting with 'Y' 00206 - A string starting with 't' 00207 - A string starting with 'T' 00208 - A string starting with '1' 00209 00210 A false boolean is found if one of the following is matched: 00211 00212 - A string starting with 'n' 00213 - A string starting with 'N' 00214 - A string starting with 'f' 00215 - A string starting with 'F' 00216 - A string starting with '0' 00217 00218 The notfound value returned if no boolean is identified, does not 00219 necessarily have to be 0 or 1. 00220 */ 00221 /*--------------------------------------------------------------------------*/ 00222 int iniparser_getboolean(dictionary * d, const char * key, int notfound); 00223 00224 00225 /*-------------------------------------------------------------------------*/ 00226 /** 00227 @brief Set an entry in a dictionary. 00228 @param ini Dictionary to modify. 00229 @param entry Entry to modify (entry name) 00230 @param val New value to associate to the entry. 00231 @return int 0 if Ok, -1 otherwise. 00232 00233 If the given entry can be found in the dictionary, it is modified to 00234 contain the provided value. If it cannot be found, -1 is returned. 00235 It is Ok to set val to NULL. 00236 */ 00237 /*--------------------------------------------------------------------------*/ 00238 00239 int iniparser_setstr(dictionary * ini, char * entry, char * val); 00240 00241 /*-------------------------------------------------------------------------*/ 00242 /** 00243 @brief Delete an entry in a dictionary 00244 @param ini Dictionary to modify 00245 @param entry Entry to delete (entry name) 00246 @return void 00247 00248 If the given entry can be found, it is deleted from the dictionary. 00249 */ 00250 /*--------------------------------------------------------------------------*/ 00251 void iniparser_unset(dictionary * ini, char * entry); 00252 00253 /*-------------------------------------------------------------------------*/ 00254 /** 00255 @brief Finds out if a given entry exists in a dictionary 00256 @param ini Dictionary to search 00257 @param entry Name of the entry to look for 00258 @return integer 1 if entry exists, 0 otherwise 00259 00260 Finds out if a given entry exists in the dictionary. Since sections 00261 are stored as keys with NULL associated values, this is the only way 00262 of querying for the presence of sections in a dictionary. 00263 */ 00264 /*--------------------------------------------------------------------------*/ 00265 int iniparser_find_entry(dictionary * ini, char * entry) ; 00266 00267 /*-------------------------------------------------------------------------*/ 00268 /** 00269 @brief Parse an ini file and return an allocated dictionary object 00270 @param ininame Name of the ini file to read. 00271 @return Pointer to newly allocated dictionary 00272 00273 This is the parser for ini files. This function is called, providing 00274 the name of the file to be read. It returns a dictionary object that 00275 should not be accessed directly, but through accessor functions 00276 instead. 00277 00278 The returned dictionary must be freed using iniparser_freedict(). 00279 */ 00280 /*--------------------------------------------------------------------------*/ 00281 dictionary * iniparser_load(const char * ininame); 00282 00283 /*-------------------------------------------------------------------------*/ 00284 /** 00285 @brief Free all memory associated to an ini dictionary 00286 @param d Dictionary to free 00287 @return void 00288 00289 Free all memory associated to an ini dictionary. 00290 It is mandatory to call this function before the dictionary object 00291 gets out of the current context. 00292 */ 00293 /*--------------------------------------------------------------------------*/ 00294 void iniparser_freedict(dictionary * d); 00295 00296 #endif