]> git.ozlabs.org Git - ccan/blob - ccan/ciniparser/ciniparser.h
tally: Adapt tally_num to Samba coding conventions
[ccan] / 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  */