Data Structures¶

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

Macros¶

#define INIFORMAT_TABLE_AS(_____)
Call a user-given macro (that accepts four arguments) for each row of the table. #define INIFORMAT_HAS_NO_ESC(FORMAT)
Check whether a format does not support escape sequences. #define INI_IS_IMPLICIT_SUBSTR(CHAR_PTR)
Check whether a given char * data type points to the global variable INI_GLOBAL_IMPLICIT_VALUE or to any fragment of it. #define CONFINI_ERROR 252
Error mask (flags not present in user-generated interruptions) #define INI_DISABLED_FLAG 4
Disabled flag (i.e. third bit, present only in non-active node types)

Typedefs¶

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

Enumerations¶

enum ConfiniInterruptNo { CONFINI_SUCCESS = 0, CONFINI_IINTR = 1, CONFINI_FEINTR = 2, CONFINI_ENOENT = 4, CONFINI_ENOMEM = 5, CONFINI_EIO = 6, CONFINI_EOOR = 7, CONFINI_EBADF = 8, CONFINI_EFBIG = 9, CONFINI_EROADDR = 10 }
Error codes. 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 and possible values of IniDispatch::type. enum IniDelimiters { INI_ANY_SPACE = 0, INI_EQUALS = '=', INI_COLON = ':', INI_DOT = '.', INI_COMMA = ',' }
Common array and key-value delimiters (but a delimiter may also be any other ASCII character not present in this list) 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 // and // in respect to a format) 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. 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.

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)
Parse and tokenize a buffer containing an INI file, then dispatch its content to a custom callback. 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. 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. 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. 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. 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. 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. 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) 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. 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. 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. 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. 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. 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   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  , 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. 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. void ini_global_set_lowercase_mode (const bool lowercase)
Set the value of the global variable INI_GLOBAL_LOWERCASE_MODE. 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. IniFormatNum ini_fton (const IniFormat format)
Calculate the IniFormatNum of an IniFormat. IniFormat ini_ntof (const IniFormatNum format_id)
Construct a new IniFormat according to an IniFormatNum. 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) 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)

Variables¶

int(*const ini_get_int )(const char *ini_string)
Pointer to atoi() long int(*const ini_get_lint )(const char *ini_string)
Pointer to atol() long long int(*const ini_get_llint )(const char *ini_string)
Pointer to atoll() double(*const ini_get_double )(const char *ini_string)
Pointer to atof() double(*const ini_get_float )(const char *ini_string)
Legacy support for parsing a double data type – please do not use this function: use ini_get_double() instead. static const IniFormat INI_DEFAULT_FORMAT = { INI_EQUALS, false, INI_DISABLED_OR_COMMENT, INI_DISABLED_OR_COMMENT, INI_ABSOLUTE_AND_RELATIVE, INI_MULTILINE_EVERYWHERE, false, false, false, false, false, false, false, false }
A model format for standard INI files. static const IniFormat INI_UNIXLIKE_FORMAT = { INI_ANY_SPACE, false, INI_DISABLED_OR_COMMENT, INI_DISABLED_OR_COMMENT, INI_ABSOLUTE_AND_RELATIVE, INI_MULTILINE_EVERYWHERE, false, false, false, false, false, false, false, false }
A model format for Unix-like .conf files (where space characters are delimiters between keys and values) 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) char * INI_GLOBAL_IMPLICIT_VALUE
Value to be assigned to implicit keys (default value: NULL) size_t INI_GLOBAL_IMPLICIT_V_LEN
Length of the value assigned to implicit keys (default value: 0)

#define CONFINI_ERROR 252¶

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

#define INI_DISABLED_FLAG 4¶

Disabled flag (i.e. third bit, present only in non-active node types) Example #1:

if (dispatch->type & INI_DISABLED_FLAG) {


    printf("This is not a real INI node...\n");
}

Example #2:

if ((dispatch->type | INI_DISABLED_FLAG) == INI_DISABLED_KEY) {


    printf("Hey! This is either an INI_KEY or an INI_DISABLED_KEY!\n");
}

See also IniNodeType.

#define INI_IS_IMPLICIT_SUBSTR(CHAR_PTR)¶

Value:

    (CHAR_PTR >= INI_GLOBAL_IMPLICIT_VALUE && CHAR_PTR <= \


    INI_GLOBAL_IMPLICIT_VALUE + INI_GLOBAL_IMPLICIT_V_LEN)

