5.27 libhlp

5.27.1 Overview

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

5.27.2 API

Function: int lw6hlp_is_documented (lw6sys_context_t * sys_context, const char * keyword)

sys_context: global system context

keyword: the keyword we want to check out

Checks wether a given keyword is documented or not.

Return value: 1 if documented, 0 if not.

Function: const char * lw6hlp_about (lw6sys_context_t * sys_context, lw6hlp_type_t * type, const char ** default_value, int * min_value, int * max_value, const char * keyword)

sys_context: global system context

type: the type of the data associated to the keyword, will be written

default_value: the default value for the keyword, will be written

min_value: the min value for the keyword, will be written

max_value: the max value for the keyword, will be written

keyword: the keyword we want help about

Returns the documentation string associated to a keyword. The keyword might be a command-line option, a Guile function, an XML file entry. Raises a warning if the keyword is undocumented, but never returns NULL, you can use the returned value without checking it. String is localized if a translation is available. It’s safe to call this function with type or other parameters being NULL.

Return value: a help string, never NULL, must not be freed. Additionnally, type will be updated.

Function: lw6hlp_type_t lw6hlp_get_type (lw6sys_context_t * sys_context, const char * keyword)

sys_context: global system context

keyword: the keyword we want the type of

Returns the type of a keyword. Calls lw6hlp_about internally.

Return value: the type, might be LW6HLP_TYPE_VOID.

Function: const char * lw6hlp_get_default_value (lw6sys_context_t * sys_context, const char * keyword)

sys_context: global system context

keyword: the keyword we want the default for

Returns the default value for a keyword. Note that it can be NULL! The returned value is always a string, it’s suitable to store in the config file, it’s the value a user would pass on a command line, the one he wants documented.

Return value: a pointer, which can be NULL, must not be freed.

Function: int lw6hlp_get_min_value (lw6sys_context_t * sys_context, const char * keyword)

sys_context: global system context

keyword: the keyword we want the min for

Returns the min value for a keyword. Wether this is relevant for a given keyword does not affect the fact that you can call this function. A min and max of zero means min and max make no sense.

Return value: the value (integer)

Function: int lw6hlp_get_max_value (lw6sys_context_t * sys_context, const char * keyword)

sys_context: global system context

keyword: the keyword we want the max for

Returns the max value for a keyword. Wether this is relevant for a given keyword does not affect the fact that you can call this function. A min and max of zero means min and max make no sense.

Return value: the value (integer)

Function: char * lw6hlp_get_credits (lw6sys_context_t * sys_context, int id)

sys_context: global system context

id: the id of the credits line to return

Returns a "credit line", that is a short sentence, about 30 to 50 chars, saying who developped the game, created graphics, giving important URLs, and so on. One can pass an arbitraty high id, no risk, it will just loop on previous lines.

Return value: the string, must be freed.

Function: int lw6hlp_match (lw6sys_context_t * sys_context, const char * keyword1, const char * keyword2)

sys_context: global system context

keyword1: the 1st keyword

keyword2: the 2nd keyword

Checks wether a keyword matches another. Not only a string comparison, will also try and guess if the error is only about dash "-" replaced by underscode "_", for instance.

Return value: 1 if matches, 0 if different.

