libconfini
Yet another INI parser
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
confini.h File Reference

libconfini header More...

#include <stdio.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  IniFormat
 24-bit bitfield representing the format of an INI file (INI dialect) More...
 
struct  IniStatistics
 Global statistics about an INI file. More...
 
struct  IniDispatch
 Dispatch of a single INI node. More...
 

Macros

#define INIFORMAT_TABLE_AS(_____)
 Calls a user-given macro for each row of the table. More...
 
#define INIFORMAT_HAS_NO_ESC(FORMAT)
 Checks whether a format does not support escape sequences. More...
 
#define CONFINI_ERROR   252
 Error mask (flags not present in user-generated interruptions) More...
 

Typedefs

typedef struct IniFormat IniFormat
 24-bit bitfield representing the format of an INI file (INI dialect) More...
 
typedef struct IniStatistics IniStatistics
 Global statistics about an INI file. More...
 
typedef struct IniDispatch IniDispatch
 Dispatch of a single INI node. More...
 
typedef uint32_t IniFormatNum
 The unique ID number of an INI format (24-bit maximum) More...
 
typedef int(* IniStatsHandler) (IniStatistics *statistics, void *user_data)
 Callback function for handling an IniStatistics structure. More...
 
typedef int(* IniDispHandler) (IniDispatch *dispatch, void *user_data)
 Callback function for handling an IniDispatch structure. More...
 
typedef 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. More...
 
typedef 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. More...
 

Enumerations

enum  ConfiniInterruptNo {
  CONFINI_SUCCESS = 0, CONFINI_IINTR = 1, CONFINI_FEINTR = 2, CONFINI_ENOENT = 4,
  CONFINI_ENOMEM = 5, CONFINI_EIO = 6, CONFINI_EOOR = 7
}
 Error codes. More...
 
enum  IniNodeType {
  INI_UNKNOWN = 0, INI_VALUE = 1, INI_KEY = 2, INI_SECTION = 3,
  INI_COMMENT = 4, INI_INLINE_COMMENT = 5, INI_DISABLED_KEY = 6, INI_DISABLED_SECTION = 7
}
 INI node types. More...
 
enum  IniDelimiters {
  INI_ANY_SPACE = 0, INI_EQUALS = '=', INI_COLON = ':', INI_DOT = '.',
  INI_COMMA = ','
}
 Most used key-value and array delimiters (but a delimiter may also be any other ASCII character) More...
 
enum  IniCommentMarker { INI_DISABLED_OR_COMMENT = 0, INI_ONLY_COMMENT = 1, INI_IGNORE = 2, INI_IS_NOT_A_MARKER = 3 }
 Possible values of IniFormat::semicolon_marker and IniFormat::hash_marker (i.e., meaning of /\s+[#;]/ in respect to a format) More...
 
enum  IniSectionPaths { INI_ABSOLUTE_AND_RELATIVE = 0, INI_ABSOLUTE_ONLY = 1, INI_ONE_LEVEL_ONLY = 2, INI_NO_SECTIONS = 3 }
 Possible values of IniFormat::section_paths. More...
 
enum  IniMultiline { INI_MULTILINE_EVERYWHERE = 0, INI_BUT_COMMENTS = 1, INI_BUT_DISABLED_AND_COMMENTS = 2, INI_NO_MULTILINE = 3 }
 Possible values of IniFormat::multiline_nodes. More...
 

Functions

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 callback. More...
 
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. More...
 
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. More...
 
_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. More...
 
_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. More...
 
_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. More...
 
_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. More...
 
size_t ini_unquote (char *const ini_string, const IniFormat format)
 Unescapes \', \", and \\ and removes all unescaped quotes (if single/double quotes are considered metacharacters in respect to the format given) More...
 
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 metacharacters in respect to the format given); if the format allows it, sequences of one or more spaces out of quotes will be collapsed. More...
 
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. More...
 
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 the buffer – useful for read-only (const) stringified arrays. More...
 
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 content of the buffer), or to NULL if the INI array has no more members – useful for read-only (const) stringified arrays. More...
 
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 that surround its delimiters, empty quotes, collapsable spaces, etc. More...
 
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 More...
 
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, then shifts the location pointed by ini_strptr to the next member of the INI array, or to NULL if the INI array has no more members. More...
 
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. More...
 
void ini_global_set_lowercase_mode (_Bool lowercase)
 Sets the value of the global variable INI_GLOBAL_LOWERCASE_MODE. More...
 
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. More...
 
IniFormatNum ini_fton (const IniFormat format)
 Calculates the IniFormatNum of an IniFormat. More...
 
IniFormat ini_ntof (IniFormatNum format_id)
 Constructs a new IniFormat according to an IniFormatNum. More...
 
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-insensitive) More...
 

Variables

int(*const ini_get_int )(const char *ini_string)
 Link to atoi() More...
 
long int(*const ini_get_lint )(const char *ini_string)
 Link to atol() More...
 
long long int(*const ini_get_llint )(const char *ini_string)
 Link to atoll() More...
 
double(*const ini_get_float )(const char *ini_string)
 Link to atof() More...
 
static const IniFormat INI_DEFAULT_FORMAT = { INI_EQUALS , 0 , INI_DISABLED_OR_COMMENT , INI_DISABLED_OR_COMMENT , INI_ABSOLUTE_AND_RELATIVE , INI_MULTILINE_EVERYWHERE , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , }
 A model format for standard INI files. More...
 
static const IniFormat INI_UNIXLIKE_FORMAT = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, }
 A model format for Unix-like .conf files (where space characters are delimiters between keys and values) More...
 
