plibsys
Typedefs | Functions
pinifile.h File Reference

INI file parser. More...

#include <pmacros.h>
#include <ptypes.h>
#include <plist.h>
#include <perror.h>
Include dependency graph for pinifile.h:

Go to the source code of this file.

Typedefs

typedef typedefP_BEGIN_DECLS struct PIniFile_ PIniFile
 INI file opaque data structure. More...
 

Functions

P_LIB_API PIniFilep_ini_file_new (const pchar *path)
 Creates a new PIniFile for parsing. More...
 
P_LIB_API void p_ini_file_free (PIniFile *file)
 Frees memory and allocated resources of PIniFile. More...
 
P_LIB_API pboolean p_ini_file_parse (PIniFile *file, PError **error)
 Parses given PIniFile. More...
 
P_LIB_API pboolean p_ini_file_is_parsed (const PIniFile *file)
 Checks whether PIniFile was already parsed or not. More...
 
P_LIB_API PListp_ini_file_sections (const PIniFile *file)
 Gets all the sections from a given file. More...
 
P_LIB_API PListp_ini_file_keys (const PIniFile *file, const pchar *section)
 Gets all the keys from a given section. More...
 
P_LIB_API pboolean p_ini_file_is_key_exists (const PIniFile *file, const pchar *section, const pchar *key)
 Checks whether a key exists. More...
 
P_LIB_API pcharp_ini_file_parameter_string (const PIniFile *file, const pchar *section, const pchar *key, const pchar *default_val)
 Gets specified parameter's value as a string. More...
 
P_LIB_API pint p_ini_file_parameter_int (const PIniFile *file, const pchar *section, const pchar *key, pint default_val)
 Gets specified parameter's value as an integer. More...
 
P_LIB_API double p_ini_file_parameter_double (const PIniFile *file, const pchar *section, const pchar *key, double default_val)
 Gets specified parameter's value as a floating point. More...
 
P_LIB_API pboolean p_ini_file_parameter_boolean (const PIniFile *file, const pchar *section, const pchar *key, pboolean default_val)
 Gets specified parameter's value as a boolean. More...
 
P_LIB_API PListp_ini_file_parameter_list (const PIniFile *file, const pchar *section, const pchar *key)
 Gets specified parameter's value as a list of strings separated with the spaces or tabs. More...
 

Detailed Description

INI file parser.

Author
Alexander Saprykin

An INI file is usually used for storing configuration information. It consists of sections: every section starts with a line containing the name in square brackets (i.e. [section_name]). After that line all the following parameters will belong to that section until another section begins.

Each section has a list of key-value pairs. Empty sections are not permitted (they will be skipped). Every key-value pair is represented with a line in the key = value format. If a section has several values with the same key the last one will be used. A value is parsed by the first in-order '=' symbol. All the following '=' occurrences belong to the value.

All symbols after '#' and ';' (even at the line ending) are the comments and wouldn't be read. If you want to use them in values take the value inside the "" or '' symbols. A section name line is not allowed to use the comment symbols after the section name in the square brackets itself.

Integer values can be written in the usual form.

Floating point values can be written in any commonly used notation (i.e. with the decimal point, in the exponential form using the 'e' character). The only valid decimal point symbol is the '.'. There is no locale dependency on the decimal point.

Boolean values can be written in the form of 'true/false' or 'TRUE/FALSE', or simply '0/1'.

Any value can be interpreted as a string at any moment. Actually all the values are stored internally as strings.

A list of values can be stored between the '{}' symbols separated with spaces. The list only supports string values, so you should convert them to numbers manually. The list doesn't support strings with spaces - such strings will be splitted.

To parse a file, create PIniFile with p_ini_file_new() and then parse it with the p_ini_file_parse() routine.

PIniFile handles (skips) UTF-8/16/32 BOM characters (marks).

Example of the INI file contents:

[numeric_section]
numeric_value_1 = 1234 # One type of the comment
numeric_value_2 = 123 ; Comment is allowed here
[floating_section]
float_value_1 = 123.3e10
float_value_2 = 123.19
[boolean_section]
boolean_value_1 = TRUE
boolean_value_2 = 0
boolean_value_3 = false
[string_section]
string_value_1 = "Test string"
string_value_2 = 'Another test string'
[list_section]
list_value = {123 val 7654}

Typedef Documentation

◆ PIniFile

typedef typedefP_BEGIN_DECLS struct PIniFile_ PIniFile

INI file opaque data structure.

Function Documentation

◆ p_ini_file_free()

P_LIB_API void p_ini_file_free ( PIniFile file)

Frees memory and allocated resources of PIniFile.