Function: lw6sys_list_t * lw6hlp_list_quick (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning quick options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_doc (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning self-documentation system.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_show (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the show options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_path (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the path options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_players (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the players options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_input (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the input options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_graphics (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the graphics options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_sound (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the sound options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_network (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the network options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_map (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the map options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_map_rules (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the rules options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_map_hints (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the hints options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_map_style (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the style options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_map_teams (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning the teams options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_funcs (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of C-function exported to Guile.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_hooks (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of hooks.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_advanced (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of keywords concerning advanced options.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_aliases (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of command-line aliases.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_team_colors (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of team_colors.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list_weapons (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of weapons.

Return value: list of static strings (can’t modify them)

Function: lw6sys_list_t * lw6hlp_list (lw6sys_context_t * sys_context)

sys_context: global system context

Returns the list of all available keywords.

Return value: list of static strings (can’t modify them)

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

sys_context: global system context

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

argv: an array of strings containing command-line args, as passed to main

run_game: a pointer to a boolean which will contain true (1) if the game must be launched, or false (0) if the option is such that game must be skipped. Example: –copyright, –help, ...

Will interpret the command-line arguments, and trap those who are related to docs, this is usefull when building the game, we want to have an extra binary to do this without being linked to SDL, for instance.

Return value: non-zero if success, 0 if error. The error can be, for instance, the test suite returning "no, tests were not OK".

Function: void lw6hlp_print_keyword (lw6sys_context_t * sys_context, lw6sys_list_t ** list, FILE * f)

sys_context: global system context

list: a pointer to a list of keywords

f: the file to print the content to

Prints all the keywords from the list. One keyword per line.

Return value: none.

Function: void lw6hlp_print_content (lw6sys_context_t * sys_context, lw6sys_list_t ** list, FILE * f)

sys_context: global system context

list: a pointer to a list of keywords

f: the file to print the content to

Prints all the keywords from the list, with the associated keyword help, to the given file. Output is formatted to fit on the standard terminal/console.

Return value: none.

Function: void lw6hlp_print_about (lw6sys_context_t * sys_context, const char * keyword, FILE * f)

sys_context: global system context

keyword: the keyword to print help about

f: the file to print the content to

Displays the help about a keyword, to a file, directly. It’s formatted for the purpose of the –about=<value> option.

Return value: none

Function: void lw6hlp_print_help (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays a short help message.

Return value: none

Function: void lw6hlp_print_version (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the version of the game.

Return value: none

Function: void lw6hlp_print_short_copyright (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the copyright of the game (short version).

Return value: none

Function: void lw6hlp_print_long_copyright (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the copyright of the game (long version).

Return value: none

Function: void lw6hlp_print_bench (lw6sys_context_t * sys_context, float bench_result, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the program bench value.

Return value: none

Function: void lw6hlp_print_pedigree (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the program pedigree, think of this as version on steroids.

Return value: none

Function: void lw6hlp_print_host (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the host on which the program was compiled.

Return value: none

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

sys_context: global system context

f: the file to print the content to

Displays various paths used by the game.

Return value: none

Function: void lw6hlp_print_modules (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of modules compiled with the game.

Return value: none

Function: void lw6hlp_print_credits (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays all credits on f, those should be available elsewhere within the game (typically on splash screen) but it’s good to be able to show them "standalone".

Return value: none

Function: void lw6hlp_print_list_quick (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’quick’ options.

Return value: none

Function: void lw6hlp_print_list_doc (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’doc’ options.

Return value: none

Function: void lw6hlp_print_list_show (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’show’ options.

Return value: none

Function: void lw6hlp_print_list_path (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’path’ options.

Return value: none

Function: void lw6hlp_print_list_players (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’players’ options.

Return value: none

Function: void lw6hlp_print_list_input (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’input’ options.

Return value: none

Function: void lw6hlp_print_list_graphics (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’graphics’ options.

Return value: none

Function: void lw6hlp_print_list_sound (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’sound’ options.

Return value: none

Function: void lw6hlp_print_list_network (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’network’ options.

Return value: none

Function: void lw6hlp_print_list_map (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’map’ options.

Return value: none

Function: void lw6hlp_print_list_map_rules (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’map rules’ options.

Return value: none

Function: void lw6hlp_print_list_map_hints (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’map hints’ options.

Return value: none

Function: void lw6hlp_print_list_map_style (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’map style’ options.

Return value: none

Function: void lw6hlp_print_list_map_teams (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’map teams’ options.

Return value: none

Function: void lw6hlp_print_list_funcs (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’funcs’.

Return value: none

Function: void lw6hlp_print_list_hooks (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’hooks’.

Return value: none

Function: void lw6hlp_print_list_advanced (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of ’advanced’ options.

Return value: none

Function: void lw6hlp_print_list_aliases (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of options aliases.

Return value: none

Function: void lw6hlp_print_list_team_colors (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of team colors.

Return value: none

Function: void lw6hlp_print_list_weapons (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of weapons.

Return value: none

Function: void lw6hlp_print_list (lw6sys_context_t * sys_context, FILE * f)

sys_context: global system context

f: the file to print the content to

Displays the list of all known options.

Return value: none

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

sys_context: global system context

argc: number of args as passed to main

argv: array of args as passed to main

Displays ’hello’ at the beginning of the program.

Return value: none

Function: void lw6hlp_print_goodbye (lw6sys_context_t * sys_context)

sys_context: global system context

Displays ’goodbye’, typically use at end of program to know it’s over and everything went fine.

Return value: none

Function: int lw6hlp_reference_init (lw6sys_context_t * sys_context)

sys_context: global system context

Initializes the help reference, this must be called before any call to lw6hlp_about or such help related functions.

Return value: 1 on success, 0 if failed

Function: void lw6hlp_reference_quit (lw6sys_context_t * sys_context)

sys_context: global system context

un-initializes the help reference, this must be called at the end of the program.

Return value: 1 on success, 0 if failed

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

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libhlp module.

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

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

sys_context: global system context

mode: test mode (bitmask)

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

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