_Bool INI_GLOBAL_LOWERCASE_MODE
 If set to true, key and section names in case-insensitive INI formats will be dispatched lowercase, verbatim otherwise (default value: false) More...
 
char * INI_GLOBAL_IMPLICIT_VALUE
 Value to be assigned to implicit keys (default value: NULL) More...
 
size_t INI_GLOBAL_IMPLICIT_V_LEN
 Length of the value assigned to implicit keys – this may be any unsigned number, independently of the real length of INI_GLOBAL_IMPLICIT_VALUE (default value: 0) More...
 

Detailed Description

libconfini header

Author
Stefano Gioffré
Date
2016-2019
See also
https://github.com/madmurphy/libconfini/

Macro Definition Documentation

◆ CONFINI_ERROR

#define CONFINI_ERROR   252

Error mask (flags not present in user-generated interruptions)

◆ INIFORMAT_HAS_NO_ESC

#define INIFORMAT_HAS_NO_ESC (   FORMAT)
Value:
(FORMAT.multiline_nodes == INI_NO_MULTILINE && \
FORMAT.no_double_quotes && FORMAT.no_single_quotes)

Checks whether a format does not support escape sequences.

◆ INIFORMAT_TABLE_AS

#define INIFORMAT_TABLE_AS (   _____)
Value:
/* IniFormat table *\
NAME BIT SIZE DEFAULT
*/\
_____( delimiter_symbol, 0, 7, INI_EQUALS ) \
_____( case_sensitive, 7, 1, 0 )/*
*/\
_____( semicolon_marker, 8, 2, INI_DISABLED_OR_COMMENT ) \
_____( hash_marker, 10, 2, INI_DISABLED_OR_COMMENT ) \
_____( section_paths, 12, 2, INI_ABSOLUTE_AND_RELATIVE ) \
_____( multiline_nodes, 14, 2, INI_MULTILINE_EVERYWHERE )/*
*/\
_____( no_single_quotes, 16, 1, 0 ) \
_____( no_double_quotes, 17, 1, 0 ) \
_____( no_spaces_in_names, 18, 1, 0 ) \
_____( implicit_is_not_empty, 19, 1, 0 ) \
_____( do_not_collapse_values, 20, 1, 0 ) \
_____( preserve_empty_quotes, 21, 1, 0 ) \
_____( disabled_after_space, 22, 1, 0 ) \
_____( disabled_can_be_implicit, 23, 1, 0 )

Calls a user-given macro for each row of the table.

Content of the table:

  • Bits 1-19: INI syntax
  • Bits 20-22: INI semantics
  • Bits 23-24: Human syntax (disabled entries)

Typedef Documentation

◆ IniDispatch

typedef struct IniDispatch IniDispatch

Dispatch of a single INI node.

◆ IniDispHandler

int(* IniDispHandler)(IniDispatch *dispatch, void *user_data)

Callback function for handling an IniDispatch structure.

Parameters
dispatchA pointer to the IniDispatch to handle
user_dataThe custom argument previously passed to the caller function

◆ IniFormat

typedef struct IniFormat IniFormat

24-bit bitfield representing the format of an INI file (INI dialect)

◆ IniFormatNum

typedef uint32_t IniFormatNum

The unique ID number of an INI format (24-bit maximum)

◆ IniStatistics

typedef struct IniStatistics IniStatistics

Global statistics about an INI file.

◆ IniStatsHandler

int(* IniStatsHandler)(IniStatistics *statistics, void *user_data)

Callback function for handling an IniStatistics structure.

Parameters
statisticsA pointer to the IniStatistics to handle
user_dataThe custom argument previously passed to the caller function

◆ 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.

Parameters
ini_stringThe INI string to handle
string_lengthThe length of the INI string in bytes
string_numThe unique number that identifies ini_string within a sequence of INI strings; it equals zero if ini_string is the first or the only member of the sequence
formatThe format of the INI file from which ini_string has been extracted
user_dataThe custom argument previously passed to the caller function

◆ 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.

Parameters
ini_stringThe INI string containing the fragment to handle
fragm_offsetThe offset of the selected fragment in bytes
fragm_lengthThe length of the selected fragment in bytes
fragm_numThe unique number that identifies the selected fragment within a sequence of fragments of ini_string; it equals zero if the fragment is the first or the only member of the sequence
formatThe format of the INI file from which ini_string has been extracted
user_dataThe custom argument previously passed to the caller function

Enumeration Type Documentation

◆ ConfiniInterruptNo

Error codes.

Enumerator
CONFINI_SUCCESS 

There have been no interruptions, everything went well [value=0]

CONFINI_IINTR 

Interrupted by the user during f_init() [value=1]

CONFINI_FEINTR 

Interrupted by the user during f_foreach() [value=2]

CONFINI_ENOENT 

File inaccessible [value=4]

CONFINI_ENOMEM 

Error allocating virtual memory [value=5]

CONFINI_EIO 

Error reading the file [value=6]

CONFINI_EOOR 

Out-of-range error: callbacks are more than expected [value=7]

◆ IniCommentMarker

