iniparser.h

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