libscm - Liquid War 6
Description: Liquid War 6

Next: libsim, Previous: libpil, Up: C API

### 5.38 libscm

#### 5.38.1 Overview

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

#### 5.38.2 API

— Function: lw6sys_hash_t * lw6scm_coverage_new (lw6sys_list_t * funcs)

> funcs: list of functions, used as an input to size the hash correctly

> Creates a new coverage hash, this is a simple hash containing pointers to integers. At startup hash is empty, whenever a scheme user function is called, if the entry exists it's incremented, else it's created with an initial value of 1 (one call).

> Return value: newly allocated hash

— Function: void lw6scm_coverage_call (lw6sys_hash_t * coverage, const char * func)

> coverage: the hash to use to store the update

> func: the name of the function (its callable scheme name)

> Registers a call on a given function.

> Return value: none.

— Function: void lw6scm_coverage_log (lw6sys_hash_t * coverage)

> coverage: the hash containing the call data

> Logs the information about which function has been called, and how many times. This is only about scheme functions.

> Return value: none

— Function: int lw6scm_coverage_check (int * percent, lw6sys_hash_t * coverage, lw6sys_list_t * funcs)

> percent: if not NULL, will contain the percentage of coverage

> coverage: object to query, containing coverage information

> funcs: list of functions to check

> Checks wether the script code coverage is fine, that is, wether all functions are called at least once. For each function listed (as a string) in funcs, it will look in coverage and check wether the entry exists and was called. Note that this function assumes that in c functions are defined with _scm_my_function (prefixed with _scm_ and using underscore) while in scm functions are defined with c-my-function (prefixed with c- and using minus).

> Return value: 1 if OK, 0 if KO.

— Function: char * lw6scm_funcname_scm2c (const char * funcname)

> funcname: function name to change

> Transforms a function name of the form c-my-func to _scm_my_func.

> Return value: new allocated string.

— Function: char * lw6scm_funcname_c2scm (const char * funcname)

> funcname: function name to change

> Transforms a function name of the form _scm_my_func to c-my-func.

> Return value: new allocated string.

— Function: int lw6scm_test_register (int mode)

> mode: test mode (bitmask)

> Registers all tests for the libscm module.

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

— Function: int lw6scm_test_run (int mode)

> mode: test mode (bitmask)

> Runs the `scm` module test suite, testing most (if not all...) functions.

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

— Function: char * lw6scm_utils_to_0str (SCM string)

> string: SCM object to convert

> Helper function, creates a 0 terminated string from a Guile string. A very common task. This function is just a wrapper that performs type checking, memory allocation around standard Guile function.

> Return value: newly allocated string, pointer must be freed.

— Function: SCM lw6scm_utils_to_scm_str_list (lw6sys_list_t * c_list)

> c_list: list object to convert

> Transform a C list containing strings to a Guile list containing those strings.

> Return value: Guile object, a list of strings

— Function: SCM lw6scm_utils_to_scm_str_assoc (lw6sys_assoc_t * c_assoc)

> c_assoc: assoc object to convert

> Transform a C assoc containing strings to a Guile assoc containing those strings.

> Return value: Guile object, an assoc of strings

— Function: lw6sys_list_t * lw6scm_utils_to_sys_str_list (SCM list)

> list: SCM object to convert

> Creates a C list from an SCM list containing strings. Beware of types, function will fail if members are not all strings, it won't convert them.

> Return value: new C list object

— Function: lw6sys_assoc_t * lw6scm_utils_to_sys_str_assoc (SCM assoc)

> assoc: SCM object to convert

> Creates a C assoc from an SCM assoc containing strings. Beware of types, function will fail if members are not all strings, it won't convert them.

> Return value: new C assoc object

— Function: int lw6scm_c_define_gsubr (const char * name, int req, int opt, int rst, lw6scm_func_t fcn)

> name: name of the function when called from guile

> req: required parameters

> opt: optional parameters

> rst: ? should RTFM to find that out

> fcn: the function itself (pointer on the C executable code)

> Wrapper on `scm_c_define_gsubr`, one of the value of this function is that it does check wether it's documented before registering it. So if you try to register something not documented, it will fire a warning, which is a very nice code-quality tool.

> Return value: 1 on success, 0 on failure.

— Function: int lw6scm_c_primitive_load (const char * filename)

> filename: file to execute

> Loads and executes a script. Will add a log message while doing it.

> Return value: 1 on success, 0 on failure.

— Function: void * lw6scm_with_guile (lw6scm_callback_t func, void * data)

> func: callback to use

> data: data to pass to callback

> Initializes Guile and calls function within it.

> Return value: callback return value.