Possible values of IniFormat::semicolon_marker and IniFormat::hash_marker (i.e., meaning of /\s+[#;]/ in respect to a format)

Enumerator
INI_DISABLED_OR_COMMENT 

This marker opens a comment or a disabled entry

INI_ONLY_COMMENT 

This marker opens a comment

INI_IGNORE 

This marker opens a comment that must not be dispatched or counted

INI_IS_NOT_A_MARKER 

This is not a marker at all, but a normal character instead

◆ IniDelimiters

Most used key-value and array delimiters (but a delimiter may also be any other ASCII character)

Enumerator
INI_ANY_SPACE 

In multi-line INIs: /(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/, in non-multi-line INIs: /[\t \v\f])+/

INI_EQUALS 

Equals character (=)

INI_COLON 

Colon character (:)

INI_DOT 

Dot character (.)

INI_COMMA 

Comma character (,)

◆ IniMultiline

Possible values of IniFormat::multiline_nodes.

Enumerator
INI_MULTILINE_EVERYWHERE 

Comments, section paths and keys – disabled or not – are allowed to be multi-line

INI_BUT_COMMENTS 

Only section paths and keys – disabled or not – are allowed to be multi-line

INI_BUT_DISABLED_AND_COMMENTS 

Only active section paths and active keys are allowed to be multi-line

INI_NO_MULTILINE 

Multi-line escape sequences are disabled

◆ IniNodeType

INI node types.

Enumerator
INI_UNKNOWN 

Node impossible to categorize [value=0]

INI_VALUE 

Not used here (values are dispatched together with keys) – but available for user's implementations [value=1]

INI_KEY 

Key [value=2]

INI_SECTION 

Section path [value=3]

INI_COMMENT 

Comment [value=4]

INI_INLINE_COMMENT 

Inline comment [value=5]

INI_DISABLED_KEY 

Disabled key [value=6]

INI_DISABLED_SECTION 

Disabled section path [value=7]

◆ IniSectionPaths

Possible values of IniFormat::section_paths.

Enumerator
INI_ABSOLUTE_AND_RELATIVE 

Section paths starting with a dot express nesting to the current parent, to root otherwise

INI_ABSOLUTE_ONLY 

Section paths starting with a dot will be cleaned of their leading dot and appended to root

INI_ONE_LEVEL_ONLY 

Format supports sections, but the dot does not express nesting and is not a meta-character

INI_NO_SECTIONS 

Format does not support sections – /\[[^\]]*\]/g, if any, will be treated as keys!

Function Documentation

◆ 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

Parameters
ini_stringThe stringified array – it can be NULL
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
A pointer to the remaining INI array or NULL if the remaining array is empty

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

Similarly to strtok_r() this function can be used only once for a given string.

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_break.c */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (IniDispatch * dispatch, void * v_null) {
"my_array",
dispatch->data,
dispatch->format
)) {
#define DELIMITER ','
char * part_a, * part_b = dispatch->value;
while ((part_a = part_b)) {
part_b = ini_array_break(part_b, DELIMITER, dispatch->format);
ini_string_parse(part_a, dispatch->format);
printf("%s\n", part_a);
}
#undef DELIMITER
}
return 0;
}
int main () {
"../ini_files/typed_ini.conf",
NULL,
my_ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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 that surround its delimiters, empty quotes, collapsable spaces, etc.

Parameters
ini_stringThe stringified array
delimiterThe delimiter between the array members – if zero (INI_ANY_SPACE) any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
The new length of the stringified array

Out of quotes similar to ECMAScript ini_string.replace(new RegExp("^\\s+|\\s*(?:(" + delimiter + ")\\s*|($))", "g"), "$1$2"). If INI_ANY_SPACE (0) is used as delimiter, one or more different spaces (/[\t \v\f\n\r]+/) will be always collapsed to one space, independently of what the format says.

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

This function can be useful before invoking memcpy() using ini_string as source, when saving memory is a priority.

The format argument is used for the following fields:

  • format.no_single_quotes
  • format.no_double_quotes
  • format.do_not_collapse_values
  • format.preserve_empty_quotes

Examples:

  1. Using the comma as delimiter:
    • Before:  first   ,    second   ,   third   ,  etc.  
    • After: first,second,third,etc.
  2. Using INI_ANY_SPACE as delimiter:
    • Before:   first    second    third     etc.   
    • After: first second third etc.
Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_collapse.c */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <confini.h>
static int populate_strarray (
char * part,
size_t part_len,
size_t idx,
IniFormat format,
void * v_array
) {
ini_string_parse(part, format);
((char **) v_array)[idx] = part;
return 0;
}
static int my_ini_listener (IniDispatch * dispatch, void * v_null) {
"my_array",
dispatch->data,
dispatch->format
)) {
#define DELIMITER ','
char ** my_array;
size_t my_array_length;
/* Save memory with `ini_array_collapse()` */
dispatch->value,
DELIMITER,
dispatch->format
);
/* Allocate a new array of strings with `malloc()` */
my_array_length = ini_array_get_length(
dispatch->value,
DELIMITER,
dispatch->format
);
my_array = (char **) malloc(my_array_length * sizeof(char *) +
dispatch->v_len + 1);
/* Copy the strings with `memcpy()` */
memcpy(
my_array + my_array_length,
dispatch->value,
dispatch->v_len + 1
);
/* Populate the array */
(char *) (my_array + my_array_length),
DELIMITER,
dispatch->format,
populate_strarray,
my_array
);
#undef DELIMITER
/* Do something with `my_array` */
printf("Array `my_array` has been created.\n\n");
for (size_t idx = 0; idx < my_array_length; idx++) {
printf("my_array[%zu] -> %s\n", idx, my_array[idx]);
}
}
return 0;
}
int main () {
"../ini_files/typed_ini.conf",
NULL,
my_ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}
Note
The actual space occupied by the array might get reduced further after each member is parsed by ini_string_parse().

◆ 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 the buffer – useful for read-only (const) stringified arrays.

Parameters
ini_stringThe stringified array (it cannot be NULL)
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
f_foreachThe function that will be invoked for each array member
user_dataA custom argument, or NULL
Returns
Zero for success, otherwise an error code (see enum ConfiniInterruptNo)

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

