4. Augmenting AutoGen Features

AutoGen was designed to be simple to enhance. You can do it by providing shell commands, Guile/Scheme macros or callout functions that can be invoked as a Guile macro. Here is how you do these.

4.1 Shell Output Commands

Shell commands are run inside of a server process. This means that, unlike `make', context is kept from one command to the next. Consequently, you can define a shell function in one place inside of your template and invoke it in another. You may also store values in shell variables for later reference. If you load functions from a file containing shell functions, they will remain until AutoGen exits.

If your shell script should determine that AutoGen should stop processing, the recommended method for stopping AutoGen is:

die "some error text"

That is a shell function added by AutoGen. It will send a SIGTERM to autogen and exit from the "persistent" shell.

4.2 Guile Macros

Guile also maintains context from one command to the next. This means you may define functions and variables in one place and reference them elsewhere. You also may load Guile macro definitions from a Scheme file by using the --load-scheme command line option (see section load-scheme option (-S)). Beware, however, that the AutoGen specific scheme functions have not been loaded at this time, so though you may define functions that reference them, do not invoke the AutoGen functions at this time.

If your Scheme script should determine that AutoGen should stop processing, the recommended method for stopping AutoGen is:

(error "some error text")

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.

4.4 AutoGen Macros

There are two kinds those you define yourself and AutoGen native. The user-defined macros may be defined in your templates or loaded with the --lib-template option (See DEFINE - Define a user AutoGen macro and lib-template option (-l)).

As for AutoGen native macros, do not add any. It is easy to do, but I won't like it. The basic functions needed to accomplish looping over and selecting blocks of text have proved to be sufficient over a period of several years. New text transformations can be easily added via any of the AutoGen extension methods, as discussed above.

This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.