git.ozlabs.org Git - ccan/blob - ccan/ciniparser/ciniparser.h

   1 #ifndef _INIPARSER_H_
   2 #define _INIPARSER_H_
   3
   4 /* Copyright (c) 2000-2007 by Nicolas Devillard.
   5  * Copyright (x) 2009 by Tim Post <tinkertim@gmail.com>
   6  * MIT License
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a
   9  * copy of this software and associated documentation files (the "Software"),
  10  * to deal in the Software without restriction, including without limitation
  11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12  * and/or sell copies of the Software, and to permit persons to whom the
  13  * Software is furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24  * DEALINGS IN THE SOFTWARE.
  25  */
  26
  27 /** @addtogroup ciniparser
  28  * @{
  29  */
  30
  31 /**
  32  * @file    ciniparser.h
  33  * @author  N. Devillard
  34  * @date    Sep 2007
  35  * @version 3.0
  36  * @brief   Parser for ini files.
  37  */
  38
  39 #include <stdio.h>
  40 #include <stdlib.h>
  41 #include <string.h>
  42 #include <unistd.h>
  43
  44 #include "dictionary.h"
  45
  46 #define ciniparser_getstr(d, k)  ciniparser_getstring(d, k, NULL)
  47 #define ciniparser_setstr        ciniparser_setstring
  48
  49 /**
  50  * @brief    Get number of sections in a dictionary
  51  * @param    d   Dictionary to examine
  52  * @return   int Number of sections found in dictionary, -1 on error
  53  *
  54  * This function returns the number of sections found in a dictionary.
  55  * The test to recognize sections is done on the string stored in the
  56  * dictionary: a section name is given as "section" whereas a key is
  57  * stored as "section:key", thus the test looks for entries that do not
  58  * contain a colon.
  59  *
  60  * This clearly fails in the case a section name contains a colon, but
  61  * this should simply be avoided.
  62  */
  63 int ciniparser_getnsec(dictionary *d);
  64
  65 /**
  66  * @brief    Get name for section n in a dictionary.
  67  * @param    d   Dictionary to examine
  68  * @param    n   Section number (from 0 to nsec-1).
  69  * @return   Pointer to char string, NULL on error
  70  *
  71  * This function locates the n-th section in a dictionary and returns
  72  * its name as a pointer to a string statically allocated inside the
  73  * dictionary. Do not free or modify the returned string!
  74  */
  75 char *ciniparser_getsecname(dictionary *d, int n);
  76
  77 /**
  78  * @brief    Save a dictionary to a loadable ini file
  79  * @param    d   Dictionary to dump
  80  * @param    f   Opened file pointer to dump to
  81  * @return   void
  82  *
  83  * This function dumps a given dictionary into a loadable ini file.
  84  * It is Ok to specify @c stderr or @c stdout as output files.
  85  */
  86 void ciniparser_dump_ini(dictionary *d, FILE *f);
  87
  88 /**
  89  * @brief    Dump a dictionary to an opened file pointer.
  90  * @param    d   Dictionary to dump.
  91  * @param    f   Opened file pointer to dump to.
  92  * @return   void
  93  *
  94  * This function prints out the contents of a dictionary, one element by
  95  * line, onto the provided file pointer. It is OK to specify @c stderr
  96  * or @c stdout as output files. This function is meant for debugging
  97  * purposes mostly.
  98  */
  99 void ciniparser_dump(dictionary *d, FILE *f);
 100
 101 /**
 102  * @brief    Get the string associated to a key
 103  * @param    d       Dictionary to search
 104  * @param    key     Key string to look for
 105  * @param    def     Default value to return if key not found.
 106  * @return   pointer to statically allocated character string
 107  *
 108  * This function queries a dictionary for a key. A key as read from an
 109  * ini file is given as "section:key". If the key cannot be found,
 110  * the pointer passed as 'def' is returned.
 111  * The returned char pointer is pointing to a string allocated in
 112  * the dictionary, do not free or modify it.
 113  */
 114 char *ciniparser_getstring(dictionary *d, const char *key, char *def);
 115
 116 /**
 117  * @brief    Get the string associated to a key, convert to an int
 118  * @param    d Dictionary to search
 119  * @param    key Key string to look for
 120  * @param    notfound Value to return in case of error
 121  * @return   integer
 122  *
 123  * This function queries a dictionary for a key. A key as read from an
 124  * ini file is given as "section:key". If the key cannot be found,
 125  * the notfound value is returned.
 126  *
 127  * Supported values for integers include the usual C notation
 128  * so decimal, octal (starting with 0) and hexadecimal (starting with 0x)
 129  * are supported. Examples:
 130  *
 131  * - "42"      ->  42
 132  * - "042"     ->  34 (octal -> decimal)
 133  * - "0x42"    ->  66 (hexa  -> decimal)
 134  *
 135  * Warning: the conversion may overflow in various ways. Conversion is
 136  * totally outsourced to strtol(), see the associated man page for overflow
 137  * handling.
 138  *
 139  * Credits: Thanks to A. Becker for suggesting strtol()
 140  */
 141 int ciniparser_getint(dictionary *d, const char *key, int notfound);
 142
 143 /**
 144  * @brief    Get the string associated to a key, convert to a double
 145  * @param    d Dictionary to search
 146  * @param    key Key string to look for
 147  * @param    notfound Value to return in case of error
 148  * @return   double
 149  *
 150  * This function queries a dictionary for a key. A key as read from an
 151  * ini file is given as "section:key". If the key cannot be found,
 152  * the notfound value is returned.
 153  */
 154 double ciniparser_getdouble(dictionary *d, char *key, double notfound);
 155
 156 /**
 157  * @brief    Get the string associated to a key, convert to a boolean
 158  * @param    d Dictionary to search
 159  * @param    key Key string to look for
 160  * @param    notfound Value to return in case of error
 161  * @return   integer
 162  *
 163  * This function queries a dictionary for a key. A key as read from an
 164  * ini file is given as "section:key". If the key cannot be found,
 165  * the notfound value is returned.
 166  *
 167  * A true boolean is found if one of the following is matched:
 168  *
 169  * - A string starting with 'y'
 170  * - A string starting with 'Y'
 171  * - A string starting with 't'
 172  * - A string starting with 'T'
 173  * - A string starting with '1'
 174  *
 175  * A false boolean is found if one of the following is matched:
 176  *
 177  * - A string starting with 'n'
 178  * - A string starting with 'N'
 179  * - A string starting with 'f'
 180  * - A string starting with 'F'
 181  * - A string starting with '0'
 182  *
 183  * The notfound value returned if no boolean is identified, does not
 184  * necessarily have to be 0 or 1.
 185  */
 186 int ciniparser_getboolean(dictionary *d, const char *key, int notfound);
 187
 188 /**
 189  * @brief    Set an entry in a dictionary.
 190  * @param    ini     Dictionary to modify.
 191  * @param    entry   Entry to modify (entry name)
 192  * @param    val     New value to associate to the entry.
 193  * @return   int 0 if Ok, -1 otherwise.
 194  *
 195  * If the given entry can be found in the dictionary, it is modified to
 196  * contain the provided value. If it cannot be found, -1 is returned.
 197  * It is Ok to set val to NULL.
 198  */
 199 int ciniparser_setstring(dictionary *ini, char *entry, char *val);
 200
 201 /**
 202  * @brief    Delete an entry in a dictionary
 203  * @param    ini     Dictionary to modify
 204  * @param    entry   Entry to delete (entry name)
 205  * @return   void
 206  *
 207  * If the given entry can be found, it is deleted from the dictionary.
 208  */
 209 void ciniparser_unset(dictionary *ini, char *entry);
 210
 211 /**
 212  * @brief    Finds out if a given entry exists in a dictionary
 213  * @param    ini     Dictionary to search
 214  * @param    entry   Name of the entry to look for
 215  * @return   integer 1 if entry exists, 0 otherwise
 216  *
 217  * Finds out if a given entry exists in the dictionary. Since sections
 218  * are stored as keys with NULL associated values, this is the only way
 219  * of querying for the presence of sections in a dictionary.
 220  */
 221 int ciniparser_find_entry(dictionary *ini, char *entry) ;
 222
 223 /**
 224  * @brief    Parse an ini file and return an allocated dictionary object
 225  * @param    ininame Name of the ini file to read.
 226  * @return   Pointer to newly allocated dictionary
 227  *
 228  * This is the parser for ini files. This function is called, providing
 229  * the name of the file to be read. It returns a dictionary object that
 230  * should not be accessed directly, but through accessor functions
 231  * instead.
 232  *
 233  * The returned dictionary must be freed using ciniparser_freedict().
 234  */
 235 dictionary *ciniparser_load(const char *ininame);
 236
 237 /**
 238  * @brief    Free all memory associated to an ini dictionary
 239  * @param    d Dictionary to free
 240  * @return   void
 241  *
 242  * Free all memory associated to an ini dictionary.
 243  * It is mandatory to call this function before the dictionary object
 244  * gets out of the current context.
 245  */
 246 void ciniparser_freedict(dictionary *d);
 247
 248 /**
 249  * @brief Set an item in the dictionary
 250  * @param d      Dictionary object created by ciniparser_load()
 251  * @param entry  Entry in the dictionary to manipulate
 252  * @param val    Value to assign to the entry
 253  * @return       0 on success, -1 on error
 254  *
 255  * Remember that string values are converted by ciniparser_getboolean(),
 256  * ciniparser_getdouble(), etc. It is also OK to set an entry to NULL.
 257  */
 258 int ciniparser_set(dictionary *d, char *entry, char *val);
 259
 260 #endif
 261 /** @}
 262  */