Next: , Previous: mod-random, Up: C API


5.5 libcfg

5.5.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/coverage/src/lib/cfg/index.html.

5.5.2 API

— Function: int lw6cfg_parse_command_line (void * context)

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

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 (void * cfg_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: char * lw6cfg_format (char * key, char * value, lw6hlp_type_t type)

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 (char * key, char * value)

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 (void * cfg_context, char * filename)

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_save (void * cfg_context, char * filename)

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 (int argc, char * [] argv)

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 (void * cfg_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 (int argc, char * [] argv)

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 (int mode)

mode: 0 for check only, 1 for full test

Runs the cfg module test suite.

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

— Function: char * lw6cfg_unified_get_value (int argc, char * [] argv, char * key)

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 (int argc, char * [] argv)

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 (int argc, char * [] argv)

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 (int argc, char * [] argv)

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 (int argc, char * [] argv)

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.