libhlp - Liquid War 6
Description: Liquid War 6

Next: libimg, Previous: libgui, Up: C API

### 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 (const char * keyword)

> 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 (lw6hlp_type_t * type, const char ** default_value, int * min_value, int * max_value, const char * keyword)

> 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 (const char * keyword)

> 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 (const char * keyword)

> 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 (const char * keyword)

> 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 (const char * keyword)

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

> 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 (const char * keyword1, const char * keyword2)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

> Returns the list of hooks.

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

— Function: lw6sys_list_t * lw6hlp_list_advanced ()

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

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

> Returns the list of team_colors.

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

— Function: lw6sys_list_t * lw6hlp_list_weapons ()

> Returns the list of weapons.

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

— Function: lw6sys_list_t * lw6hlp_list ()

> Returns the list of all available keywords.

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

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

> 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_list_t ** list, FILE * f)

> 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_list_t ** list, FILE * f)

> 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 (const char * keyword, FILE * f)

> 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 (FILE * f)

> f: the file to print the content to

> Displays a short help message.

> Return value: none

— Function: void lw6hlp_print_version (FILE * f)

> f: the file to print the content to

> Displays the version of the game.

> Return value: none

— Function: void lw6hlp_print_short_copyright (FILE * f)

> 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 (FILE * f)

> f: the file to print the content to

> Displays the copyright of the game (long version).

> Return value: none

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

> f: the file to print the content to

> Displays the program bench value.

> Return value: none

— Function: void lw6hlp_print_pedigree (FILE * f)

> 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 (FILE * f)

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

> f: the file to print the content to

> Displays various paths used by the game.

> Return value: none

— Function: void lw6hlp_print_modules (FILE * f)

> 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 (FILE * f)

> 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 (FILE * f)

> f: the file to print the content to

> Displays the list of 'quick' options.

> Return value: none

— Function: void lw6hlp_print_list_doc (FILE * f)

> f: the file to print the content to

> Displays the list of 'doc' options.

> Return value: none

— Function: void lw6hlp_print_list_show (FILE * f)

> f: the file to print the content to

> Displays the list of 'show' options.

> Return value: none

— Function: void lw6hlp_print_list_path (FILE * f)

> f: the file to print the content to

> Displays the list of 'path' options.

> Return value: none

— Function: void lw6hlp_print_list_players (FILE * f)

> f: the file to print the content to

> Displays the list of 'players' options.

> Return value: none

— Function: void lw6hlp_print_list_input (FILE * f)

> f: the file to print the content to

> Displays the list of 'input' options.

> Return value: none

— Function: void lw6hlp_print_list_graphics (FILE * f)

> f: the file to print the content to

> Displays the list of 'graphics' options.

> Return value: none

— Function: void lw6hlp_print_list_sound (FILE * f)

> f: the file to print the content to

> Displays the list of 'sound' options.

> Return value: none

— Function: void lw6hlp_print_list_network (FILE * f)

> f: the file to print the content to

> Displays the list of 'network' options.

> Return value: none

— Function: void lw6hlp_print_list_map (FILE * f)

> f: the file to print the content to

> Displays the list of 'map' options.

> Return value: none

— Function: void lw6hlp_print_list_map_rules (FILE * f)

> 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 (FILE * f)

> 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 (FILE * f)

> 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 (FILE * f)

> f: the file to print the content to

> Displays the list of 'map teams' options.

> Return value: none

— Function: void lw6hlp_print_list_funcs (FILE * f)

> f: the file to print the content to

> Displays the list of 'funcs'.

> Return value: none

— Function: void lw6hlp_print_list_hooks (FILE * f)

> f: the file to print the content to

> Displays the list of 'hooks'.

> Return value: none

— Function: void lw6hlp_print_list_advanced (FILE * f)

> f: the file to print the content to

> Displays the list of 'advanced' options.

> Return value: none

— Function: void lw6hlp_print_list_aliases (FILE * f)

> f: the file to print the content to

> Displays the list of options aliases.

> Return value: none

— Function: void lw6hlp_print_list_team_colors (FILE * f)

> f: the file to print the content to

> Displays the list of team colors.

> Return value: none

— Function: void lw6hlp_print_list_weapons (FILE * f)

> f: the file to print the content to

> Displays the list of weapons.

> Return value: none

— Function: void lw6hlp_print_list (FILE * f)

> f: the file to print the content to

> Displays the list of all known options.

> Return value: none

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

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

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

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

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

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

> 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.