libconfini
Yet another INI parser
confini.h
Go to the documentation of this file.
1 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*- */
2 
15 #ifndef _LIBCONFINI_HEADER_
16 #define _LIBCONFINI_HEADER_
17 
18 
19 
20 #include <stdio.h>
21 #include <stdint.h>
22 
23 
24 
25 /* PRIVATE (HEADER-SCOPED) MACROS */
26 
27 
28 #define _LIBCONFINI_INIFORMAT_DESCR_(NAME, OFFSET, SIZE, DEFVAL) \
29  unsigned char NAME:SIZE;
30 #define _LIBCONFINI_DEFAULT_FMT_DESCR_(NAME, OFFSET, SIZE, DEFVAL) DEFVAL,
31 #define _LIBCONFINI_UNIXLIKE_FMT_DESCR_(NAME, OFFSET, SIZE, DEFVAL) 0,
32 #define _LIBCONFINI_INIFORMAT_TYPE_ \
33  struct IniFormat { INIFORMAT_TABLE_AS(_LIBCONFINI_INIFORMAT_DESCR_) }
34 #define _LIBCONFINI_DEFAULT_FORMAT_ \
35  { INIFORMAT_TABLE_AS(_LIBCONFINI_DEFAULT_FMT_DESCR_) }
36 #define _LIBCONFINI_UNIXLIKE_FORMAT_ \
37  { INIFORMAT_TABLE_AS(_LIBCONFINI_UNIXLIKE_FMT_DESCR_) }
38 
39 
40 
41 /* PUBLIC MACROS */
42 
43 
47 /*
48  NOTE: The following table and the order of its rows **define** (and link
49  together) both the #IniFormat and #IniFormatNum data types declared in this
50  header
51 */
52 #define INIFORMAT_TABLE_AS(_____) /* IniFormat table *\
53 
54  NAME BIT SIZE DEFAULT
55  */\
56 _____( delimiter_symbol, 0, 7, INI_EQUALS ) \
57 _____( case_sensitive, 7, 1, 0 )/*
58  */\
59 _____( semicolon_marker, 8, 2, INI_DISABLED_OR_COMMENT ) \
60 _____( hash_marker, 10, 2, INI_DISABLED_OR_COMMENT ) \
61 _____( section_paths, 12, 2, INI_ABSOLUTE_AND_RELATIVE ) \
62 _____( multiline_nodes, 14, 2, INI_MULTILINE_EVERYWHERE )/*
63  */\
64 _____( no_single_quotes, 16, 1, 0 ) \
65 _____( no_double_quotes, 17, 1, 0 ) \
66 _____( no_spaces_in_names, 18, 1, 0 ) \
67 _____( implicit_is_not_empty, 19, 1, 0 ) \
68 _____( do_not_collapse_values, 20, 1, 0 ) \
69 _____( preserve_empty_quotes, 21, 1, 0 ) \
70 _____( disabled_after_space, 22, 1, 0 ) \
71 _____( disabled_can_be_implicit, 23, 1, 0 )
72 
73 
74 
78 #define INIFORMAT_HAS_NO_ESC(FORMAT) \
79  (FORMAT.multiline_nodes == INI_NO_MULTILINE && \
80  FORMAT.no_double_quotes && FORMAT.no_single_quotes)
81 
82 
83 
84 /* PUBLIC TYPEDEFS */
85 
86 
90 typedef _LIBCONFINI_INIFORMAT_TYPE_ IniFormat;
91 
92 
96 typedef struct IniStatistics {
98  const size_t bytes;
99  const size_t members;
100 } IniStatistics;
101 
102 
106 typedef struct IniDispatch {
108  uint8_t type;
109  char * data;
110  char * value;
111  const char * append_to;
112  size_t d_len;
113  size_t v_len;
114  size_t at_len;
115  size_t dispatch_id;
116 } IniDispatch;
117 
118 
122 typedef uint32_t IniFormatNum;
123 
124 
128 typedef int (* IniStatsHandler) (
129  IniStatistics * statistics,
130  void * user_data
131 );
132 
133 
137 typedef int (* IniDispHandler) (
138  IniDispatch * dispatch,
139  void * user_data
140 );
141 
142 
146 typedef int (* IniStrHandler) (
147  char * ini_string,
148  size_t string_length,
149  size_t string_num,
150  IniFormat format,
151  void * user_data
152 );
153 
154 
158 typedef int (* IniSubstrHandler) (
159  const char * ini_string,
160  size_t fragm_offset,
161  size_t fragm_length,
162  size_t fragm_num,
163  IniFormat format,
164  void * user_data
165 );
166 
167 
168 
169 /* PUBLIC FUNCTIONS */
170 
171 
172 extern int strip_ini_cache (
173  register char * const ini_source,
174  const size_t ini_length,
175  const IniFormat format,
176  const IniStatsHandler f_init,
177  const IniDispHandler f_foreach,
178  void * const user_data
179 );
180 
181 
182 extern int load_ini_file (
183  FILE * const ini_file,
184  const IniFormat format,
185  const IniStatsHandler f_init,
186  const IniDispHandler f_foreach,
187  void * const user_data
188 );
189 
190 
191 extern int load_ini_path (
192  const char * const path,
193  const IniFormat format,
194  const IniStatsHandler f_init,
195  const IniDispHandler f_foreach,
196  void * const user_data
197 );
198 
199 
200 extern _Bool ini_string_match_ss (
201  const char * const simple_string_a,
202  const char * const simple_string_b,
203  const IniFormat format
204 );
205 
206 
207 extern _Bool ini_string_match_si (
208  const char * const simple_string,
209  const char * const ini_string,
210  const IniFormat format
211 );
212 
213 
214 extern _Bool ini_string_match_ii (
215  const char * const ini_string_a,
216  const char * const ini_string_b,
217  const IniFormat format
218 );
219 
220 
221 extern _Bool ini_array_match (
222  const char * const ini_string_a,
223  const char * const ini_string_b,
224  const char delimiter,
225  const IniFormat format
226 );
227 
228 
229 extern size_t ini_unquote (
230  char * const ini_string,
231  const IniFormat format
232 );
233 
234 
235 extern size_t ini_string_parse (
236  char * const ini_string,
237  const IniFormat format
238 );
239 
240 
241 extern size_t ini_array_get_length (
242  const char * const ini_string,
243  const char delimiter,
244  const IniFormat format
245 );
246 
247 
248 extern int ini_array_foreach (
249  const char * const ini_string,
250  const char delimiter,
251  const IniFormat format,
252  const IniSubstrHandler f_foreach,
253  void * const user_data
254 );
255 
256 
257 extern size_t ini_array_shift (
258  const char ** const ini_strptr,
259  const char delimiter,
260  const IniFormat format
261 );
262 
263 
264 extern size_t ini_array_collapse (
265  char * const ini_string,
266  const char delimiter,
267  const IniFormat format
268 );
269 
270 
271 extern char * ini_array_break (
272  char * const ini_string,
273  const char delimiter,
274  const IniFormat format
275 );
276 
277 
278 extern char * ini_array_release (
279  char ** ini_strptr,
280  const char delimiter,
281  const IniFormat format
282 );
283 
284 
285 extern int ini_array_split (
286  char * const ini_string,
287  const char delimiter,
288  const IniFormat format,
289  const IniStrHandler f_foreach,
290  void * const user_data
291 );
292 
293 
294 extern void ini_global_set_lowercase_mode (
295  _Bool lowercase
296 );
297 
298 
299 extern void ini_global_set_implicit_value (
300  char * const implicit_value,
301  const size_t implicit_v_len
302 );
303 
304 
305 extern IniFormatNum ini_fton (
306  const IniFormat format
307 );
308 
309 
310 extern IniFormat ini_ntof (
311  IniFormatNum format_id
312 );
313 
314 
315 extern int ini_get_bool (
316  const char * const ini_string,
317  const int return_value
318 );
319 
320 
321 
322 /* PUBLIC LINKS */
323 
324 
325 extern int (* const ini_get_int) (
326  const char * ini_string
327 );
328 
329 
330 extern long int (* const ini_get_lint) (
331  const char * ini_string
332 );
333 
334 
335 extern long long int (* const ini_get_llint) (
336  const char * ini_string
337 );
338 
339 
340 extern double (* const ini_get_float) (
341  const char * ini_string
342 );
343 
344 
345 
346 /* PUBLIC CONSTANTS AND VARIABLES */
347 
348 
352 #define CONFINI_ERROR 252
353 
354 
370 };
371 
372 
378  INI_VALUE = 1,
381  INI_KEY = 2,
387 };
388 
389 
398  INI_EQUALS = '=',
399  INI_COLON = ':',
400  INI_DOT = '.',
401  INI_COMMA = ','
402 };
403 
404 
418 };
419 
420 
437 };
438 
439 
455 };
456 
457 
461 static const IniFormat INI_DEFAULT_FORMAT = _LIBCONFINI_DEFAULT_FORMAT_;
462 
463 
468 /* All properties are set to `0` here. */
469 static const IniFormat INI_UNIXLIKE_FORMAT = _LIBCONFINI_UNIXLIKE_FORMAT_;
470 
471 
477 extern _Bool INI_GLOBAL_LOWERCASE_MODE;
478 
479 
483 extern char * INI_GLOBAL_IMPLICIT_VALUE;
484 
485 
491 extern size_t INI_GLOBAL_IMPLICIT_V_LEN;
492 
493 
494 
495 /* CLEAN THE PRIVATE ENVIRONMENT */
496 
497 
498 #undef _LIBCONFINI_UNIXLIKE_FORMAT_
499 #undef _LIBCONFINI_DEFAULT_FORMAT_
500 #undef _LIBCONFINI_INIFORMAT_TYPE_
501 #undef _LIBCONFINI_UNIXLIKE_FMT_DESCR_
502 #undef _LIBCONFINI_DEFAULT_FMT_DESCR_
503 #undef _LIBCONFINI_INIFORMAT_DESCR_
504 
505 
506 
507 /* END OF `_LIBCONFINI_HEADER_` */
508 
509 
510 #endif
511 
512 
513 
514 /* EOF */
515 
INI_NO_SECTIONS
Definition: confini.h:434
ini_array_split
int ini_array_split(char *const ini_string, const char delimiter, const IniFormat format, const IniStrHandler f_foreach, void *const user_data)
Splits a stringified INI array into NUL-separated members and calls a custom function for each member...
Definition: confini.c:4471
INI_DOT
Definition: confini.h:400
INI_MULTILINE_EVERYWHERE
Definition: confini.h:444
ini_string_match_ii
_Bool ini_string_match_ii(const char *const ini_string_a, const char *const ini_string_b, const IniFormat format)
Compares two INI strings and checks if they match.
Definition: confini.c:3065
INI_UNKNOWN
Definition: confini.h:377
INI_BUT_DISABLED_AND_COMMENTS
Definition: confini.h:450
ini_get_lint
long int(*const ini_get_lint)(const char *ini_string)
Link to atol()
Definition: confini.c:4745
CONFINI_EOOR
Definition: confini.h:368
INI_DISABLED_SECTION
Definition: confini.h:386
IniDispatch::format
const IniFormat format
Definition: confini.h:107
IniFormatNum
uint32_t IniFormatNum
The unique ID number of an INI format (24-bit maximum)
Definition: confini.h:122
IniDispatch::v_len
size_t v_len
Definition: confini.h:113
IniDispatch::data
char * data
Definition: confini.h:109
INI_COMMA
Definition: confini.h:401
ConfiniInterruptNo
ConfiniInterruptNo
Error codes.
Definition: confini.h:358
IniFormat
24-bit bitfield representing the format of an INI file (INI dialect)
Definition: confini.h:90
ini_get_float
double(*const ini_get_float)(const char *ini_string)
Link to atof()
Definition: confini.c:4749
ini_unquote
size_t ini_unquote(char *const ini_string, const IniFormat format)
Unescapes \', \", and \\ and removes all unescaped quotes (if single/double quotes are considered met...
Definition: confini.c:3486
IniDispatch
struct IniDispatch IniDispatch
Dispatch of a single INI node.
ini_ntof
IniFormat ini_ntof(IniFormatNum format_id)
Constructs a new IniFormat according to an IniFormatNum.
Definition: confini.c:4651
IniSubstrHandler
int(* IniSubstrHandler)(const char *ini_string, size_t fragm_offset, size_t fragm_length, size_t fragm_num, IniFormat format, void *user_data)
Callback function for handling a selected fragment of an INI string.
Definition: confini.h:158
INI_ABSOLUTE_AND_RELATIVE
Definition: confini.h:425
INI_ANY_SPACE
Definition: confini.h:395
ini_array_break
char * ini_array_break(char *const ini_string, const char delimiter, const IniFormat format)
Replaces the first delimiter found (together with the spaces that surround it) with \0
Definition: confini.c:4328
ini_fton
IniFormatNum ini_fton(const IniFormat format)
Calculates the IniFormatNum of an IniFormat.
Definition: confini.c:4630
CONFINI_ENOENT
Definition: confini.h:365
IniStatistics
Global statistics about an INI file.
Definition: confini.h:96
CONFINI_FEINTR
Definition: confini.h:363
ini_array_shift
size_t ini_array_shift(const char **const ini_strptr, const char delimiter, const IniFormat format)
Shifts the location pointed by ini_strptr to the next member of the INI array (without modifying the ...
Definition: confini.c:4041
ini_string_match_si
_Bool ini_string_match_si(const char *const simple_string, const char *const ini_string, const IniFormat format)
Compares a simple string and an INI string and and checks if they match.
Definition: confini.c:2901
CONFINI_EIO
Definition: confini.h:367
IniDelimiters
IniDelimiters
Most used key-value and array delimiters (but a delimiter may also be any other ASCII character)
Definition: confini.h:394
CONFINI_ENOMEM
Definition: confini.h:366
ini_get_llint
long long int(*const ini_get_llint)(const char *ini_string)
Link to atoll()
Definition: confini.c:4747
INI_ABSOLUTE_ONLY
Definition: confini.h:428
INI_BUT_COMMENTS
Definition: confini.h:447
load_ini_file
int load_ini_file(FILE *const ini_file, const IniFormat format, const IniStatsHandler f_init, const IniDispHandler f_foreach, void *const user_data)
Parses an INI file and dispatches its content using a FILE structure as argument.
Definition: confini.c:2676
ini_array_collapse
size_t ini_array_collapse(char *const ini_string, const char delimiter, const IniFormat format)
Compresses the distribution of the data of a stringified INI array by removing all the white spaces t...
Definition: confini.c:4131
ini_get_bool
int ini_get_bool(const char *const ini_string, const int return_value)
Checks whether a string matches one of the booleans listed in the private constant INI_BOOLEANS (case...
Definition: confini.c:4696
ini_array_release
char * ini_array_release(char **ini_strptr, const char delimiter, const IniFormat format)
Replaces the first delimiter found (together with the spaces that surround it) with \0,...
Definition: confini.c:4404
IniStatistics
struct IniStatistics IniStatistics
Global statistics about an INI file.
IniDispatch
Dispatch of a single INI node.
Definition: confini.h:106
IniStatistics::members
const size_t members
Definition: confini.h:99
INI_IGNORE
Definition: confini.h:414
INI_SECTION
Definition: confini.h:382
IniDispatch::dispatch_id
size_t dispatch_id
Definition: confini.h:115
INI_GLOBAL_IMPLICIT_V_LEN
size_t INI_GLOBAL_IMPLICIT_V_LEN
Length of the value assigned to implicit keys – this may be any unsigned number, independently of the...
Definition: confini.c:4760
strip_ini_cache
int strip_ini_cache(register char *const ini_source, const size_t ini_length, const IniFormat format, const IniStatsHandler f_init, const IniDispHandler f_foreach, void *const user_data)
Parses and tokenizes a buffer containing an INI file, then dispatches its content to a custom callbac...
Definition: confini.c:2171
ini_string_parse
size_t ini_string_parse(char *const ini_string, const IniFormat format)
Unescapes \', \", and \\ and removes all unescaped quotes (if single/double quotes are considered met...
Definition: confini.c:3614
IniFormat
struct IniFormat IniFormat
24-bit bitfield representing the format of an INI file (INI dialect)
ini_get_int
int(*const ini_get_int)(const char *ini_string)
Link to atoi()
Definition: confini.c:4743
INI_ONE_LEVEL_ONLY
Definition: confini.h:431
IniStatistics::format
const IniFormat format
Definition: confini.h:97
IniDispatch::value
char * value
Definition: confini.h:110
ini_global_set_lowercase_mode
void ini_global_set_lowercase_mode(_Bool lowercase)
Sets the value of the global variable INI_GLOBAL_LOWERCASE_MODE.
Definition: confini.c:4589
CONFINI_SUCCESS
Definition: confini.h:359
INI_INLINE_COMMENT
Definition: confini.h:384
ini_string_match_ss
_Bool ini_string_match_ss(const char *const simple_string_a, const char *const simple_string_b, const IniFormat format)
Compares two simple strings and checks if they match.
Definition: confini.c:2807
INI_DISABLED_OR_COMMENT
Definition: confini.h:411
ini_array_get_length
size_t ini_array_get_length(const char *const ini_string, const char delimiter, const IniFormat format)
Gets the length of a stringified INI array in number of members.
Definition: confini.c:3800
IniDispatch::append_to
const char * append_to
Definition: confini.h:111
INI_IS_NOT_A_MARKER
Definition: confini.h:416
INI_NO_MULTILINE
Definition: confini.h:453
IniDispHandler
int(* IniDispHandler)(IniDispatch *dispatch, void *user_data)
Callback function for handling an IniDispatch structure.
Definition: confini.h:137
IniSectionPaths
IniSectionPaths
Possible values of IniFormat::section_paths.
Definition: confini.h:424
INI_ONLY_COMMENT
Definition: confini.h:413
INI_UNIXLIKE_FORMAT
static const IniFormat INI_UNIXLIKE_FORMAT
A model format for Unix-like .conf files (where space characters are delimiters between keys and valu...
Definition: confini.h:469
IniNodeType
IniNodeType
INI node types.
Definition: confini.h:376
ini_array_match
_Bool ini_array_match(const char *const ini_string_a, const char *const ini_string_b, const char delimiter, const IniFormat format)
Compares two INI arrays and checks if they match.
Definition: confini.c:3255
INI_KEY
Definition: confini.h:381
INI_COMMENT
Definition: confini.h:383
INI_GLOBAL_LOWERCASE_MODE
_Bool INI_GLOBAL_LOWERCASE_MODE
If set to true, key and section names in case-insensitive INI formats will be dispatched lowercase,...
Definition: confini.c:4756
IniStrHandler
int(* IniStrHandler)(char *ini_string, size_t string_length, size_t string_num, IniFormat format, void *user_data)
Callback function for handling an INI string.
Definition: confini.h:146
IniMultiline
IniMultiline
Possible values of IniFormat::multiline_nodes.
Definition: confini.h:443
IniStatistics::bytes
const size_t bytes
Definition: confini.h:98
CONFINI_IINTR
Definition: confini.h:361
IniDispatch::type
uint8_t type
Definition: confini.h:108
INI_COLON
Definition: confini.h:399
INI_DISABLED_KEY
Definition: confini.h:385
INI_GLOBAL_IMPLICIT_VALUE
char * INI_GLOBAL_IMPLICIT_VALUE
Value to be assigned to implicit keys (default value: NULL)
Definition: confini.c:4758
INI_EQUALS
Definition: confini.h:398
IniDispatch::at_len
size_t at_len
Definition: confini.h:114
IniDispatch::d_len
size_t d_len
Definition: confini.h:112
load_ini_path
int load_ini_path(const char *const path, const IniFormat format, const IniStatsHandler f_init, const IniDispHandler f_foreach, void *const user_data)
Parses an INI file and dispatches its content using a path as argument.
Definition: confini.c:2744
ini_global_set_implicit_value
void ini_global_set_implicit_value(char *const implicit_value, const size_t implicit_v_len)
Sets the value to be to be assigned to implicit keys.
Definition: confini.c:4614
INI_DEFAULT_FORMAT
static const IniFormat INI_DEFAULT_FORMAT
A model format for standard INI files.
Definition: confini.h:461
ini_array_foreach
int ini_array_foreach(const char *const ini_string, const char delimiter, const IniFormat format, const IniSubstrHandler f_foreach, void *const user_data)
Calls a custom function for each member of a stringified INI array, without modifying the content of ...
Definition: confini.c:3916
IniStatsHandler
int(* IniStatsHandler)(IniStatistics *statistics, void *user_data)
Callback function for handling an IniStatistics structure.
Definition: confini.h:128
INI_VALUE
Definition: confini.h:378
IniCommentMarker
IniCommentMarker
Possible values of IniFormat::semicolon_marker and IniFormat::hash_marker (i.e., meaning of /\s+[#;]/...
Definition: confini.h:410