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 
91 typedef _LIBCONFINI_INIFORMAT_TYPE_ IniFormat;
92 
93 
97 typedef struct IniStatistics {
99  const size_t bytes;
100  const size_t members;
101 } IniStatistics;
102 
103 
107 typedef struct IniDispatch {
109  uint8_t type;
110  char * data;
111  char * value;
112  const char * append_to;
113  size_t d_len;
114  size_t v_len;
115  size_t at_len;
116  size_t dispatch_id;
117 } IniDispatch;
118 
119 
123 typedef uint32_t IniFormatNum;
124 
125 
129 typedef int (* IniStatsHandler) (
130  IniStatistics * statistics,
131  void * user_data
132 );
133 
134 
138 typedef int (* IniDispHandler) (
139  IniDispatch * dispatch,
140  void * user_data
141 );
142 
143 
148 typedef int (* IniStrHandler) (
149  char * ini_string,
150  size_t string_length,
151  size_t string_num,
152  IniFormat format,
153  void * user_data
154 );
155 
156 
160 typedef int (* IniSubstrHandler) (
161  const char * ini_string,
162  size_t fragm_offset,
163  size_t fragm_length,
164  size_t fragm_num,
165  IniFormat format,
166  void * user_data
167 );
168 
169 
170 
171 /* PUBLIC FUNCTIONS */
172 
173 
174 extern int strip_ini_cache (
175  register char * const ini_source,
176  const size_t ini_length,
177  const IniFormat format,
178  const IniStatsHandler f_init,
179  const IniDispHandler f_foreach,
180  void * const user_data
181 );
182 
183 
184 extern int load_ini_file (
185  FILE * const ini_file,
186  const IniFormat format,
187  const IniStatsHandler f_init,
188  const IniDispHandler f_foreach,
189  void * const user_data
190 );
191 
192 
193 extern int load_ini_path (
194  const char * const path,
195  const IniFormat format,
196  const IniStatsHandler f_init,
197  const IniDispHandler f_foreach,
198  void * const user_data
199 );
200 
201 
202 extern _Bool ini_string_match_ss (
203  const char * const simple_string_a,
204  const char * const simple_string_b,
205  const IniFormat format
206 );
207 
208 
209 extern _Bool ini_string_match_si (
210  const char * const simple_string,
211  const char * const ini_string,
212  const IniFormat format
213 );
214 
215 
216 extern _Bool ini_string_match_ii (
217  const char * const ini_string_a,
218  const char * const ini_string_b,
219  const IniFormat format
220 );
221 
222 
223 extern _Bool ini_array_match (
224  const char * const ini_string_a,
225  const char * const ini_string_b,
226  const char delimiter,
227  const IniFormat format
228 );
229 
230 
231 extern size_t ini_unquote (
232  char * const ini_string,
233  const IniFormat format
234 );
235 
236 
237 extern size_t ini_string_parse (
238  char * const ini_string,
239  const IniFormat format
240 );
241 
242 
243 extern size_t ini_array_get_length (
244  const char * const ini_string,
245  const char delimiter,
246  const IniFormat format
247 );
248 
249 
250 extern int ini_array_foreach (
251  const char * const ini_string,
252  const char delimiter,
253  const IniFormat format,
254  const IniSubstrHandler f_foreach,
255  void * const user_data
256 );
257 
258 
259 extern size_t ini_array_shift (
260  const char ** const ini_strptr,
261  const char delimiter,
262  const IniFormat format
263 );
264 
265 
266 extern size_t ini_array_collapse (
267  char * const ini_string,
268  const char delimiter,
269  const IniFormat format
270 );
271 
272 
273 extern char * ini_array_break (
274  char * const ini_string,
275  const char delimiter,
276  const IniFormat format
277 );
278 
279 
280 extern char * ini_array_release (
281  char ** const ini_strptr,
282  const char delimiter,
283  const IniFormat format
284 );
285 
286 
287 extern int ini_array_split (
288  char * const ini_string,
289  const char delimiter,
290  const IniFormat format,
291  const IniStrHandler f_foreach,
292  void * const user_data
293 );
294 
295 
296 extern void ini_global_set_lowercase_mode (
297  _Bool lowercase
298 );
299 
300 
301 extern void ini_global_set_implicit_value (
302  char * const implicit_value,
303  const size_t implicit_v_len
304 );
305 
306 
307 extern IniFormatNum ini_fton (
308  const IniFormat format
309 );
310 
311 
312 extern IniFormat ini_ntof (
313  IniFormatNum format_id
314 );
315 
316 
317 extern int ini_get_bool (
318  const char * const ini_string,
319  const int return_value
320 );
321 
322 
323 
324 /* PUBLIC LINKS */
325 
326 
327 extern int (* const ini_get_int) (
328  const char * ini_string
329 );
330 
331 
332 extern long int (* const ini_get_lint) (
333  const char * ini_string
334 );
335 
336 
337 extern long long int (* const ini_get_llint) (
338  const char * ini_string
339 );
340 
341 
342 extern double (* const ini_get_double) (
343  const char * ini_string
344 );
345 
346 
351 #define ini_get_float \
352  _Pragma("GCC warning \"function `ini_get_float()` is deprecated for parsing a `double` data type; use `ini_get_double()` instead\"") \
353  ini_get_double
354 
355 
356 
357 /* PUBLIC CONSTANTS AND VARIABLES */
358 
359 
363 #define CONFINI_ERROR 252
364 
365 
384 };
385 
386 
393  INI_VALUE = 1,
397  INI_KEY = 2,
405 };
406 
407 
416  INI_EQUALS = '=',
417  INI_COLON = ':',
418  INI_DOT = '.',
419  INI_COMMA = ','
420 };
421 
422 
436 };
437 
438 
455 };
456 
457 
473 };
474 
475 
479 static const IniFormat INI_DEFAULT_FORMAT = _LIBCONFINI_DEFAULT_FORMAT_;
480 
481 
486 /* All fields are set to `0` here. */
487 static const IniFormat INI_UNIXLIKE_FORMAT = _LIBCONFINI_UNIXLIKE_FORMAT_;
488 
489 
495 extern _Bool INI_GLOBAL_LOWERCASE_MODE;
496 
497 
501 extern char * INI_GLOBAL_IMPLICIT_VALUE;
502 
503 
509 extern size_t INI_GLOBAL_IMPLICIT_V_LEN;
510 
511 
512 
513 /* CLEAN THE PRIVATE ENVIRONMENT */
514 
515 
516 #undef _LIBCONFINI_UNIXLIKE_FORMAT_
517 #undef _LIBCONFINI_DEFAULT_FORMAT_
518 #undef _LIBCONFINI_INIFORMAT_TYPE_
519 #undef _LIBCONFINI_UNIXLIKE_FMT_DESCR_
520 #undef _LIBCONFINI_DEFAULT_FMT_DESCR_
521 #undef _LIBCONFINI_INIFORMAT_DESCR_
522 
523 
524 
525 /* END OF `_LIBCONFINI_HEADER_` */
526 
527 
528 #endif
529 
530 
531 
532 /* EOF */
533 
INI_NO_SECTIONS
Definition: confini.h:452
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:4601
INI_DOT
Definition: confini.h:418
INI_MULTILINE_EVERYWHERE
Definition: confini.h:462
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:3191
INI_UNKNOWN
Definition: confini.h:391
INI_BUT_DISABLED_AND_COMMENTS
Definition: confini.h:468
ini_get_lint
long int(*const ini_get_lint)(const char *ini_string)
Link to atol()
Definition: confini.c:4875
CONFINI_EOOR
Definition: confini.h:379
INI_DISABLED_SECTION
Definition: confini.h:403
IniDispatch::format
const IniFormat format
Definition: confini.h:108
IniFormatNum
uint32_t IniFormatNum
The unique ID of an INI format (24-bit maximum)
Definition: confini.h:123
IniDispatch::v_len
size_t v_len
Definition: confini.h:114
IniDispatch::data
char * data
Definition: confini.h:110
INI_COMMA
Definition: confini.h:419
ConfiniInterruptNo
ConfiniInterruptNo
Error codes.
Definition: confini.h:369
IniFormat
24-bit bitfield representing the format of an INI file (INI dialect)
Definition: confini.h:91
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:3616
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:4781
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:160
INI_ABSOLUTE_AND_RELATIVE
Definition: confini.h:443
INI_ANY_SPACE
Definition: confini.h:413
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:4458
ini_fton
IniFormatNum ini_fton(const IniFormat format)
Calculates the IniFormatNum of an IniFormat.
Definition: confini.c:4760
CONFINI_ENOENT
Definition: confini.h:376
IniStatistics
Global statistics about an INI file.
Definition: confini.h:97
CONFINI_FEINTR
Definition: confini.h:374
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:4171
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:3023
CONFINI_EIO
Definition: confini.h:378
CONFINI_EBADF
Definition: confini.h:381
IniDelimiters
IniDelimiters
Most used key-value and array delimiters (but a delimiter may also be any other ASCII character)
Definition: confini.h:412
CONFINI_ENOMEM
Definition: confini.h:377
ini_get_llint
long long int(*const ini_get_llint)(const char *ini_string)
Link to atoll()
Definition: confini.c:4877
INI_ABSOLUTE_ONLY
Definition: confini.h:446
INI_BUT_COMMENTS
Definition: confini.h:465
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:2768
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:4261
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:4826
IniStatistics
struct IniStatistics IniStatistics
Global statistics about an INI file.
IniDispatch
Dispatch of a single INI node.
Definition: confini.h:107
IniStatistics::members
const size_t members
Definition: confini.h:100
INI_IGNORE
Definition: confini.h:432
INI_SECTION
Definition: confini.h:398
IniDispatch::dispatch_id
size_t dispatch_id
Definition: confini.h:116
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:4896
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:2262
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:3744
ini_get_double
double(*const ini_get_double)(const char *ini_string)
Link to atof()
Definition: confini.c:4879
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:4873
INI_ONE_LEVEL_ONLY
Definition: confini.h:449
IniStatistics::format
const IniFormat format
Definition: confini.h:98
IniDispatch::value
char * value
Definition: confini.h:111
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:4719
CONFINI_EFBIG
Definition: confini.h:383
CONFINI_SUCCESS
Definition: confini.h:370
INI_INLINE_COMMENT
Definition: confini.h:401
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:2925
INI_DISABLED_OR_COMMENT
Definition: confini.h:429
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:3930
IniDispatch::append_to
const char * append_to
Definition: confini.h:112
INI_IS_NOT_A_MARKER
Definition: confini.h:434
INI_NO_MULTILINE
Definition: confini.h:471
IniDispHandler
int(* IniDispHandler)(IniDispatch *dispatch, void *user_data)
Callback function for handling an IniDispatch structure.
Definition: confini.h:138
IniSectionPaths
IniSectionPaths
Possible values of IniFormat::section_paths.
Definition: confini.h:442
INI_ONLY_COMMENT
Definition: confini.h:431
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:487
IniNodeType
IniNodeType
INI node types.
Definition: confini.h:390
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:3385
INI_KEY
Definition: confini.h:397
INI_COMMENT
Definition: confini.h:400
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:4892
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 belonging to a sequence of INI strings.
Definition: confini.h:148
IniMultiline
IniMultiline
Possible values of IniFormat::multiline_nodes.
Definition: confini.h:461
IniStatistics::bytes
const size_t bytes
Definition: confini.h:99
CONFINI_IINTR
Definition: confini.h:372
IniDispatch::type
uint8_t type
Definition: confini.h:109
INI_COLON
Definition: confini.h:417
INI_DISABLED_KEY
Definition: confini.h:402
INI_GLOBAL_IMPLICIT_VALUE
char * INI_GLOBAL_IMPLICIT_VALUE
Value to be assigned to implicit keys (default value: NULL)
Definition: confini.c:4894
INI_EQUALS
Definition: confini.h:416
IniDispatch::at_len
size_t at_len
Definition: confini.h:115
IniDispatch::d_len
size_t d_len
Definition: confini.h:113
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:2848
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:4744
INI_DEFAULT_FORMAT
static const IniFormat INI_DEFAULT_FORMAT
A model format for standard INI files.
Definition: confini.h:479
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:4046
ini_array_release
char * ini_array_release(char **const 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:4534
IniStatsHandler
int(* IniStatsHandler)(IniStatistics *statistics, void *user_data)
Callback function for handling an IniStatistics structure.
Definition: confini.h:129
INI_VALUE
Definition: confini.h:393
IniCommentMarker
IniCommentMarker
Possible values of IniFormat::semicolon_marker and IniFormat::hash_marker (i.e., meaning of /\s+[#;]/...
Definition: confini.h:428