Check whether a given char * data type points to the global variable INI_GLOBAL_IMPLICIT_VALUE or to any fragment of it.

#define INIFORMAT_HAS_NO_ESC(FORMAT)¶

Value:

    (FORMAT.multiline_nodes == INI_NO_MULTILINE && \


    FORMAT.no_double_quotes && FORMAT.no_single_quotes)

Check whether a format does not support escape sequences.

#define INIFORMAT_TABLE_AS(_____)¶

Value:

/*  IniFormat table  *\


       NAME                      BIT  SIZE DEFAULT


                                                                     */\
_____( delimiter_symbol,         0,   7,   INI_EQUALS                ) \
_____( case_sensitive,           7,   1,   false                     )/*


                                                                     */\
_____( 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,   false                     ) \
_____( no_double_quotes,         17,  1,   false                     ) \
_____( no_spaces_in_names,       18,  1,   false                     ) \
_____( implicit_is_not_empty,    19,  1,   false                     ) \
_____( do_not_collapse_values,   20,  1,   false                     ) \
_____( preserve_empty_quotes,    21,  1,   false                     ) \
_____( disabled_after_space,     22,  1,   false                     ) \
_____( disabled_can_be_implicit, 23,  1,   false                     )

Call a user-given macro (that accepts four arguments) 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 struct IniFormat IniFormat¶

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

typedef struct IniDispatch IniDispatch¶

Dispatch of a single INI node.

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

Callback function for handling an IniDispatch structure.

Parameters

typedef uint_least32_t IniFormatNum¶

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

typedef struct IniStatistics IniStatistics¶

Global statistics about an INI file.

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

Callback function for handling an IniStatistics structure.

Parameters

int(* IniStrHandler)(char *ini_string, size_t string_length, size_t string_num, IniFormat format, void *user_data)¶

Callback function for handling an INI string belonging to a sequence of INI strings.

Parameters

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

enum 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]

CONFINI_EBADF

The stream specified is not a seekable stream [value=8]

CONFINI_EFBIG

File too large [value=9]

CONFINI_EROADDR

Address is read-only [value=10]

enum IniCommentMarker¶