The user given function f_foreach (see IniSubstrHandler data type) will be invoked with six arguments: ini_string, memb_offset (the offset of the member in bytes), memb_length (the length of the member in bytes), memb_num (the offset of the member in number of members), format (the format of the INI file), user_data (the custom argument user_data previously passed). If f_foreach returns a non-zero value the function ini_array_foreach() will be interrupted.

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_foreach.c */
#include <stdio.h>
#include <confini.h>
static int my_array_fragm_handler (
const char * ini_array,
size_t fragm_offset,
size_t fragm_length,
size_t fragm_num,
IniFormat format,
void * user_data
) {
printf("%.*s\n", (unsigned int) fragm_length, ini_array + fragm_offset);
return 0;
}
int main () {
"first, second, third",
',',
my_array_fragm_handler,
NULL
);
return 0;
}

.

◆ 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.

Parameters
ini_stringThe stringified array (it can be NULL)
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
The length of the INI array

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).

◆ 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.

Parameters
ini_string_aThe first INI array
ini_string_bThe second INI array
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
A boolean: true if the two arrays match, false otherwise

This function grants that the result of the comparison between two INI arrays will always match the the literal comparison between the individual members of both arrays after these have been parsed, one by one, by ini_string_parse() (with format.do_not_collapse_values set to false).

This function can be used, with '.' as delimiter, to compare section paths.

INI strings are the strings typically dispatched by load_ini_file(), load_ini_path() or strip_ini_cache(), which may contain quotes and the three escape sequences \\, \' and \".

In order to be suitable for both names and values, this function always considers sequences of one or more spaces out of quotes in both strings as collapsed, even when format.do_not_collapse_values is set to true.

The format argument is used for the following fields:

  • format.case_sensitive
  • format.no_double_quotes
  • format.no_single_quotes
  • format.multiline_nodes

◆ 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, then shifts the location pointed by ini_strptr to the next member of the INI array, or to NULL if the INI array has no more members.

Parameters
ini_strptrThe memory location of the stringified array – it cannot be NULL, but it can point to NULL
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
The array member that has been released

Usually ini_strptr comes from an IniDispatch (but any other string may be used as well).

Similarly to strtok_r() this function can be used only once for a given string.

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_release.c */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (IniDispatch * dispatch, void * v_null) {
"my_array",
dispatch->data,
dispatch->format
)) {
#define DELIMITER ','
char * token, * remaining = dispatch->value;
while ((
token = ini_array_release(&remaining, DELIMITER, dispatch->format)
)) {
ini_string_parse(token, dispatch->format);
printf("%s\n", token);
}
#undef DELIMITER
}
return 0;
}
int main () {
"../ini_files/typed_ini.conf",
NULL,
my_ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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 content of the buffer), or to NULL if the INI array has no more members – useful for read-only (const) stringified arrays.

Parameters
ini_strptrThe memory location of the stringified array – it cannot be NULL, but it can point to NULL
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
Returns
The length of the array member that has been left behind

Usually ini_strptr comes from an IniDispatch (but any other string may be used as well).

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_shift.c */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (IniDispatch * dispatch, void * v_null) {
"my_array",
dispatch->data,
dispatch->format
)) {
#define DELIMITER ','
size_t length;
char * left_behind, * shifted = dispatch->value;
while ((left_behind = shifted)) {
length = ini_array_shift(
(const char **) &shifted,
DELIMITER,
dispatch->format
);
printf("%.*s\n", (unsigned int) length, left_behind);
}
#undef DELIMITER
}
return 0;
}
int main () {
"../ini_files/typed_ini.conf",
NULL,
my_ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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.

Parameters
ini_stringThe stringified array (it cannot be NULL)
delimiterThe delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/)
formatThe format of the INI file
f_foreachThe function that will be invoked for each array member
user_dataA custom argument, or NULL
Returns
Zero for success, otherwise an error code (see enum ConfiniInterruptNo)

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

The user given function f_foreach (see IniStrHandler data type) will be invoked with five arguments: member (the member of the array), memb_length (the length of the member in bytes), memb_num (the offset of the member in number of members), format (the format of the INI file), user_data (the custom argument user_data previously passed). If f_foreach returns a non-zero value the function ini_array_split() will be interrupted.

Similarly to strtok_r() this function can be used only once for a given string.

Note
If delimiter matches a metacharacter within the format given ('\\', '\'' or '\"'), its role as metacharacter will have higher priority than its role as delimiter (i.e., the array will have no delimiters and will contain only one member).
/* examples/topics/ini_array_split.c */
#include <stdio.h>
#include <confini.h>
static int my_array_memb_handler (
char * arr_member,
size_t memb_length,
size_t memb_num,
IniFormat format,
void * foreach_other
) {
printf("%s\n", arr_member);
return 0;
}
int main () {
char my_ini_array[] = "first . second . third";
my_ini_array,
'.',
my_array_memb_handler,
NULL
);
return 0;
}

.

◆ ini_fton()

IniFormatNum ini_fton ( const IniFormat  source)

Calculates the IniFormatNum of an IniFormat.

Parameters
sourceThe IniFormat to compute
Returns
The unique unsigned integer that identifies the format given

◆ 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-insensitive)

Parameters
ini_stringA string to be checked
return_valueA value that is returned if no matching boolean has been found
Returns
The matching boolean value (0 or 1) or return_value if no boolean has been found

Usually ini_string comes from an IniDispatch (but any other string may be used as well).

