Toby Harris / iniparser

http://ndevilla.free.fr/iniparser/ Welcome to iniParser -- version 3.1 released 08 Apr 2012 This modules offers parsing of ini files from the C level. See a complete documentation in HTML format, from this directory open the file html/index.html with any HTML-capable browser. Enjoy! N.Devillard Sun Apr 8 16:38:09 CEST 2012

Dependents:   SPK-DVIMXR

iniparser.h@0:1a9f9f36242e, 2012-09-17 (annotated)

Committer:
tobyspark
Date:
Mon Sep 17 00:33:09 2012 +0000
Revision:
0:1a9f9f36242e
//#include <unistd.h> // Not required for MBED

Who changed what in which revision?

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