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

### 5.20 libhlp

#### 5.20.1 Overview

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

#### 5.20.2 API

— Function: int lw6hlp_is_documented (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: char * lw6hlp_about (lw6hlp_type_t * type, char ** default_value, int * min_value, int * max_value, 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 (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: char * lw6hlp_get_default_value (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 (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 (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.

> Return value: the string, must be freed.

— Function: int lw6hlp_match (char * keyword1, 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 ()

> Returns a list of all available keywords.

> Return value: a list containing all the keywords. Strings are not dynamically allocated, you can't modify them.

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

> mode: 0 for check only, 1 for full test

> Runs the `hlp` module test suite.

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