/* examples/miscellanea/typed_ini.c */
/*
The following code will try to read an INI section called `my_section`,
expected to contain the following typed data:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.ini}
[my_section]
my_string = [string]
my_number = [number]
my_boolean = [boolean]
my_implicit_boolean
my_array = [comma-delimited array]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No errors will be generated if any of the data above are absent.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdbool.h>
#include <confini.h>
#include "../utilities/make_strarray.h"
#define MY_ARRAY_DELIMITER ','
/* My stored data */
struct ini_store {
char * my_section_my_string;
signed int my_section_my_number;
bool my_section_my_boolean;
bool my_section_my_implicit_boolean;
char ** my_section_my_array;
size_t my_section_my_arr_len;
};
static int my_init (IniStatistics * statistics, void * v_store) {
*((struct ini_store *) v_store) = (struct ini_store) {
.my_section_my_string = NULL,
.my_section_my_number = -1,
.my_section_my_boolean = false,
.my_section_my_implicit_boolean = false,
.my_section_my_array = NULL,
.my_section_my_arr_len = 0
};
return 0;
}
static int my_handler (IniDispatch * disp, void * v_store) {
struct ini_store * store = (struct ini_store *) v_store;
if (disp->type == INI_KEY && ini_string_match_si("my_section", disp->append_to, disp->format)) {
if (ini_string_match_si("my_string", disp->data, disp->format)) {
disp->v_len = ini_string_parse(disp->value, disp->format);
/* Free previous duplicate key (if any) */
if (store->my_section_my_string) {
free(store->my_section_my_string);
}
/* Allocate the new string */
store->my_section_my_string = strndup(disp->value, disp->v_len);
if (!store->my_section_my_string) {
return 1;
}
} else if (ini_string_match_si("my_number", disp->data, disp->format)) {
store->my_section_my_number = ini_get_int(disp->value);
} else if (ini_string_match_si("my_boolean", disp->data, disp->format)) {
store->my_section_my_boolean = ini_get_bool(disp->value, 0);
} else if (ini_string_match_si("my_implicit_boolean", disp->data, disp->format)) {
store->my_section_my_implicit_boolean = ini_get_bool(disp->value, 1);
} else if (ini_string_match_si("my_array", disp->data, disp->format)) {
/* Save memory (not strictly needed) */
disp->value,
MY_ARRAY_DELIMITER,
disp->format
);
/* Free previous duplicate key (if any) */
if (store->my_section_my_array) {
free(store->my_section_my_array);
}
/* Allocate a new array of strings (see examples/utilities/make_strarray.h) */
store->my_section_my_array = make_strarray(
disp->value,
disp->v_len,
MY_ARRAY_DELIMITER,
disp->format,
&store->my_section_my_arr_len
);
if (!store->my_section_my_array) {
return 1;
}
}
}
return 0;
}
static void print_stored_data (const struct ini_store * const store) {
printf(
"my_string -> %s\n"
"my_number -> %d\n"
"my_boolean -> %s\n"
"my_implicit_boolean -> %s\n"
"my_array[%zu] -> [%s",
store->my_section_my_string,
store->my_section_my_number,
store->my_section_my_boolean ? "True (`1`)" : "False (`0`)",
store->my_section_my_implicit_boolean ? "True (`1`)" : "False (`0`)",
store->my_section_my_arr_len,
store->my_section_my_arr_len ? store->my_section_my_array[0] : ""
);
for (size_t idx = 1; idx < store->my_section_my_arr_len; idx++) {
printf("|%s", store->my_section_my_array[idx]);
}
printf("]\n");
}
int main () {
IniFormat my_format;
struct ini_store my_store;
my_format = INI_DEFAULT_FORMAT;
my_format.semicolon_marker = my_format.hash_marker = INI_IGNORE;
my_format.implicit_is_not_empty = true;
"../ini_files/typed_ini.conf",
my_format,
my_init,
my_handler,
&my_store
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
print_stored_data(&my_store);
if (my_store.my_section_my_string) {
free(my_store.my_section_my_string);
}
if (my_store.my_section_my_arr_len) {
free(my_store.my_section_my_array);
}
return 0;
}

◆ 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.

Parameters
implicit_valueThe string to be used as implicit value (usually "YES", or "TRUE")
implicit_v_lenThe length of implicit_value (usually 0, independently of its real length)
Returns
Nothing
Warning
This function changes the value of one or more global variables. In order to be thread-safe this function should be used only once at beginning of execution, or otherwise a mutex logic must be introduced.
/* examples/topics/ini_global_set_implicit_value.c */
#include <stdio.h>
#include <confini.h>
#define NO 0
#define YES 1
static int ini_listener (IniDispatch * dispatch, void * v_null) {
if (dispatch->value == INI_GLOBAL_IMPLICIT_VALUE) {
printf(
"\nDATA: %s\nVALUE: %s\nNODE TYPE: %u\n"
"(This is an implicit key element)\n",
dispatch->data,
dispatch->value,
dispatch->type
);
} else {
printf(
"\nDATA: %s\nVALUE: %s\nNODE TYPE: %u\n",
dispatch->data,
dispatch->value,
dispatch->type
);
}
return 0;
}
int main () {
ini_global_set_implicit_value("[implicit default value]", 0);
/* Without setting this implicit keys will be considered empty */
my_format.implicit_is_not_empty = YES;
"../ini_files/unix-like.conf",
my_format,
NULL,
ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
}

◆ ini_global_set_lowercase_mode()

void ini_global_set_lowercase_mode ( _Bool  lowercase)

Sets the value of the global variable INI_GLOBAL_LOWERCASE_MODE.

Parameters
lowercaseThe new value
Returns
Nothing

If lowercase is true, key and section names in case-insensitive INI formats will be dispatched lowercase, verbatim otherwise (default value: true).

Warning
This function changes the value of one or more global variables. In order to be thread-safe this function should be used only once at beginning of execution, or otherwise a mutex logic must be introduced.

