The Configuration File Library
0.2.0
|
Source for Configuration File Library (CEL) More...
#include <stddef.h>
#include <stdio.h>
#include <ctype.h>
#include <string.h>
#include <stdlib.h>
#include <errno.h>
#include "cbl/assert.h"
#include "cbl/memory.h"
#include "cdsl/hash.h"
#include "cdsl/table.h"
#include "conf.h"
Functions | |
int() | conf_preset (const conf_t *tab, int ctrl) |
constructs a default set for configuration variables. | |
size_t() | conf_init (FILE *fp, int ctrl) |
reads a configuration file and constructs the configuration data. | |
const void * | conf_conv (const char *val, int type) |
converts a string based on a type. | |
const void *() | conf_get (const char *var) |
retrieves a value with a section/variable name. | |
int() | conf_getbool (const char *var, int errval) |
retrieves a boolean value with a section/variable name. | |
long() | conf_getint (const char *var, long errval) |
retrieves an integral value with a section/variable name. | |
unsigned long() | conf_getuint (const char *var, unsigned long errval) |
retrieves an unsigned integral value with a section/variable name. | |
double() | conf_getreal (const char *var, double errval) |
retrieves a real value with a section/variable name. | |
const char *() | conf_getstr (const char *var) |
retrieves a string with a section/variable name. | |
int() | conf_set (const char *secvar, const char *value) |
inserts or replaces a value associated with a variable. | |
int() | conf_section (const char *sec) |
sets the current section. | |
void() | conf_free (void) |
deallocates the stroage for the configuration data. | |
void() | conf_hashreset (void) |
resets the hash table using hash_reset(). | |
int() | conf_errcode (void) |
returns an error code. | |
const char *() | conf_errstr (int code) |
returns an error message. |
Source for Configuration File Library (CEL)
const void* conf_conv | ( | const char * | val, |
int | type | ||
) |
converts a string based on a type.
conf_conv() converts a string to an integer or floating-point number as requested. type
should be CONF_TYPE_BOOL
(which recognizes some forms of boolean values), CONF_TYPE_INT
(which indicates conversion to signed long int), CONT_TYPE_UINT
(conversion to unsigned long int), CONF_TYPE_REAL
(conversion to double) or CONF_TYPE_STR
(no conversion necessary). The expected forms for CONF_TYPE_INT
, CONF_TYPE_UINT
and CONF_TYPE_REAL
are respectively those for strtol(), strtoul() and strtod(). CONF_TYPE_BOOL
gives 1 for a string starting with 't', 'T', 'y', 'Y', '1' and 0 for others. conf_conv() returns a pointer to the storage that contains the converted value (an integer, floating-point number or string) and its caller (user code) has to convert the pointer properly (to const int *, const long *, const unsigned long *, const double * and const char *) before use. If the conversion fails, conf_conv() returns a null pointer and sets CONF_ERR_TYPE
as an error code.
CONF_TYPE_STR
.[in] | val | string to convert |
[in] | type | type based on which conversion performed |
non-null | pointer to conversion result |
NULL | conversion failure |
int() conf_errcode | ( | void | ) |
returns an error code.
Every function in this library sets the internal error variable as it performs its operation. Unlike errno provided by <errno.h>, the error variable of this library is set to CONF_ERR_OK
before starting an operation, thus a user code need not to clear it before calling a conf_ function.
When using a function returning an error code (of the int type), the returned value is the same as what conf_errcode() will return if there is no intervening call to a conf_ function between them. When using a function returning a pointer, the only way to get what the error has been occurred is to use conf_errcode().
The following code fragment shows an example for how to use conf_errcode() and conf_errstr():
fp = fopen(conf, "r"); if (!fp) fprintf(stderr, "%s:%s: %s\n", prg, conf, conf_errstr(CONF_ERR_FILE)); line = conf_init(fp, CONF_OPT_CASE | CONF_OPT_ESC); if (line != 0) fprintf(stderr, "%s:%s:%lu: %s\n", prg, conf, line, conf_errstr(conf_errcode()));
Possible exceptions: none
Unchecked errors: none
const char*() conf_errstr | ( | int | code | ) |
returns an error message.
conf_errstr() returns an error message for a given error code.
Possible exceptions: assert_exceptfail
Unchecked errors: none
[in] | code | error code for which error message returned |
void() conf_free | ( | void | ) |
deallocates the stroage for the configuration data.
conf_free() deallocates storages for the configuration data. After conf_free() invoked, other conf_ functions should not be called without an intervening call to conf_preset() or conf_init().
Possible exceptions: assert_exceptfail
Unchecked errors: none
const void*() conf_get | ( | const char * | var | ) |
retrieves a value with a section/variable name.
conf_get() retrieves a value with a section/variable name.
In a program (e.g., when using conf_get()), variables can be referred to using one of the following forms:
variable . variable section . variable
where whitespaces are optional before and after section and variable names. The first form refers to a variable belonging to the "current" section; the current section can be set by invoking conf_section(). The second form refers to a variable belonging to the global section. The last form refers to a variable belonging to a specific section.
CONF_TYPE_STR
. Similarly, a subsequent call to conf_getbool(), conf_getint(), conf_getuint() and conf_getreal() may overwrite the contents of the buffer pointed by the resulting pointer.Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
non-null | value retrieved |
NULL | failure |
int() conf_getbool | ( | const char * | var, |
int | errval | ||
) |
retrieves a boolean value with a section/variable name.
conf_getbool() retrieves a boolean value with a section/variable name. Every value for a variable is stored in a string form, and conf_getbool() converts it to a boolean value; the result is 1 (indicating true) if the string starts with 't', 'T', 'y', 'Y' or '1' ignoring any leading spaces and 0 (indicating false) otherwise. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_BOOL
, the value of errval
is returned.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
[in] | errval | value returned as error |
errval
long() conf_getint | ( | const char * | var, |
long | errval | ||
) |
retrieves an integral value with a section/variable name.
conf_getint() retrieves an integral value with a section/variable name. Every value for a variable is stored in a string form, and conf_getint() converts it to an integer using strtol() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_INT
, the value of errval
is returned.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
[in] | errval | value returned as error |
errval
double() conf_getreal | ( | const char * | var, |
double | errval | ||
) |
retrieves a real value with a section/variable name.
conf_getreal() retrieves a real value with a section/variable name. Every value for a variable is stored in a string form, and conf_getreal() converts it to a floating-point number using strtod() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_REAL
, the value of errval
is returned; HUGE_VAL
defined <math.h> would be a nice choice for errval
.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
[in] | errval | value returned as error |
errval
const char*() conf_getstr | ( | const char * | var | ) |
retrieves a string with a section/variable name.
conf_getstr() retrieves a string with a section/variable name. Every value for a variable is stored in a string form, thus conf_getstr() performs no conversion. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_STR
, a null pointer is returned.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
non-null | string retrieved |
NULL | failure |
unsigned long() conf_getuint | ( | const char * | var, |
unsigned long | errval | ||
) |
retrieves an unsigned integral value with a section/variable name.
conf_getuint() retrieves an unsigned integral value with a section/variable name. Every value for a variable is stored in a string form, and conf_getuint() converts it to an unsigned integer using strtoul() declared in <stdlib.h>. If there is no variable with the given name or the preset type of the variable is not CONF_TYPE_UINT
, the value of errval
is returned.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | var | section/variable name |
[in] | errval | value returned as error |
errval
void() conf_hashreset | ( | void | ) |
resets the hash table using hash_reset().
conf_hashreset() simply calls hash_reset() to reset the hash table. As explained in conf_free(), conf_free() does not invoke hash_reset() because the single hash table may be used by other parts of a user program. Since requiring a reference to hash_reset() when using the Configuration File Library is inconsistent and inconvenient (e.g., a user code is obliged to include "hash.h"), conf_hashreset() is provided as a wrapper for hash_reset().
Possible exceptions: none
Unchecked errors: none
size_t() conf_init | ( | FILE * | fp, |
int | ctrl | ||
) |
reads a configuration file and constructs the configuration data.
conf_init() reads a configuration file and constructs the configuration data by analyzing the file. For how conf_init() interacts with conf_preset(), see conf_preset().
The default behavior of the library is that names are not case-insensitive and that escape sequences are not recognized. This behavior can be changed by setting the CONF_OPT_CASE
and CONF_OPT_ESC
bits in ctrl
, respectively; see also conf_preset().
If the control mode that can be set through ctrl
has been already set by conf_preset(), conf_init() ignores ctrl
.
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: invalid file pointer given for fp
[in] | fp | file pointer from which configuration data read |
[in] | ctrl | control code |
0 | success |
positive | line number on which error occurred |
int() conf_preset | ( | const conf_t * | tab, |
int | ctrl | ||
) |
constructs a default set for configuration variables.
A user program can specify the default set of configuration variables (including sections to which they belong and their types) with conf_preset(). The table (an array, in fact) containing necessary information have the conf_t
type and called a "configuration description table." For a detailed explanation and examples, see conf_t
. conf_preset(), if invoked, has to be called before conf_init(). conf_init() is not necessarily invoked if conf_preset() is used.
If invoked, conf_preset() remembers names that need to be recognized as sections and variables, types of variables, and their default values. When conf_init() processes a configuration file, a sections or variable that is not given via conf_preset() is considered an error. Using conf_preset() and a configuration description table is the only way to let variables have other types than CONF_TYPE_STR
(string type).
If not invoked, conf_init() accepts any section and variable name (if they have a valid form) and all of variables are assumed to be of CONF_TYPE_STR
type.
conf_preset() also takes ctrl
for controling some behaviors of the library, especially handling section/variable names and values. If the CONF_OPT_CASE
bit is set in ctrl
(that is, CONF_OPT_CASE
& ctrl
is not 0), section and variable names are case-sensitive. If the CONF_OPT_ESC
bit is set in ctrl
, some forms of escape sequences are supported in a quoted value. The default behavior is that section and variable names are case-insensitive and no escape sequences are supported.
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | tab | configuration description table |
[in] | ctrl | control code |
CONF_ERR_OK | success |
others | failure |
int() conf_section | ( | const char * | sec | ) |
sets the current section.
conf_section() sets the current section to a given section. The global section can be set as the current section by giving an empty string "" to conf_section(). conf_section() affects how conf_get(), conf_getbool(), conf_getint(), confgetuint(), confgetreal(), confgetstr() and conf_set() work.
[in] | sec | section name to set as current section |
CONF_ERR_OK | success |
others | failure |
int() conf_set | ( | const char * | secvar, |
const char * | value | ||
) |
inserts or replaces a value associated with a variable.
conf_set() inserts or replaces a value associated with a variable. If conf_preset() has been invoked, conf_set() is able to only replace a value associated with an existing variable, which means an error code is returned when a user tries to insert a new variable and its value (possibly with a new section). conf_set() is allowed to insert a new variable-value pair otherwise.
For how to refer to variables in a program, see conf_get().
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: none
[in] | secvar | section/variable name |
[in] | value | value to store |
CONF_ERR_OK | success |
others | failure |