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_context_t * sys_context, lw6sys_list_t * funcs)

sys_context: global system context

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_context_t * sys_context, lw6sys_hash_t * coverage, const char * func)

sys_context: global system context

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_context_t * sys_context, lw6sys_hash_t * coverage)

sys_context: global system context

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 (lw6sys_context_t * sys_context, int * percent, lw6sys_hash_t * coverage, lw6sys_list_t * funcs)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const char * funcname)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const char * funcname)

sys_context: global system context

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: SCM lw6scm_gettext (lw6sys_context_t * sys_context, SCM string)

sys_context: global system context

string: SCM object to convert

For a GNU gettext-like behavior of scheme code, exported with a name such as _ then calling function _ from Guile will just do the same as _ in C.

Return value: SCM value, the translated string

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

sys_context: global system context

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 (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

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 (lw6sys_context_t * sys_context, SCM string)

sys_context: global system context

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_context_t * sys_context, lw6sys_list_t * c_list)

sys_context: global system context

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_context_t * sys_context, lw6sys_assoc_t * c_assoc)

sys_context: global system context

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 (lw6sys_context_t * sys_context, SCM list)

sys_context: global system context

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 (lw6sys_context_t * sys_context, SCM assoc)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const char * name, int req, int opt, int rst, lw6scm_func_t fcn)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const char * filename)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6scm_callback_t func, void * data)

sys_context: global system context

func: callback to use

data: data to pass to callback

Initializes Guile and calls function within it.

Return value: callback return value.