5.7 libcfg

5.7.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/cfg/index.html.

5.7.2 API

Function: int lw6cfg_parse_command_line (lw6sys_context_t * sys_context, void * cfg_context)

sys_context: global system context

cfg_context: opaque pointer on a context

Overwrites any existing option with command line args

Return value: 1 if success, 0 if error

Function: int lw6cfg_defaults (lw6sys_context_t * sys_context, void * cfg_context)

sys_context: global system context

cfg_context: opaque pointer on a context

Sets all values to their defaults.

Return value: 1 if success, 0 if error

Function: int lw6cfg_merge_env (lw6sys_context_t * sys_context, void * cfg_context)

sys_context: global system context

cfg_context: a context returned by lw6cfg_init

Overwrites any existing vale in the config with environment variables prefixed by LW6_.

Return value: 1 if successfull, 0 if error.

Function: int lw6cfg_load_exp (lw6sys_context_t * sys_context, const char * user_dir, int * exp)

sys_context: global system context

user_dir: the user directory

exp: the exp (out param)

Gets exp from file.

Return value: 1 on success, 0 on failure

Function: int lw6cfg_save_exp (lw6sys_context_t * sys_context, const char * user_dir, int exp)

sys_context: global system context

user_dir: the user directory

exp: the exp

Saves exp to file.

Return value: 1 on success, 0 on failure

Function: char * lw6cfg_format (lw6sys_context_t * sys_context, const char * key, const char * value, lw6hlp_type_t type)

sys_context: global system context

key: the key of the value to format

value: the value to format

type: the type of the value to format

Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct.

Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.

Function: char * lw6cfg_format_guess_type (lw6sys_context_t * sys_context, const char * key, const char * value)

sys_context: global system context

key: the key of the value to format

value: the value to format

Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct. This function will automatically guess the type of the value from its description in the help system.

Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.

Function: int lw6cfg_load (lw6sys_context_t * sys_context, void * cfg_context, const char * filename)

sys_context: global system context

cfg_context: a context returned by lw6cfg_init

filename: a file path, absolute or relative

Loads the given config file, and stores its values into the current context. Parameters which are both in the config file and given as command line parameters, will be taken from the command-line.

Return value: 1 if successfull, 0 if error.

Function: int lw6cfg_option_exists (lw6sys_context_t * sys_context, void * cfg_context, const char * key)

sys_context: global system context

cfg_context: context to query

key: key to search

Returns wether a key exists within context or not.

Return value: 1 if exists, 0 if not

Function: char * lw6cfg_get_option (lw6sys_context_t * sys_context, void * cfg_context, const char * key)

sys_context: global system context

cfg_context: context to query

key: key to search

Returns the current value for a given query, the returned value is always a string, typically the string one would pass on the command line or set in a config file

Return value: pointer to string, must be freed.

Function: void lw6cfg_set_option (lw6sys_context_t * sys_context, void * cfg_context, const char * key, const char * value)

sys_context: global system context

cfg_context: context to modify

key: key to search and change

value: new value

Sets a given key to the specified value, this is a string only function, pass the value you would pass on the command line or set in a config file.

Return value: none

Function: int lw6cfg_get_option_int (lw6sys_context_t * sys_context, void * cfg_context, const char * key)

key: key to search

Returns an option as an integer. Note that this function does not know wether the parameter should really be an integer or not, so you can call it even on non-integer values, but of course results will have no real meaning.

Return value: option value converted to int

Function: void lw6cfg_set_option_int (lw6sys_context_t * sys_context, void * cfg_context, const char * key, int value)

sys_context: global system context

cfg_context: context to modify

key: key to search and change

value: new value

Set a config option to an integer value. Note that this function does not know wether the parameter should really be an integer or not, so you can call it even on non-integer values, at your own risk.

Return value: none.

Function: int lw6cfg_get_option_bool (lw6sys_context_t * sys_context, void * cfg_context, const char * key)

sys_context: global system context

cfg_context: context to query

key: key to search

Returns an option as a boolean. Note that this function does not know wether the parameter should really be a boolean or not, so you can call it even on non-boolean values, but of course results will have no real meaning.

Return value: option value converted to boolean

Function: void lw6cfg_set_option_bool (lw6sys_context_t * sys_context, void * cfg_context, const char * key, int value)

sys_context: global system context

cfg_context: context to modify

key: key to search and change

value: new value

Set a config option to a boolean value. Note that this function does not know wether the parameter should really be a boolean or not, so you can call it even on non-boolean values, at your own risk.

Return value: none.

Function: int lw6cfg_must_be_saved (lw6sys_context_t * sys_context, const char * key)

sys_context: global system context

