libconfini
Yet another INI parser
|
libconfini functions More...
Macros | |
#define | CONFINI_IO_FLAVOR CONFINI_STANDARD |
The I/O API to use (possibly overridden via -DCONFINI_IO_FLAVOR=[FLAVOR] ) More... | |
Functions | |
static unsigned char | is_some_space (const char chr, const int_least8_t depth) |
Check whether a character is a space. More... | |
static size_t | ltrim_s (const char *const str, const size_t offs, const int_least8_t depth) |
Soft left trim – does not change the buffer. More... | |
static size_t | ltrim_h (char *const str, const size_t offs, const int_least8_t depth) |
Hard left trim – does change the buffer. More... | |
static size_t | ltrim_hh (char *const str, const size_t offs, const int_least8_t depth) |
Shifting left trim – does change the buffer. More... | |
static size_t | rtrim_s (const char *const str, const size_t len, const int_least8_t depth) |
Soft right trim – does not change the buffer. More... | |
static size_t | rtrim_h (char *const str, const size_t len, const int_least8_t depth) |
Hard right trim – does change the buffer. More... | |
static size_t | urtrim_s (const char *const str, const size_t len) |
Unparsed soft right trim (right trim of /(?:\s|\\[\n\r])+$/ ) – does not change the buffer. More... | |
static void | string_tolower (char *const str) |
Convert an ASCII string to lower case. More... | |
static size_t | qultrim_h (char *const srcstr, const size_t offs, const IniFormat format) |
Unparsed hard left trim (left trim of /^(?:\s+|\\[\n\r]|''|"")+/ ) – does change the buffer. More... | |
static size_t | dqultrim_s (const char *const srcstr, const size_t offs, const IniFormat format) |
Soft left trim within an unparsed disabled entry (left trim of /(?:(?:^|\\?[\n\r])[ \t\v\f]*(?:#(?:[ \t\v\f]|''|"")*)?)+/ ) – does not change the buffer. More... | |
static size_t | getn_metachar_pos (const char *const str, const char chr, const size_t len, const IniFormat format) |
Get the position of the first occurrence out of quotes of a given character, stopping after a given number of charcters. More... | |
static size_t | get_metachar_pos (const char *const str, const char chr, const IniFormat format) |
Get the position of the first occurrence out of quotes of a given character. More... | |
static size_t | unescape_cr_lf (char *const srcstr, const size_t len, const unsigned char is_disabled, const IniFormat format) |
Replace /\\(\n\r?|\r\n?)[\t \v\f]*[#;]/ or /\\(\n\r?|\r\n?)/ with "$1" More... | |
static size_t | sanitize_section_path (char *const secpath, const IniFormat format) |
Sanitize a section path. More... | |
static size_t | collapse_everything (char *const ini_string, const IniFormat format) |
Out of quotes similar to ECMAScript ini_string.replace(/''|""/g, "").replace(/^[\n\r]\s*|\s+/g, " ") More... | |
static size_t | collapse_spaces (char *const ini_string, const IniFormat format) |
Out of quotes similar to ECMAScript ini_string.replace(/\s+/g, " ") More... | |
static size_t | collapse_empty_quotes (char *const str, const IniFormat format) |
Similar to ECMAScript str.replace(/''|""/g, "") More... | |
static size_t | uncomment (char *const srcstr, size_t len, const IniFormat format) |
Remove all comment initializers (# and/or ; ) from the beginning of each line of a comment. More... | |
static uint_least8_t | get_type_as_active (const char *const srcstr, const size_t len, const unsigned char allow_implicit, const IniFormat format) |
Try to determine the type of a member assuming it is active More... | |
static size_t | further_cuts (char *const srcstr, const IniFormat format) |
Examine a (single-/multi-line) segment and check whether it contains more than just one node. More... | |
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) |
Parse and tokenize a buffer containing an INI file, then dispatch 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) |
Parse an INI file and dispatch its content to a custom callback 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) |
Parse an INI file and dispatch its content to a custom callback 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) |
Compare two simple strings and check whether they match. More... | |
bool | ini_string_match_si (const char *const simple_string, const char *const ini_string, const IniFormat format) |
Compare a simple string and an INI string and and check whether they match. More... | |
bool | ini_string_match_ii (const char *const ini_string_a, const char *const ini_string_b, const IniFormat format) |
Compare two INI strings and check whether 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) |
Compare two INI arrays and check whether they match. More... | |
size_t | ini_unquote (char *const ini_string, const IniFormat format) |
Unescape \' , \" , and \\ and remove all unescaped quotes (when 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) |
Unescape \' , \" , and \\ and remove all unescaped quotes (when 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) |
Get 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) |
Call 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) |
Shift 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) |
Compress the distribution of the data in 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) |
Replace the first delimiter found (together with the spaces that surround it) with \0 More... | |
char * | ini_array_release (char **const ini_strptr, const char delimiter, const IniFormat format) |
Replace 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) |
Split a stringified INI array into NUL-separated members and call a custom function for each member. More... | |
void | ini_global_set_lowercase_mode (const bool lowercase) |
Set 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) |
Set the value to be to be assigned to implicit keys. More... | |
IniFormatNum | ini_fton (const IniFormat source) |
Calculate the IniFormatNum of an IniFormat. More... | |
IniFormat | ini_ntof (const IniFormatNum format_num) |
Construct a new IniFormat according to an IniFormatNum. More... | |
int | ini_get_bool (const char *const simple_string, const int when_fail) |
Check whether a simple string matches one of the booleans listed in the private constant INI_BOOLEANS (case-insensitive) More... | |
int | ini_get_bool_i (const char *const ini_string, const int when_fail, const IniFormat format) |
Check whether an INI string matches one of the booleans listed in the private constant INI_BOOLEANS (case-insensitive) More... | |
Variables | |
static const char *const | INI_BOOLEANS [][2] |
A list of possible string representations of boolean pairs. More... | |
int(*const | ini_get_int )(const char *ini_string) = atoi |
Pointer to atoi() More... | |
long int(*const | ini_get_lint )(const char *ini_string) = atol |
Pointer to atol() More... | |
long long int(*const | ini_get_llint )(const char *ini_string) = atoll |
Pointer to atoll() More... | |
double(*const | ini_get_double )(const char *ini_string) = atof |
Pointer to atof() More... | |
double(*const | ini_get_float )(const char *ini_string) = atof |
Legacy support for parsing a double data type – please do not use this function: use ini_get_double() instead. More... | |
bool | INI_GLOBAL_LOWERCASE_MODE = 0 |
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 = (char *) 0 |
Value to be assigned to implicit keys (default value: NULL ) More... | |
size_t | INI_GLOBAL_IMPLICIT_V_LEN = 0 |
Length of the value assigned to implicit keys (default value: 0 ) More... | |
libconfini functions
#define CONFINI_IO_FLAVOR CONFINI_STANDARD |
The I/O API to use (possibly overridden via -DCONFINI_IO_FLAVOR=[FLAVOR]
)
Possible values are CONFINI_STANDARD
and CONFINI_POSIX
|
static |
Similar to ECMAScript str.replace(/''|""/g, "")
str | The string to collapse |
format | The format of the INI file |
|
static |
Out of quotes similar to ECMAScript ini_string.replace(/''|""/g, "").replace(/^[\n\r]\s*|\s+/g, " ")
ini_string | The string to collapse – multi-line escape sequences must be already unescaped at this stage |
format | The format of the INI file |
|
static |
Out of quotes similar to ECMAScript ini_string.replace(/\s+/g, " ")
ini_string | The string to collapse – multi-line escape sequences must be already unescaped at this stage |
format | The format of the INI file |
|
inlinestatic |
Soft left trim within an unparsed disabled entry (left trim of /(?:(?:^|\\?[\n\r])[ \t\v\f]*(?:#(?:[ \t\v\f]|''|"")*)?)+/
) – does not change the buffer.
srcstr | The target string (it may contain multi-line escape sequences) |
offs | The offset where to start the left trim |
format | The format of the INI file |
|
static |
Examine a (single-/multi-line) segment and check whether it contains more than just one node.
srcstr | Segment to examine (it may contain multi-line escape sequences) |
format | The format of the INI file |
|
inlinestatic |
Get the position of the first occurrence out of quotes of a given character.
str | The string where to search |
chr | The character to to search |
format | The format of the INI file |
chr
or the length of str
if chr
has not been not found
|
static |
Try to determine the type of a member assuming it is active
srcstr | String containing an individual node (it may contain multi-line escape sequences) |
len | Length of the node |
allow_implicit | A boolean: true if keys without a key-value delimiter are allowed, false otherwise |
format | The format of the INI file |
|
inlinestatic |
Get the position of the first occurrence out of quotes of a given character, stopping after a given number of charcters.
str | The string where to search |
chr | The character to to search |
len | The maximum number of characters to read |
format | The format of the INI file |
chr
, or len
if chr
has not been not found char* ini_array_break | ( | char *const | ini_string, |
const char | delimiter, | ||
const IniFormat | format | ||
) |
Replace the first delimiter found (together with the spaces that surround it) with \0
ini_string | The stringified array (it can be NULL ) |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
NULL
if the remaining array is emptyUsually 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.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE this function is no-op and will return NULL
.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).size_t ini_array_collapse | ( | char *const | ini_string, |
const char | delimiter, | ||
const IniFormat | format | ||
) |
Compress the distribution of the data in a stringified INI array by removing all the white spaces that surround its delimiters, empty quotes, collapsable spaces, etc.
ini_string | The stringified array |
delimiter | The delimiter between the array members – if zero (INI_ANY_SPACE ) any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
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:
first , second , third , etc.
first,second,third,etc.
INI_ANY_SPACE
as delimiter: first second third etc.
first second third etc.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE this function is no-op and will only return the value of INI_GLOBAL_IMPLICIT_V_LEN minus the offset of ini_string
within INI_GLOBAL_IMPLICIT_VALUE.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).int ini_array_foreach | ( | const char *const | ini_string, |
const char | delimiter, | ||
const IniFormat | format, | ||
const IniSubstrHandler | f_foreach, | ||
void *const | user_data | ||
) |
Call 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.
ini_string | The stringified array (it can be NULL ) |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
f_foreach | The function that will be invoked for each array member |
user_data | A custom argument, or NULL |
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.
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).Possible return values are: CONFINI_SUCCESS, CONFINI_FEINTR.
size_t ini_array_get_length | ( | const char *const | ini_string, |
const char | delimiter, | ||
const IniFormat | format | ||
) |
Get the length of a stringified INI array in number of members.
ini_string | The stringified array (it can be NULL ) |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
Usually ini_string
comes from an IniDispatch (but any other string may be used as well).
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). bool ini_array_match | ( | const char *const | ini_string_a, |
const char *const | ini_string_b, | ||
const char | delimiter, | ||
const IniFormat | format | ||
) |
Compare two INI arrays and check whether they match.
ini_string_a | The first INI array |
ini_string_b | The second INI array |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
true
if the two arrays match, false
otherwiseThis 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
(INIFORMAT_HAS_NO_ESC()
) char* ini_array_release | ( | char **const | ini_strptr, |
const char | delimiter, | ||
const IniFormat | format | ||
) |
Replace 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.
ini_strptr | The memory location of the stringified array – it cannot be NULL , but it can point to NULL |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
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.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE this function is no-op and will set ini_strptr
to NULL
.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).size_t ini_array_shift | ( | const char **const | ini_strptr, |
const char | delimiter, | ||
const IniFormat | format | ||
) |
Shift 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.
ini_strptr | The memory location of the stringified array – it cannot be NULL , but it can point to NULL |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
Usually ini_strptr
comes from an IniDispatch (but any other string may be used as well).
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).int ini_array_split | ( | char *const | ini_string, |
const char | delimiter, | ||
const IniFormat | format, | ||
const IniStrHandler | f_foreach, | ||
void *const | user_data | ||
) |
Split a stringified INI array into NUL-separated members and call a custom function for each member.
ini_string | The stringified array (it cannot be NULL ) |
delimiter | The delimiter between the array members – if zero (see INI_ANY_SPACE), any space is delimiter (/(?:\\(?:\n\r?|\r\n?)|[\t \v\f])+/ ) |
format | The format of the INI file |
f_foreach | The function that will be invoked for each array member |
user_data | A custom argument, or NULL |
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.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE or is NULL
this function is no-op and will return an error code.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).Possible return values are: CONFINI_SUCCESS, CONFINI_EROADDR, CONFINI_FEINTR.
IniFormatNum ini_fton | ( | const IniFormat | source | ) |
Calculate the IniFormatNum of an IniFormat.
source | The IniFormat to compute |
int ini_get_bool | ( | const char *const | simple_string, |
const int | when_fail | ||
) |
Check whether a simple string matches one of the booleans listed in the private constant INI_BOOLEANS (case-insensitive)
simple_string | A string to check (it can be NULL ) |
when_fail | The value that is returned if no matching boolean is found |
0
or 1
) or when_fail
if simple_string
does not contain a valid INI booleanint ini_get_bool_i | ( | const char *const | ini_string, |
const int | when_fail, | ||
const IniFormat | format | ||
) |
Check whether an INI string matches one of the booleans listed in the private constant INI_BOOLEANS (case-insensitive)
ini_string | A string to check (it can be NULL ) |
when_fail | The value that is returned if no matching boolean is found |
format | The format of the INI file |
0
or 1
) or when_fail
if ini_string
does not contain a valid INI booleanUsually ini_string
comes from an IniDispatch (but any other string may be used as well).
The format
argument is used for the following fields:
format.no_double_quotes
format.no_single_quotes
void ini_global_set_implicit_value | ( | char *const | implicit_value, |
const size_t | implicit_v_len | ||
) |
Set the value to be to be assigned to implicit keys.
implicit_value | The string to be used as implicit value (usually "YES" , "TRUE" , or "ON" , or any other string; it can be NULL ) |
implicit_v_len | The length of implicit_value (without counting the NUL terminator; use 0 for both an empty string and NULL ) |
void ini_global_set_lowercase_mode | ( | const bool | lowercase | ) |
Set the value of the global variable INI_GLOBAL_LOWERCASE_MODE.
lowercase | The new value |
If lowercase
is true
, key and section names in case-insensitive INI formats will be dispatched lowercase, verbatim otherwise (default value: true
).
IniFormat ini_ntof | ( | const IniFormatNum | format_num | ) |
Construct a new IniFormat according to an IniFormatNum.
format_num | The IniFormatNum to parse |
format_num
>
16777215
it will be truncated to 24 bits. bool ini_string_match_ii | ( | const char *const | ini_string_a, |
const char *const | ini_string_b, | ||
const IniFormat | format | ||
) |
Compare two INI strings and check whether they match.
ini_string_a | The first INI string unescaped according to format |
ini_string_b | The second INI string unescaped according to format |
format | The format of the INI file |
true
if the two strings match, false
otherwiseThis function grants that the result of the comparison between two INI strings
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 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
(INIFORMAT_HAS_NO_ESC()
) bool ini_string_match_si | ( | const char *const | simple_string, |
const char *const | ini_string, | ||
const IniFormat | format | ||
) |
Compare a simple string and an INI string and and check whether they match.
ini_string | The INI string escaped according to format |
simple_string | The simple string |
format | The format of the INI file |
true
if the two strings match, false
otherwiseThis function grants that the result of the comparison between a simple string and an INI string
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 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
(INIFORMAT_HAS_NO_ESC()
)bool ini_string_match_ss | ( | const char *const | simple_string_a, |
const char *const | simple_string_b, | ||
const IniFormat | format | ||
) |
Compare two simple strings and check whether they match.
simple_string_a | The first simple string |
simple_string_b | The second simple string |
format | The format of the INI file |
true
if the two strings match, false
otherwiseSimple strings are user-given strings or the result of ini_string_parse(). The format
argument is used for the following fields:
format.case_sensitive
size_t ini_string_parse | ( | char *const | ini_string, |
const IniFormat | format | ||
) |
Unescape \'
, \"
, and \\
and remove all unescaped quotes (when 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.
ini_string | The string to be unescaped |
format | The format of the INI file |
This function is meant to be used to parse values. In order to parse key and section names please use ini_unquote().
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.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE this function is no-op and will only return the value of INI_GLOBAL_IMPLICIT_V_LEN minus the offset of ini_string
within INI_GLOBAL_IMPLICIT_VALUE.The format
argument is used for the following fields:
format.no_single_quotes
format.no_double_quotes
format.multiline_nodes
(INIFORMAT_HAS_NO_ESC()
)format.do_not_collapse_values
size_t ini_unquote | ( | char *const | ini_string, |
const IniFormat | format | ||
) |
Unescape \'
, \"
, and \\
and remove all unescaped quotes (when single/double quotes are considered metacharacters in respect to the format given)
ini_string | The string to be unescaped |
format | The format of the INI file |
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().
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.
ini_string
comes from INI_GLOBAL_IMPLICIT_VALUE this function is no-op and will only return the value of INI_GLOBAL_IMPLICIT_V_LEN minus the offset of ini_string
within INI_GLOBAL_IMPLICIT_VALUE.The format
argument is used for the following fields:
format.no_single_quotes
format.no_double_quotes
format.multiline_nodes
(INIFORMAT_HAS_NO_ESC()
)
|
inlinestatic |
Check whether a character is a space.
chr | The target character |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
true
if the character matches, false
otherwise int load_ini_file | ( | FILE *const | ini_file, |
const IniFormat | format, | ||
const IniStatsHandler | f_init, | ||
const IniDispHandler | f_foreach, | ||
void *const | user_data | ||
) |
Parse an INI file and dispatch its content to a custom callback using a FILE
structure as argument.
ini_file | The FILE handle pointing to the INI file to parse |
format | The format of the INI file |
f_init | The function that will be invoked before the first dispatch, or NULL |
f_foreach | The function that will be invoked for each dispatch, or NULL |
user_data | A custom argument, or NULL |
enum
ConfiniInterruptNo)--without-io-api
option was passed to the configure
script when the library was compiledThe ini_file
parameter must be a FILE
handle with read privileges. On some platforms, such as Microsoft Windows, it might be necessary 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. Adding the binary specifier guarantees portability across all platforms:
For the two parameters f_init
and f_foreach
see function strip_ini_cache().
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.
NUL
characters, if present in the file, will be removed from the dispatched strings.Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_ENOMEM, CONFINI_EIO, CONFINI_EOOR, CONFINI_EBADF, CONFINI_EFBIG.
int load_ini_path | ( | const char *const | path, |
const IniFormat | format, | ||
const IniStatsHandler | f_init, | ||
const IniDispHandler | f_foreach, | ||
void *const | user_data | ||
) |
Parse an INI file and dispatch its content to a custom callback using a path as argument.
path | The path of the INI file |
format | The format of the INI file |
f_init | The function that will be invoked before the first dispatch, or NULL |
f_foreach | The function that will be invoked for each dispatch, or NULL |
user_data | A custom argument, or NULL |
enum
ConfiniInterruptNo)--without-io-api
option was passed to the configure
script when the library was compiledFor the two parameters f_init
and f_foreach
see function strip_ini_cache().
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.
NUL
characters, if present in the file, will be removed from the dispatched strings.Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_ENOENT, CONFINI_ENOMEM, CONFINI_EIO, CONFINI_EOOR, CONFINI_EBADF, CONFINI_EFBIG.
|
inlinestatic |
Hard left trim – does change the buffer.
str | The target string |
offs | The offset where to start the left trim |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
|
inlinestatic |
Shifting left trim – does change the buffer.
str | The target string |
offs | The offset where to start the left trim |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
|
inlinestatic |
Soft left trim – does not change the buffer.
str | The target string |
offs | The offset where to start the left trim |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
|
inlinestatic |
Unparsed hard left trim (left trim of /^(?:\s+|\\[\n\r]|''|"")+/
) – does change the buffer.
srcstr | The target string (it may contain multi-line escape sequences) |
offs | The offset where to start the left trim |
format | The format of the INI file |
|
inlinestatic |
Hard right trim – does change the buffer.
str | The target string |
len | The length of the string |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
|
inlinestatic |
Soft right trim – does not change the buffer.
str | The target string |
len | The length of the string |
depth | What is actually considered a space (possible values: _CONFINI_WITH_EOL_ , _CONFINI_NO_EOL_ , _CONFINI_JUST_S_T_ ) |
|
static |
Sanitize a section path.
secpath | The section path |
format | The format of the INI file |
Out of quotes, similar to ECMAScript secpath.replace(/\.*\s*$|(?:\s*(\.))+\s*|^\s+/g, "$1").replace(/\s+/g, " ")
A section path can start with a dot (append), but cannot end with a dot. Spaces surrounding dots will be removed. Fragments surrounded by single or double quotes (if these are enabled) are prevented from changes.
|
inlinestatic |
Convert an ASCII string to lower case.
str | The target string |
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 | ||
) |
Parse and tokenize a buffer containing an INI file, then dispatch its content to a custom callback.
ini_source | The buffer containing the INI file to tokenize |
ini_length | The length of ini_source without counting the NUL terminator (if any – se below) |
format | The format of the INI file |
f_init | The function that will be invoked before the first dispatch, or NULL |
f_foreach | The function that will be invoked for each dispatch, or NULL |
user_data | A custom argument, or NULL |
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, 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.
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.
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.
NUL
characters possibly present in the buffer (with the exception of the last one).Possible return values are: CONFINI_SUCCESS, CONFINI_IINTR, CONFINI_FEINTR, CONFINI_EOOR.
|
static |
Remove all comment initializers (#
and/or ;
) from the beginning of each line of a comment.
srcstr | The comment to parse (it may contain multi-line escape sequences) |
len | The length of srcstr |
format | The format of the INI file |
srcstr.replace(/^[#;]+|(\n\r?|\r\n?)[\t \v\f]*[#;]+/g, "$1")
srcstr.replace(/^[#;]+/, "")
The argument srcstr
may begin with a comment initializer (#
or ;
depending on the format), or with the character that immediately follows it.
|
static |
Replace /\\(\n\r?|\r\n?)[\t \v\f]*[#;]/
or /\\(\n\r?|\r\n?)/
with "$1"
srcstr | The target string (it may contain multi-line escape sequences) |
len | Length of the string |
is_disabled | The string represents a disabled entry |
format | The format of the INI file |
|
inlinestatic |
Unparsed soft right trim (right trim of /(?:\s|\\[\n\r])+$/
) – does not change the buffer.
str | The target string |
len | The length of the string |
|
static |
A list of possible string representations of boolean pairs.
There may be infinite pairs here. Each pair must be organized according to the following order:
false
true
double(* const ini_get_double) (const char *ini_string) | ( | const char * | ini_string | ) | = atof |
Pointer to atof()
double(* const ini_get_float) (const char *ini_string) | ( | const char * | ini_string | ) | = atof |
Legacy support for parsing a double
data type – please do not use this function: use ini_get_double()
instead.
ini_string | The string to parse as a double |
int(* const ini_get_int) (const char *ini_string) | ( | const char * | ini_string | ) | = atoi |
Pointer to atoi()
long int(* const ini_get_lint) (const char *ini_string) | ( | const char * | ini_string | ) | = atol |
Pointer to atol()
long long int(* const ini_get_llint) (const char *ini_string) | ( | const char * | ini_string | ) | = atoll |
Pointer to atoll()
size_t INI_GLOBAL_IMPLICIT_V_LEN = 0 |
Length of the value assigned to implicit keys (default value: 0
)
char* INI_GLOBAL_IMPLICIT_VALUE = (char *) 0 |
Value to be assigned to implicit keys (default value: NULL
)
bool INI_GLOBAL_LOWERCASE_MODE = 0 |
If set to true
, key and section names in case-insensitive INI formats will be dispatched lowercase, verbatim otherwise (default value: false
)