4.3 Guile Callout Functions

Callout functions must be registered with Guile to work. This can be accomplished either by putting your routines into a shared library that contains a void scm_init( void ) routine that registers these routines, or by building them into AutoGen.

To build them into AutoGen, you must place your routines in the source directory and name the files `exp*.c'. You also must have a stylized comment that `getdefs' can find that conforms to the following:

/*=gfunc <function-name>
 *
 *  what:    <short one-liner>
 *  general_use:
 *  string:  <invocation-name-string>
 *  exparg:  <name>, <description> [, ['optional'] [, 'list']]
 *  doc:     A long description telling people how to use
 *           this function.
=*/
SCM
ag_scm_<function-name>( SCM arg_name[, ...] )
{ <code> }

`gfunc'

You must have this exactly thus.

`<function-name>'

This must follow C syntax for variable names

`<short one-liner>'

This should be about a half a line long. It is used as a subsection title in this document.

`general_use:'

You must supply this unless you are an AutoGen maintainer and are writing a function that queries or modifies the state of AutoGen.

`<invocation-name-string>'

Normally, the function-name string will be transformed into a reasonable invocation name. However, that is not always true. If the result does not suit your needs, then supply an alternate string.

`exparg:'

You must supply one for each argument to your function. All optional arguments must be last. The last of the optional arguments may be a list, if you choose.

`doc:'

Please say something meaningful.

`[, ...]'

Do not actually specify an ANSI ellipsis here. You must provide for all the arguments you specified with exparg.

See the Guile documentation for more details. More information is also available in a large comment at the beginning of the `agen5/snarf.tpl' template file.