source: thirdparty/SZ/sz/include/iniparser.h @ 2c47b73

Revision 2c47b73, 11.9 KB checked in by Hal Finkel <hfinkel@…>, 6 years ago (diff)

more work on adding SZ (latest version)

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