◆ ini_ntof()

IniFormat ini_ntof ( IniFormatNum  format_num)

Constructs a new IniFormat according to an IniFormatNum.

Parameters
format_numThe IniFormatNum to parse
Returns
The new IniFormat constructed
Note
If format_num > 16777215 it will be truncated to 24 bits.

◆ 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.

Parameters
ini_string_aThe first INI string unescaped according to format
ini_string_bThe second INI string unescaped according to format
formatThe format of the INI file
Returns
A boolean: true if the two strings match, false otherwise

This function grants that the result of the comparison between two INI strings

printf(
"%s\n",
ini_string_match_ii(my_ini_string_1, my_ini_string_2, format) ?
"They match"
:
"They don't match"
);

will always match the result of the literal comparison between the same two INI strings after these have been parsed by ini_string_parse() when format.do_not_collapse_values is set to false.

ini_string_parse(my_ini_string_1, format);
ini_string_parse(my_ini_string_2, format);
printf("%s\n",
ini_string_match_ss(my_ini_string_1, my_ini_string_2, format) ?
"They match"
:
"They don't match"
);

INI strings are the strings typically dispatched by load_ini_file(), load_ini_path() or strip_ini_cache(), which may contain quotes and the three escape sequences \\, \' and \".

In order to be suitable for both names and values, this function always considers sequences of one or more spaces out of quotes in both strings as collapsed, even when format.do_not_collapse_values is set to true.

The format argument is used for the following fields:

  • format.case_sensitive
  • format.no_double_quotes
  • format.no_single_quotes
  • format.multiline_nodes

◆ 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.

Parameters
ini_stringThe INI string escaped according to format
simple_stringThe simple string
formatThe format of the INI file
Returns
A boolean: true if the two strings match, false otherwise

This function grants that the result of the comparison between a simple string and an INI string

printf(
"%s\n",
ini_string_match_si(my_simple_string, my_ini_string, format) ?
"They match"
:
"They don't match"
);

will always match the result of the literal comparison between the simple string and the INI string after the latter has been parsed by ini_string_parse() when format.do_not_collapse_values is set to false.

ini_string_parse(my_ini_string, format);
printf(
"%s\n",
ini_string_match_ss(my_simple_string, my_ini_string, format) ?
"They match"
:
"They don't match"
);

INI strings are the strings typically dispatched by load_ini_file(), load_ini_path() or strip_ini_cache(), which may contain quotes and the three escape sequences \\, \' and \". Simple strings are user-given strings or the result of ini_string_parse().

In order to be suitable for both names and values, this function always considers sequences of one or more spaces out of quotes in the INI string as collapsed, even when format.do_not_collapse_values is set to true.

The format argument is used for the following fields:

  • format.case_sensitive
  • format.no_double_quotes
  • format.no_single_quotes
  • format.multiline_nodes
/* examples/topics/ini_string_match_si.c */
#include <stdio.h>
#include <confini.h>
static int passfinder (IniDispatch * disp, void * v_membid) {
/* Search for `password = "hello world"` in the INI file */
if (
ini_string_match_si("password", disp->data, disp->format) &&
ini_string_match_si("hello world", disp->value, disp->format)
) {
*((size_t *) v_membid) = disp->dispatch_id;
return 1;
}
return 0;
}
int main () {
size_t membid;
/* Load INI file */
int retval = load_ini_path(
"../ini_files/self_explaining.conf",
NULL,
passfinder,
&membid
);
/* Check for errors */
if (retval & CONFINI_ERROR) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
/* Check if parsing has been interrupted by `passfinder()` */
retval == CONFINI_FEINTR ?
printf(
"We found it! It's the INI element number #%zu!\n",
membid
)
:
printf("We didn't find it :-(\n");
return 0;
}

◆ 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.

Parameters
simple_string_aThe first simple string
simple_string_bThe second simple string
formatThe format of the INI file
Returns
A boolean: true if the two strings match, false otherwise

Simple strings are user-given strings or the result of ini_string_parse(). The format argument is used for the following fields:

  • format.case_sensitive

◆ 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 metacharacters in respect to the format given); if the format allows it, sequences of one or more spaces out of quotes will be collapsed.

Parameters
ini_stringThe string to be unescaped
formatThe format of the INI file
Returns
The new length of the string

This function is meant to be used to parse values. In order to parse key and section names please use ini_unquote() instead.

If you only need to compare ini_string with another string, consider to use ini_string_match_si() and ini_string_match_ii() instead of parsing the former and perform a simple comparison afterwards. These two functions are in fact able to check directly for equality between unparsed INI strings without actually modifying them.

Usually ini_string comes from an IniDispatch (but any other string may be used as well). If format.do_not_collapse_values is set to non-zero, spaces surrounding empty quotes will be collapsed together with the latter.

The format argument is used for the following fields:

  • format.no_single_quotes
  • format.no_double_quotes
  • format.multiline_nodes
  • format.do_not_collapse_values
Note
format.multiline_nodes is used only to figure out whether there are escape sequences or not. For all other purposes new line characters will be considered to be equal to any other space character, even if the format is not multi-line – in fact new line characters should never appear in non-multi-line formats .
/* examples/topics/ini_string_parse.c */
#include <stdio.h>
#include <confini.h>
static int ini_listener (IniDispatch * dispatch, void * v_null) {
if (
dispatch->type == INI_KEY || dispatch->type == INI_DISABLED_KEY
) {
ini_unquote(dispatch->data, dispatch->format);
ini_string_parse(dispatch->value, dispatch->format);
}
printf(
"DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",
dispatch->data,
dispatch->value,
dispatch->type
);
return 0;
}
int main () {
"../ini_files/self_explaining.conf",
NULL,
ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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 metacharacters in respect to the format given)