Possible values of IniFormat::semicolon_marker and IniFormat::hash_marker (i.e., meaning of /\s+;/ and /\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 has been marked for deletion and must not be dispatched or counted

INI_IS_NOT_A_MARKER

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

enum IniDelimiters¶

Common array and key-value delimiters (but a delimiter may also be any other ASCII character not present in this list)

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 (,)

enum 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

enum IniNodeType¶

INI node types and possible values of IniDispatch::type. See also INI_DISABLED_FLAG.

Enumerator

INI_UNKNOWN

This is a node impossible to categorize [value=0]

INI_VALUE

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

INI_KEY

This is a key [value=2]

INI_SECTION

This is a section path [value=3]

INI_COMMENT

This is a comment [value=4]

INI_INLINE_COMMENT

This is an inline comment [value=5]

INI_DISABLED_KEY

This is a disabled key [value=6]

INI_DISABLED_SECTION

This is a disabled section path [value=7]

enum 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!

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

Parameters

Returns

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

/*  examples/topics/ini_array_break.c  */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (


  IniDispatch * const dispatch,


  void * const v_null
) {


  if (


    ini_string_match_si(


      "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 () {


  if (


    load_ini_path(


      "../ini_files/typed_ini.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      my_ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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.

Parameters

Returns

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

/*  examples/topics/ini_array_collapse.c  */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <confini.h>
static int populate_strarray (


  char * const part,


  const size_t part_len,


  const size_t idx,


  const IniFormat format,


  void * const v_array
) {


  ini_string_parse(part, format);


  ((char **) v_array)[idx] = part;


  return 0;
}
static int my_ini_listener (


  IniDispatch * const dispatch,


  void * const v_null
) {


  if (


    ini_string_match_si(


      "my_array",


      dispatch->data,


      dispatch->format


    )


  ) {


    #define DELIMITER ','


    char ** my_array;


    size_t my_array_length;


    /*  Save memory with `ini_array_collapse()`  */


    dispatch->v_len = 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  */


    ini_array_split(


      (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 () {


  if (


    load_ini_path(


      "../ini_files/typed_ini.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      my_ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

Note

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.

Parameters

Returns

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

Possible return values are: CONFINI_SUCCESS, CONFINI_FEINTR.

/*  examples/topics/ini_array_foreach.c  */
#include <stdio.h>
#include <confini.h>
static int my_array_fragm_handler (


  const char * const ini_array,


  const size_t fragm_offset,


  const size_t fragm_length,


  const size_t fragm_num,


  const IniFormat format,


  void * const user_data
) {


  printf("


  return 0;
}
int main () {


  ini_array_foreach(


    "first  ,  second   ,  third",


    ',',


    INI_DEFAULT_FORMAT,


    my_array_fragm_handler,


    NULL


  );


  return 0;
}

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.

Parameters

Returns

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

Note

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.

Parameters

Returns

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

Parameters

Returns

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

/*  examples/topics/ini_array_release.c  */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (


  IniDispatch * const dispatch,


  void * const v_null
) {


  if (


    ini_string_match_si(


      "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 () {


  if (


    load_ini_path(


      "../ini_files/typed_ini.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      my_ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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.

Parameters

Returns

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

Note

/*  examples/topics/ini_array_shift.c  */
#include <stdio.h>
#include <confini.h>
static int my_ini_listener (


  IniDispatch * const dispatch,


  void * const v_null
) {


  if (


    ini_string_match_si(


      "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 () {


  if (


    load_ini_path(


      "../ini_files/typed_ini.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      my_ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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.

Parameters

Returns

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

Possible return values are: CONFINI_SUCCESS, CONFINI_EROADDR, CONFINI_FEINTR.

/*  examples/topics/ini_array_split.c  */
#include <stdio.h>
#include <confini.h>
static int my_array_memb_handler (


  char * const arr_member,


  const size_t memb_length,


  const size_t memb_num,


  const IniFormat format,


  void * const foreach_other
) {


  printf("


  return 0;
}
int main () {


  char my_ini_array[] = "first .   second   . third";


  ini_array_split(


    my_ini_array,


    '.',


    INI_DEFAULT_FORMAT,


    my_array_memb_handler,


    NULL


  );


  return 0;
}

IniFormatNum ini_fton (const IniFormat source)¶

Calculate the IniFormatNum of an IniFormat.

Parameters

Returns

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)

Parameters

Returns

/*  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 <confini.h>
#include "../utilities/make_strarray.h"
#define MY_ARRAY_DELIMITER ','
/*  My stored data  */
struct ini_store {


  char * my_section_my_string;


  int my_section_my_number;


  bool my_section_my_boolean;


  bool my_section_my_implicit_bool;


  char * const * 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_bool = false,


    .my_section_my_array = NULL,


    .my_section_my_arr_len = 0


  };


  return 0;
}
static int my_handler (IniDispatch * const dsp, void * const v_store) {


  #define store ((struct ini_store *) v_store)


  #define THEYMATCH(SSTR, ISTR) \


    ini_string_match_si(SSTR, ISTR, dsp->format)


  if (dsp->type == INI_KEY && THEYMATCH("my_section", dsp->append_to)) {


    if (THEYMATCH("my_string", dsp->data)) {


      dsp->v_len = ini_string_parse(dsp->value, dsp->format);


      /*  Free previous duplicate key (if any)  */


      free(store->my_section_my_string);


      /*  Allocate the new string  */


      store->my_section_my_string = strndup(dsp->value, dsp->v_len);


      if (!store->my_section_my_string) {


        return 1;


      }


    } else if (THEYMATCH("my_number", dsp->data)) {


      store->my_section_my_number = ini_get_int(dsp->value);


    } else if (THEYMATCH("my_boolean", dsp->data)) {


      store->my_section_my_boolean = ini_get_bool_i(


        dsp->value,


        0,


        dsp->format


      );


    } else if (THEYMATCH("my_implicit_boolean", dsp->data)) {


      store->my_section_my_implicit_bool = ini_get_bool_i(


        dsp->value,


        1,


        dsp->format


      );


    } else if (THEYMATCH("my_array", dsp->data)) {


      /*  Save memory (not strictly needed)  */


      dsp->v_len = ini_array_collapse(


        dsp->value,


        MY_ARRAY_DELIMITER,


        dsp->format


      );


      /*  Free previous duplicate key (if any)  */


      free((void *) store->my_section_my_array);


      /*  Allocate a new array of strings  */


      /*  Function in examples/utilities/make_strarray.h  */


      store->my_section_my_array = make_strarray(


        &store->my_section_my_arr_len,


        dsp->value,


        dsp->v_len,


        MY_ARRAY_DELIMITER,


        dsp->format


      );


      if (!store->my_section_my_array) {


        return 1;


      }


    }


  }


  return 0;


  #undef THEYMATCH


  #undef store
}
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_bool ? "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;


  ini_global_set_implicit_value("YES", 3);


  my_format = INI_DEFAULT_FORMAT;


  my_format.implicit_is_not_empty = true;


  my_format.disabled_can_be_implicit = true;


  my_format.semicolon_marker = my_format.hash_marker = INI_IGNORE;


  if (load_ini_path(


    "../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);


  free(my_store.my_section_my_string);


  free((void *) my_store.my_section_my_array);


  return 0;
}

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)

Parameters

Returns

Usually 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

/*  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 <confini.h>
#include "../utilities/make_strarray.h"
#define MY_ARRAY_DELIMITER ','
/*  My stored data  */
struct ini_store {


  char * my_section_my_string;


  int my_section_my_number;


  bool my_section_my_boolean;


  bool my_section_my_implicit_bool;


  char * const * 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_bool = false,


    .my_section_my_array = NULL,


    .my_section_my_arr_len = 0


  };


  return 0;
}
static int my_handler (IniDispatch * const dsp, void * const v_store) {


  #define store ((struct ini_store *) v_store)


  #define THEYMATCH(SSTR, ISTR) \


    ini_string_match_si(SSTR, ISTR, dsp->format)


  if (dsp->type == INI_KEY && THEYMATCH("my_section", dsp->append_to)) {


    if (THEYMATCH("my_string", dsp->data)) {


      dsp->v_len = ini_string_parse(dsp->value, dsp->format);


      /*  Free previous duplicate key (if any)  */


      free(store->my_section_my_string);


      /*  Allocate the new string  */


      store->my_section_my_string = strndup(dsp->value, dsp->v_len);


      if (!store->my_section_my_string) {


        return 1;


      }


    } else if (THEYMATCH("my_number", dsp->data)) {


      store->my_section_my_number = ini_get_int(dsp->value);


    } else if (THEYMATCH("my_boolean", dsp->data)) {


      store->my_section_my_boolean = ini_get_bool_i(


        dsp->value,


        0,


        dsp->format


      );


    } else if (THEYMATCH("my_implicit_boolean", dsp->data)) {


      store->my_section_my_implicit_bool = ini_get_bool_i(


        dsp->value,


        1,


        dsp->format


      );


    } else if (THEYMATCH("my_array", dsp->data)) {


      /*  Save memory (not strictly needed)  */


      dsp->v_len = ini_array_collapse(


        dsp->value,


        MY_ARRAY_DELIMITER,


        dsp->format


      );


      /*  Free previous duplicate key (if any)  */


      free((void *) store->my_section_my_array);


      /*  Allocate a new array of strings  */


      /*  Function in examples/utilities/make_strarray.h  */


      store->my_section_my_array = make_strarray(


        &store->my_section_my_arr_len,


        dsp->value,


        dsp->v_len,


        MY_ARRAY_DELIMITER,


        dsp->format


      );


      if (!store->my_section_my_array) {


        return 1;


      }


    }


  }


  return 0;


  #undef THEYMATCH


  #undef store
}
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_bool ? "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;


  ini_global_set_implicit_value("YES", 3);


  my_format = INI_DEFAULT_FORMAT;


  my_format.implicit_is_not_empty = true;


  my_format.disabled_can_be_implicit = true;


  my_format.semicolon_marker = my_format.hash_marker = INI_IGNORE;


  if (load_ini_path(


    "../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);


  free(my_store.my_section_my_string);


  free((void *) my_store.my_section_my_array);


  return 0;
}

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.

Parameters

Returns

Warning

/*  examples/topics/ini_global_set_implicit_value.c  */
#include <stdio.h>
#include <confini.h>
static int ini_listener (


  IniDispatch * const dispatch,


  void * const 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 () {


  IniFormat my_format = INI_UNIXLIKE_FORMAT;


  ini_global_set_implicit_value("[implicit default value]", 24);


  /*  Without this implicit keys will be considered empty  */


  my_format.implicit_is_not_empty = true;


  my_format.disabled_can_be_implicit = true;


  if (


    load_ini_path(


      "../ini_files/unix-like.conf",


      my_format,


      NULL,


      ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }
}

void ini_global_set_lowercase_mode (const bool lowercase)¶

Set the value of the global variable INI_GLOBAL_LOWERCASE_MODE.

Deprecated

Parameters

Returns

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

Warning

IniFormat ini_ntof (const IniFormatNum format_num)¶

Construct a new IniFormat according to an IniFormatNum.

Parameters

Returns

Note

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.

Parameters

Returns

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

Parameters

Returns

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 (INIFORMAT_HAS_NO_ESC())

/*  examples/topics/ini_string_match_si.c  */
#include <stdio.h>
#include <confini.h>
static int passfinder (


  IniDispatch * const disp,


  void * const 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",


    INI_DEFAULT_FORMAT,


    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 node number %zu!\n",


                  membid


                )


              :


                printf("We didn't find it :-(\n");


  return 0;
}

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.

Parameters

Returns

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

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.

Parameters

Returns

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.

Note

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

/*  examples/topics/ini_string_parse.c  */
#include <stdio.h>
#include <confini.h>
static int ini_listener (


  IniDispatch * const dispatch,


  void * const 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 () {


  if (


    load_ini_path(


      "../ini_files/self_explaining.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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)

Parameters

Returns

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.

Note

The format argument is used for the following fields:

• format.no_single_quotes
• format.no_double_quotes
• format.multiline_nodes (INIFORMAT_HAS_NO_ESC())

/*  examples/topics/ini_string_parse.c  */
#include <stdio.h>
#include <confini.h>
static int ini_listener (


  IniDispatch * const dispatch,


  void * const 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 () {


  if (


    load_ini_path(


      "../ini_files/self_explaining.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      ini_listener,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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.

Parameters

Returns

Note

The 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:

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

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.

Note

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

/*  examples/topics/load_ini_file.c  */
#include <stdio.h>
#include <confini.h>
static int my_callback (


  IniDispatch * const dispatch,


  void * const 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;


  }


  if (


    load_ini_file(


      ini_file,


      INI_DEFAULT_FORMAT,


      NULL,


      my_callback,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  fclose(ini_file);


  return 0;
}

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.

Parameters

Returns

Note

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.

Note

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

/*  examples/topics/load_ini_path.c  */
#include <stdio.h>
#include <confini.h>
static int my_callback (


  IniDispatch * const dispatch,


  void * const v_null
) {


  printf(


    "DATA: %s\nVALUE: %s\nNODE TYPE: %u\n\n",


    dispatch->data, dispatch->value, dispatch->type


  );


  return 0;
}
int main () {


  if (


    load_ini_path(


      "../ini_files/delivery.conf",


      INI_DEFAULT_FORMAT,


      NULL,


      my_callback,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  return 0;
}

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.

Parameters

Returns

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.

Note

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 * const dispatch,


  void * const 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 =


    "integer = 1234\n"


    "real = 3.14\n"


    "string1 =


    "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,


      INI_DEFAULT_FORMAT,


      NULL,


      my_callback,


      NULL


    )


  ) {


    fprintf(stderr, "Sorry, something went wrong :-(\n");


    return 1;


  }


  printf(


    "The previous dispatches come from the following 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 buffer]---------------\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;
}

const IniFormat INI_DEFAULT_FORMAT = { INI_EQUALS, false, INI_DISABLED_OR_COMMENT, INI_DISABLED_OR_COMMENT, INI_ABSOLUTE_AND_RELATIVE, INI_MULTILINE_EVERYWHERE, false, false, false, false, false, false, false, false } [static]¶

A model format for standard INI files.

ini_get_double (const char * ini_string) [extern]¶

Pointer to atof()

double(* const ini_get_float) (const char *ini_string) (const char * ini_string) [extern]¶

Legacy support for parsing a double data type – please do not use this function: use ini_get_double() instead.

Deprecated

Parameters

ini_get_int (const char * ini_string) [extern]¶

Pointer to atoi()

ini_get_lint (const char * ini_string) [extern]¶

Pointer to atol()

ini_get_llint (const char * ini_string) [extern]¶

Pointer to atoll()

size_t INI_GLOBAL_IMPLICIT_V_LEN [extern]¶

Length of the value assigned to implicit keys (default value: 0)

char* INI_GLOBAL_IMPLICIT_VALUE [extern]¶

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

bool INI_GLOBAL_LOWERCASE_MODE [extern]¶

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

Deprecated

const IniFormat INI_UNIXLIKE_FORMAT = { INI_ANY_SPACE, false, INI_DISABLED_OR_COMMENT, INI_DISABLED_OR_COMMENT, INI_ABSOLUTE_AND_RELATIVE, INI_MULTILINE_EVERYWHERE, false, false, false, false, false, false, false, false } [static]¶

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