key: key to test

Tells wether a key should be saved in the config file. Typically, some options you don’t want to savem such as the location of the config file itself. Most of those non-savable parameters are path-related. This does not mean no paths are saved in the config file.

Return value: 1 if must be saved, 0 if not

Function: int lw6cfg_save (lw6sys_context_t * sys_context, void * cfg_context, const char * filename)

sys_context: global system context

cfg_context: a context returned by lw6cfg_init

filename: a file path, absolute or relative

Save current options into the given config file. Before saving the file, all command line arguments will be read and will override current values. This means the saved file will contain values given as command line arguments.

Return value: 1 if successfull, 0 if error.

Function: void * lw6cfg_init (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command line arguments, as given to main

argv: a list of command line arguments, as given to main

Initializes a config context object. This object is hidden behind an opaque void * pointer to avoid direct access to its elements.

Return value: an opaque pointer, must be freed with lw6cfg_quit.

Function: void lw6cfg_quit (lw6sys_context_t * sys_context, void * cfg_context)

sys_context: global system context

cfg_context: a context returned by lw6cfg_init

Frees a config cfg_context object. You must call this once you’re done with the context.

Return value: none.

Function: void lw6cfg_reset (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command line arguments, as given to main

argv: a list of command line arguments, as given to main

Overwrites the config file with defaults. Use this to get rid of old configurations.

Function: int lw6cfg_test_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libcfg module.

Return value: 1 if test is successfull, 0 on error.

Function: int lw6cfg_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Runs the cfg module test suite, testing most (if not all...) functions.

Return value: 1 if test is successfull, 0 on error.

Function: char * lw6cfg_unified_get_value (lw6sys_context_t * sys_context, int argc, const char * [] argv, char * key)

sys_context: global system context

argc: number of command-line args, as passed to main

argv: arry of command-line args, as passed to main

key: the key to query

Unified "value" getter, which gets informations from environment variables, command line, and config file. The rules is that the command-line argument always has the last word. It will override any other value. Follows environment variables, which will be used if no command-line argument is supplied. Note that these are "LW6_" prefixed and uppercased environment variables as opposed to lowercased and "dash-separated" keys. Finally, if there’s no environment variable, nor any config-file corresponding entry, the value will be searched in the config file. If there’s no information in the config file, NULL is returned.

Return value: a string with the value. Can be NULL. Must be freed.

Function: char * lw6cfg_unified_get_user_dir (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command-line args, as passed to main

argv: arry of command-line args, as passed to main

Gets the user dir, taking all parameters in account, that’s to say the "LW6_USER_DIR" env value, the "–user-dir" command-line paramater and the LW6DEF_USER_DIR config file entry.

Return value: the directory path, might be NULL, must be freed.

Function: char * lw6cfg_unified_get_log_file (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command-line args, as passed to main

argv: arry of command-line args, as passed to main

Gets the log file, taking all parameters in account, that’s to say the "LW6_LOG_FILE" env value, the "–log-file" command-line paramater and the LW6DEF_LOG_FILE config file entry.

Return value: the directory path, might be NULL, must be freed.

Function: char * lw6cfg_unified_get_music_path (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command-line args, as passed to main

argv: arry of command-line args, as passed to main

Gets the user dir, taking all parameters in account, that’s to say the "LW6_MUSIC_PATH" env value, the "–music-path" command-line paramater and the LW6DEF_MUSIC_PATH config file entry.

Return value: the directory path, might be NULL, must be freed.

Function: char * lw6cfg_unified_get_map_path (lw6sys_context_t * sys_context, int argc, const char * [] argv)

sys_context: global system context

argc: number of command-line args, as passed to main

argv: arry of command-line args, as passed to main

Gets the user dir, taking all parameters in account, that’s to say the "LW6_MAP_PATH" env value, the "–map-path" command-line paramater and the LW6DEF_MAP_PATH config file entry.

Return value: the directory path, might be NULL, must be freed.

Function: char * lw6cfg_xml_element (lw6sys_context_t * sys_context, lw6hlp_type_t type)

sys_context: global system context

type: type as an enum

Returns the string corresponding to a given type, suitable for use in XML files. For instance if you pass LW6HLP_TYPE_INT then you will obtain the string int (string of 3 chars containing i, n and t.

Return value: string, must not be freed.

Function: void lw6cfg_read_xml_int (lw6sys_context_t * sys_context, const char * xml_key, const char * xml_value, const char * target_key, int * value)

sys_context: global system context

xml_key: key found in XML file

xml_value: value found in XML file

target_key: key we’re searching for

value: the value if found (out param)

Tries to find a value in a key/value pair. If xml_key and target_key match, then will put the corresponding value (converted to int) in the value param. Typically, you would call this in a loop on every single entry found in an XML file, in an expat callback.

Return value: none.

Function: void lw6cfg_read_xml_bool (lw6sys_context_t * sys_context, const char * xml_key, const char * xml_value, const char * target_key, int * value)

sys_context: global system context

xml_key: key found in XML file

xml_value: value found in XML file

target_key: key we’re searching for

value: the value if found (out param)

Tries to find a value in a key/value pair. If xml_key and target_key match, then will put the corresponding value (converted to boolean) in the value param. Typically, you would call this in a loop on every single entry found in an XML file, in an expat callback.

Return value: none.

Function: void lw6cfg_read_xml_float (lw6sys_context_t * sys_context, const char * xml_key, const char * xml_value, const char * target_key, float * value)

sys_context: global system context

xml_key: key found in XML file

xml_value: value found in XML file

target_key: key we’re searching for

value: the value if found (out param)

Tries to find a value in a key/value pair. If xml_key and target_key match, then will put the corresponding value (converted to float) in the value param. Typically, you would call this in a loop on every single entry found in an XML file, in an expat callback.

Return value: none.

Function: void lw6cfg_read_xml_string (lw6sys_context_t * sys_context, const char * xml_key, const char * xml_value, const char * target_key, char ** value)

sys_context: global system context

xml_key: key found in XML file

xml_value: value found in XML file

target_key: key we’re searching for

value: the value if found (out param)

Tries to find a value in a key/value pair. If xml_key and target_key match, then will put the corresponding value (as a string) in the value param. Typically, you would call this in a loop on every single entry found in an XML file, in an expat callback.

Return value: none.

Function: void lw6cfg_read_xml_color (lw6sys_context_t * sys_context, const char * xml_key, const char * xml_value, const char * target_key, lw6sys_color_8_t * value)

sys_context: global system context

xml_key: key found in XML file

xml_value: value found in XML file

target_key: key we’re searching for

value: the value if found (out param)

Tries to find a value in a key/value pair. If xml_key and target_key match, then will put the corresponding value (converted to a color) in the value param. Typically, you would call this in a loop on every single entry found in an XML file, in an expat callback.

Return value: none.

Function: int lw6cfg_read_key_value_xml_file (lw6sys_context_t * sys_context, const char * filename, lw6cfg_read_xml_callback_func_t callback_func, void * callback_data)

sys_context: global system context

filename: full path of file to read

callback_func: callback function to be called on each element

callback_data: additionnal pointer passed to callback function

Will parse a file and call the given callback on each element. This is an over-simplified way to read XML file, in fact we just explain plain non-nested simple elements but this is exactly what LW config files are made of.

Return value: 1 on success, 0 on failure.

Function: void lw6cfg_write_xml_int (lw6sys_context_t * sys_context, FILE * f, const char * key, int value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes an int entry into an opened XML file.

Return value: none.

Function: void lw6cfg_write_xml_bool (lw6sys_context_t * sys_context, FILE * f, const char * key, int value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes a boolean entry into an opened XML file.

Return value: none.

Function: void lw6cfg_write_xml_float (lw6sys_context_t * sys_context, FILE * f, const char * key, float value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes a float entry into an opened XML file.

Return value: none.

Function: void lw6cfg_write_xml_string (lw6sys_context_t * sys_context, FILE * f, const char * key, const char * value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes a string entry into an opened XML file.

Return value: none.

Function: void lw6cfg_write_xml_color (lw6sys_context_t * sys_context, FILE * f, const char * key, lw6sys_color_8_t value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes a color entry into an opened XML file.

Return value: none.

Function: void lw6cfg_write_xml_guess_type (lw6sys_context_t * sys_context, FILE * f, const char * key, const char * value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes an entry into an opened XML file, will try and guess type from the internal help system, typically, if this is a standard config file entry (the one documented by the about command line function) it will pick up the right type. The reason not to use this all the times is that sometimes, one might to to store non-standard options, and additionnally, guessing the type does consume some CPU.

Return value: none.

Function: void lw6cfg_write_xml_guess_type_skip_same (lw6sys_context_t * sys_context, FILE * f, const char * key, const char * value)

sys_context: global system context

f: file to write data to (append mode)

key: key to write

value: value to write

Writes an entry into an opened XML file, will try and guess type from the internal help system, typically, if this is a standard config file entry (the one documented by the about command line function) it will pick up the right type. The reason not to use this all the times is that sometimes, one might to to store non-standard options, and additionnally, guessing the type does consume some CPU. Also, this function will write only values that are different from the default.

Return value: none.