Parameters
ini_stringThe string to be unescaped
formatThe format of the INI file
Returns
The new length of the string

This function is very similar to ini_string_parse(), except that does not bother collapsing the sequences of more than one space that might result from removing empty quotes. Its purpose is to be used to parse key and section names, since these are always dispatched as already collapsed. In order to parse values, or array parts listed in values, please use ini_string_parse() instead.

If you only need to compare ini_string with another string, consider to use ini_string_match_si() and ini_string_match_ii() instead of parsing the former and perform a simple comparison afterwards. These two functions are in fact able to check directly for equality between unparsed INI strings without actually modifiyng them.

Usually ini_string comes from an IniDispatch (but any other string may be used as well). If the string does not contain quotes, or if quotes are considered to be normal characters, no changes will be made.

The format argument is used for the following fields:

  • format.no_single_quotes
  • format.no_double_quotes
  • format.multiline_nodes
/* examples/topics/ini_string_parse.c */
#include <stdio.h>
#include <confini.h>
static int ini_listener (IniDispatch * dispatch, void * v_null) {
if (
dispatch->type == INI_KEY || dispatch->type == INI_DISABLED_KEY
) {
ini_unquote(dispatch->data, dispatch->format);
ini_string_parse(dispatch->value, dispatch->format);
}
printf(
"DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",
dispatch->data,
dispatch->value,
dispatch->type
);
return 0;
}
int main () {
"../ini_files/self_explaining.conf",
NULL,
ini_listener,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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.

Parameters
ini_fileThe FILE handle pointing to the INI file to parse
formatThe format of the INI file
f_initThe function that will be invoked before the first dispatch, or NULL
f_foreachThe function that will be invoked for each dispatch, or NULL
user_dataA custom argument, or NULL
Returns
Zero for success, otherwise an error code (see enum ConfiniInterruptNo)

The ini_file parameter must be a FILE handle with read privileges. In some platforms, such as Microsoft Windows, it might be needed to add the binary specifier to the mode string ("b") in order to prevent discrepancies between the physical size of the file and its computed size:

FILE * my_file = fopen("example.conf", "rb");

The parsing algorithms used by libconfini are able to parse any type of file encoded in 8-bit code units, as long as the characters that match the regular expression /[\s\[\]\.\\;#"']/ refer to the same code points they refer to in ASCII (as they do, for example, in UTF-8 and ISO-8859-1), independently of platform-specific conventions.

Note
In order to be null-byte-injection safe, NUL characters, if present in the file, will be removed from the dispatched strings.

The user given function f_init (see IniStatsHandler data type) will be invoked with two arguments: statistics (a pointer to an IniStatistics structure containing some properties about the file read) and user_data (the custom argument user_data previously passed). If f_init returns a non-zero value the caller function will be interrupted.

The user given function f_foreach (see IniDispHandler data type) will be invoked with two arguments: dispatch (a pointer to an IniDispatch structure containing the parsed member of the INI file) and user_data (the custom argument user_data previously passed). If f_foreach returns a non-zero value the caller function will be interrupted.

Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_ENOMEM, CONFINI_EIO, CONFINI_EOOR.

/* examples/topics/load_ini_file.c */
#include <stdio.h>
#include <confini.h>
static int my_callback (IniDispatch * dispatch, void * v_null) {
printf(
"DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",
dispatch->data, dispatch->value, dispatch->type
);
return 0;
}
int main () {
FILE * const ini_file = fopen("../ini_files/delivery.conf", "rb");
if (ini_file == NULL) {
fprintf(stderr, "File doesn't exist :-(\n");
return 1;
}
ini_file,
NULL,
my_callback,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
fclose(ini_file);
return 0;
}

◆ 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.

Parameters
pathThe path of the INI file
formatThe format of the INI file
f_initThe function that will be invoked before the first dispatch, or NULL
f_foreachThe function that will be invoked for each dispatch, or NULL
user_dataA custom argument, or NULL
Returns
Zero for success, otherwise an error code (see enum ConfiniInterruptNo)

The parsing algorithms used by libconfini are able to parse any type of file encoded in 8-bit code units, as long as the characters that match the regular expression /[\s\[\]\.\\;#"']/ refer to the same code points they refer to in ASCII (as they do, for example, in UTF-8 and ISO-8859-1), independently of platform-specific conventions.

Note
In order to be null-byte-injection safe, NUL characters, if present in the file, will be removed from the dispatched strings.

For the two parameters f_init and f_foreach see function load_ini_file().

Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_ENOENT, CONFINI_ENOMEM, CONFINI_EIO, CONFINI_EOOR.

/* examples/topics/load_ini_path.c */
#include <stdio.h>
#include <confini.h>
static int my_callback (IniDispatch * dispatch, void * v_null) {
printf(
"DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",
dispatch->data, dispatch->value, dispatch->type
);
return 0;
}
int main () {
"../ini_files/delivery.conf",
NULL,
my_callback,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
return 0;
}

◆ 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 callback.

Parameters
ini_sourceThe buffer containing the INI file to tokenize
ini_lengthThe length of ini_source without counting the NUL terminator (if any)
formatThe format of the INI file
f_initThe function that will be invoked before the first dispatch, or NULL
f_foreachThe function that will be invoked for each dispatch, or NULL
user_dataA custom argument, or NULL
Returns
Zero for success, otherwise an error code (see enum ConfiniInterruptNo)

The ini_source parameter must be a valid pointer to a buffer of size ini_length + 1 and cannot be NULL. The ini_source string does not need to be NUL-terminated (although for portability it should, since this might become a requirement in the future), but it does need one extra byte where to append a NUL terminator – in fact, as soon as this function is invoked, ini_source[ini_length] will be immediately set to \0. In most cases, as when using strlen() for computing ini_length, this is not a concern, since ini_source[ini_length] will always be \0 by the very definition of strlen(), and will only get overwritten with the same value. However, if you are passing a substring of a string, for example the fragment foo=bar of the string foo=barracuda, you must expect the string to be immediately truncated into foo=bar\0acuda. In other words, ini_source must point to a memory location where at least ini_length + 1 bytes are freely usable.

After invoking strip_ini_cache(), the buffer pointed by the ini_source parameter must be considered as a corrupted buffer and should be freed or overwritten.

For more information about this function, please refer to the Library Functions Manual.

The parsing algorithms used by libconfini are able to parse any type of file encoded in 8-bit code units, as long as the characters that match the regular expression /[\s\[\]\.\\;#"']/ refer to the same code points they refer to in ASCII (as they do, for example, in UTF-8 and ISO-8859-1), independently of platform-specific conventions.

Note
In order to be null-byte-injection-safe, the NUL characters possibly present in the buffer, except the last one, will be stripped from it before the dispatching begins.

For the two parameters f_init and f_foreach see function load_ini_file().

Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_EOOR.

/* examples/topics/strip_ini_cache.c */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <confini.h>
static int my_callback (IniDispatch * dispatch, void * v_null) {
printf(
"DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",
dispatch->data, dispatch->value, dispatch->type
);
return 0;
}
int main () {
const char original_ini_buffer[] =
"[SectionOne]\n"
" \n"
"key = \"value\"\n"
"integer = 1234\n"
"real = 3.14\n"
"string1 = \"Case 1\"\n"
"string2 = 'Case 2'\n";
size_t ini_length = strlen(original_ini_buffer);
char * const ini_cache = strndup(original_ini_buffer, ini_length);
if (!ini_cache || strip_ini_cache(
ini_cache,
ini_length,
NULL,
my_callback,
NULL
)) {
fprintf(stderr, "Sorry, something went wrong :-(\n");
return 1;
}
printf(
"The previous dispatches come from the following INI buffer:\n\n"
"-----------------[original INI buffer]-----------------\n"
"%s"
"-------------------------------------------------------\n\n",
original_ini_buffer
);
printf(
"After being processed by `strip_ini_cache()`, the buffer looks "
"like this:\n"
);
printf("\n--------------------[disposed copy]--------------------\n");
for (size_t idx = 0; idx <= ini_length; idx++) {
putchar(ini_cache[idx] == 0 ? '.' : ini_cache[idx]);
}
printf("\n-------------------------------------------------------\n\n");
printf(
"The dots in the example above represent NUL characters. Remember "
"that\n`strip_ini_cache()` does not free the buffer passed, you will "
"have to do that\nby yourself!\n"
);
free(ini_cache);
return 0;
}

Variable Documentation

◆ INI_DEFAULT_FORMAT

const IniFormat INI_DEFAULT_FORMAT = { INI_EQUALS , 0 , INI_DISABLED_OR_COMMENT , INI_DISABLED_OR_COMMENT , INI_ABSOLUTE_AND_RELATIVE , INI_MULTILINE_EVERYWHERE , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , }
static

A model format for standard INI files.

◆ ini_get_float

ini_get_float

Link to atof()

◆ ini_get_int

ini_get_int

Link to atoi()

◆ ini_get_lint

ini_get_lint

Link to atol()

◆ ini_get_llint

ini_get_llint

Link to atoll()

◆ 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 real length of INI_GLOBAL_IMPLICIT_VALUE (default value: 0)

◆ INI_GLOBAL_IMPLICIT_VALUE

char* INI_GLOBAL_IMPLICIT_VALUE

Value to be assigned to implicit keys (default value: NULL)

◆ 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, verbatim otherwise (default value: false)

◆ INI_UNIXLIKE_FORMAT

const IniFormat INI_UNIXLIKE_FORMAT = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, }
static

A model format for Unix-like .conf files (where space characters are delimiters between keys and values)

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_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
IniDispatch::format
const IniFormat format
Definition: confini.h:107
IniDispatch::v_len
size_t v_len
Definition: confini.h:113
IniDispatch::data
char * data
Definition: confini.h:109
IniFormat
24-bit bitfield representing the format of an INI file (INI dialect)
Definition: confini.h:90
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
INI_ABSOLUTE_AND_RELATIVE
Definition: confini.h:425
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
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
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
IniFormat::semicolon_marker
unsigned char semicolon_marker
Definition: confini.h:90
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
IniDispatch
Dispatch of a single INI node.
Definition: confini.h:106
INI_IGNORE
Definition: confini.h:414
IniFormat::hash_marker
unsigned char hash_marker
Definition: confini.h:90
IniDispatch::dispatch_id
size_t dispatch_id
Definition: confini.h:115
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
ini_get_int
int(*const ini_get_int)(const char *ini_string)
Link to atoi()
Definition: confini.c:4743
IniDispatch::value
char * value
Definition: confini.h:110
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
CONFINI_ERROR
#define CONFINI_ERROR
Error mask (flags not present in user-generated interruptions)
Definition: confini.h:352
IniFormat::implicit_is_not_empty
unsigned char implicit_is_not_empty
Definition: confini.h:90
IniDispatch::append_to
const char * append_to
Definition: confini.h:111
confini.h
libconfini header
INI_NO_MULTILINE
Definition: confini.h:453
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
INI_KEY
Definition: confini.h:381
IniDispatch::type
uint8_t type
Definition: confini.h:108
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
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