Parameters
filePIniFile to free.
Since
0.0.1

◆ p_ini_file_is_key_exists()

P_LIB_API pboolean p_ini_file_is_key_exists ( const PIniFile file,
const pchar section,
const pchar key 
)

Checks whether a key exists.

Parameters
filePIniFile to check in. The file should be parsed before.
sectionSection to check the key in.
keyKey to check.
Returns
TRUE if key exists, FALSE otherwise.
Since
0.0.1

◆ p_ini_file_is_parsed()

P_LIB_API pboolean p_ini_file_is_parsed ( const PIniFile file)

Checks whether PIniFile was already parsed or not.

Parameters
filePIniFile to check.
Returns
TRUE if the file was already parsed, FALSE otherwise.
Since
0.0.1

◆ p_ini_file_keys()

P_LIB_API PList* p_ini_file_keys ( const PIniFile file,
const pchar section 
)

Gets all the keys from a given section.

Parameters
filePIniFile to get the keys from. The file should be parsed before.
sectionSection name to get the keys from.
Returns
PList of key names.
Since
0.0.1
Note
It's a caller responsibility to p_free() each returned string and to free the returned list with p_list_free().

◆ p_ini_file_new()

P_LIB_API PIniFile* p_ini_file_new ( const pchar path)

Creates a new PIniFile for parsing.

Parameters
pathPath to a file to parse.
Returns
Newly allocated PIniFile in case of success, NULL otherwise.
Since
0.0.1

◆ p_ini_file_parameter_boolean()

P_LIB_API pboolean p_ini_file_parameter_boolean ( const PIniFile file,
const pchar section,
const pchar key,
pboolean  default_val 
)

Gets specified parameter's value as a boolean.

Parameters
filePIniFile to get the value from. The file should be parsed before.
sectionSection to get the value from.
keyKey to get the value from.
default_valDefault value to return if no specified key exists.
Returns
Key's value in case of success, default_value otherwise.
Since
0.0.1

◆ p_ini_file_parameter_double()

P_LIB_API double p_ini_file_parameter_double ( const PIniFile file,
const pchar section,
const pchar key,
double  default_val 
)

Gets specified parameter's value as a floating point.

Parameters
filePIniFile to get the value from. The file should be parsed before.
sectionSection to get the value from.
keyKey to get the value from.
default_valDefault value to return if no specified key exists.
Returns
Key's value in case of success, default_value otherwise.
Since
0.0.1

◆ p_ini_file_parameter_int()

P_LIB_API pint p_ini_file_parameter_int ( const PIniFile file,
const pchar section,
const pchar key,
pint  default_val 
)

Gets specified parameter's value as an integer.

Parameters
filePIniFile to get the value from. The file should be parsed before.
sectionSection to get the value from.
keyKey to get the value from.
default_valDefault value to return if no specified key exists.
Returns
Key's value in case of success, default_value otherwise.
Since
0.0.1

◆ p_ini_file_parameter_list()

P_LIB_API PList* p_ini_file_parameter_list ( const PIniFile file,
const pchar section,
const pchar key 
)

Gets specified parameter's value as a list of strings separated with the spaces or tabs.

Parameters
filePIniFile to get the value from. The file should be parsed before.
sectionSection to get the value from.
keyKey to get the value from.
Returns
PList of strings. NULL will be returned if no parameter with the given name exists.
Since
0.0.1
Note
It's a caller responsibility to p_free() each returned string and to free the returned list with p_list_free().

◆ p_ini_file_parameter_string()

P_LIB_API pchar* p_ini_file_parameter_string ( const PIniFile file,
const pchar section,
const pchar key,
const pchar default_val 
)

Gets specified parameter's value as a string.

Parameters
filePIniFile to get the value from. The file should be parsed before.
sectionSection to get the value from.
keyKey to get the value from.
default_valDefault value to return if no specified key exists.
Returns
Key's value in case of success, default_value otherwise.
Since
0.0.1
Note
It's a caller responsibility to p_free() the returned string after usage.

◆ p_ini_file_parse()

P_LIB_API pboolean p_ini_file_parse ( PIniFile file,
PError **  error 
)

Parses given PIniFile.

Parameters
filePIniFile file to parse.
[out]errorError report object, NULL to ignore.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1

◆ p_ini_file_sections()

P_LIB_API PList* p_ini_file_sections ( const PIniFile file)

Gets all the sections from a given file.

Parameters
filePIniFile to get the sections from. The file should be parsed before.
Returns
PList of section names.
Since
0.0.1
Note
It's a caller responsibility to p_free() each returned string and to free the returned list with p_list_free().