| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The AutoGen template file defines the content of the output text. It is composed of two parts. The first part consists of a pseudo macro invocation and commentary. It is followed by the template proper.
This pseudo macro is special. It is used to identify the file as a AutoGen template file, fixing the starting and ending marks for the macro invocations in the rest of the file, specifying the list of suffixes to be generated by the template and, optionally, the shell to use for processing shell commands embedded in the template.
AutoGen-ing a file consists of copying text from the template to the output file until a start macro marker is found. The text from the start marker to the end marker constitutes the macro text. AutoGen macros may cause sections of the template to be skipped or processed several times. The process continues until the end of the template is reached. The process is repeated once for each suffix specified in the pseudo macro.
This chapter describes the format of the AutoGen template macros and the usage of the AutoGen native macros. Users may augment these by defining their own macros. See section 3.6.4 DEFINE - Define a user AutoGen macro.
3.1 Format of the Pseudo Macro 3.2 Naming a value 3.3 Macro Expression Syntax 3.4 AutoGen Scheme Functions 3.5 Common Scheme Functions 3.6 AutoGen Native Macros 3.7 Redirecting Output
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The pseudo macro is used to tell AutoGen how to process a template. It tells autogen:
The next several components may be intermingled:
(suffix) scheme function (see section 3.4.34 `suffix' - get the current suffix).
The suffix specification consists of a sequence of POSIX compliant file name
characters and, optionally, an equal sign and a file name "printf"-style
formatting string. Two string arguments are allowed for that string:
the base name of the definition file and the current suffix (that being
the text to the left of the equal sign). (Note: "POSIX compliant file
name characters" consist of alphanumerics plus the period (.),
hyphen (-) and underscore (_) characters.)
#]),
and edit mode comments (text between pairs of -*- strings).
(setenv "SHELL" "/bin/sh") |
This is extremely useful to ensure that the shell used is the one the template was written to use. By default, AutoGen determines the shell to use by user preferences. Sometimes, that can be the "csh", though.
The scheme expression can also be used to save a pre-existing output file for later text extraction (see section 3.5.4 `extract' - extract text from another file).
(shellf "mv -f %1$s.c %1$s.sav" (base-name)) |
It is generally a good idea to use some sort of opening
bracket in the starting macro and closing bracket in the ending
macro (e.g. {, (, [, or even <
in the starting macro). It helps both visually and with editors
capable of finding a balancing parenthesis. The closing marker
may not begin with an open parenthesis, as that is used
to enclose a scheme expression.
It is also helpful to avoid using the comment marker (#);
the POSIXly acceptable file name characters period (.),
hyphen (-) and underscore (_); and finally, it is
advisable to avoid using any of the quote characters double,
single or back-quote. But there is no special check for any of
these advisories.
As an example, assume we want to use [+ and +] as the start
and end macro markers, and we wish to produce a `.c' and a `.h'
file, then the first macro invocation will look something like this:
[+ AutoGen5 template -*- Mode: emacs-mode-of-choice -*- h=chk-%s.h c # make sure we don't use csh: (setenv "SHELL" "/bin/sh") +] |
The template proper starts after the pseudo-macro. The starting character is either the first non-whitespace character or the first character after the newline that follows the end macro marker.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When an AutoGen value is specified in a template, it is specified by name. The name may be a simple name, or a compound name of several components. Since each named value in AutoGen is implicitly an array of one or more values, each component may have an index associated with it.
It looks like this:
comp-name-1 . comp-name-2 [ 2 ] |
Note that if there are multiple components to a name, each component
name is separated by a dot (.). Indexes follow a component name,
enclosed in square brackets ([ and ]). The index may be
either an integer or an integer-valued define name. The first component
of the name is searched for in the current definition level. If not
found, higher levels will be searched until either a value is found,
or there are no more definition levels. Subsequent components of the
name must be found within the context of the newly-current definition
level. Also, if the named value is prefixed by a dot (.), then
the value search is started in the current context only. No higher
levels are searched.
If someone rewrites this, I'll incorporate it. :-)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AutoGen has two types of expressions: full expressions and basic ones. A full AutoGen expression can appear by itself, or as the argument to certain AutoGen built-in macros: CASE, IF, ELIF, INCLUDE, INVOKE (explicit invocation, see section 3.6.16 INVOKE - Invoke a User Defined Macro), and WHILE. If it appears by itself, the result is inserted into the output. If it is an argument to one of these macros, the macro code will act on it sensibly.
You are constrained to basic expressions only when passing arguments to user defined macros, See section 3.6.4 DEFINE - Define a user AutoGen macro.
The syntax of a full AutoGen expression is:
[[ <apply-code> ] <value-name> ] [ <basic-expr-1> [ <basic-expr-2> ]] |
How the expression is evaluated depends upon the presence or absence
of the apply code and value name. The "value name" is the name of
an AutoGen defined value, or not. If it does not name such a value,
the expression result is generally the empty string. All expressions
must contain either a value-name or a basic-expr.
3.3.1 Apply Code 3.3.2 Basic Expression
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The "apply code" selected determines the method of evaluating the expression. There are five apply codes, including the non-use of an apply code.
value-name, if defined.
Otherwise it is the empty string.
value-name, then the basic-expr
is evaluated. Otherwise, the result is the empty string.
value-name is defined, use basic-expr as a format
string for sprintf. Then, if the basic-expr is either a back-quoted
string or a parenthesized expression, then hand the result to the
appropriate interpreter for further evaluation. Otherwise, for single
and double quote strings, the result is the result of the sprintf operation.
Naturally, if value-name is not defined, the result is the empty
string.
For example, assume that fumble had the string value, stumble:
[+ % fumble `printf '%%x\\n' $%s` +] |
printf '%x\n' $stumble".
Assuming that the shell variable stumble had a numeric value,
the expression result would be that number, in hex. Note the need
for doubled percent characters and backslashes.
basic-expr-s are required. If the value-name is
defined, then the first basic-expr-1 is evaluated, otherwise
basic-expr-2 is.
basic-expr only if value-name is not defined.
value-name is
defined, it behaves exactly like `%', above, using basic-expr-1.
If not defined, then basic-expr-2 is evaluated.
For example, assume again that fumble had the string value, stumble:
[+ ?% fumble `cat $%s` `pwd` +] |
cat $stumble".
If fumble were not defined, then the result would be the name
of our current directory.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A basic expression can have one of the following forms:
'), hash characters (#), or backslashes (\)
in the string. All other characters of STRING are output as-is when the
single quoted string is evaluated. Backslashes are processed before the hash
character for consistency with the definition syntax. It is needed there
to avoid preprocessing conflicts.
STRING" will output STRING with all
backslash sequences interpreted.
Additionally, other than in the % and ?% expressions, the
Guile expressions may be introduced with the Guile comment character
(;) and you may put a series of Guile expressions within a single
macro. They will be implicitly evaluated as if they were arguments
to the (begin ...) expression. The result will be the the
result of the last Guile expression evaluated.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AutoGen uses Guile to interpret Scheme expressions within AutoGen macros. All of the normal Guile functions are available, plus several extensions (see section 3.5 Common Scheme Functions) have been added to augment the repertoire of string manipulation functions and manage the state of AutoGen processing.
This section describes those functions that are specific to AutoGen. Please take note that these AutoGen specific functions are not loaded and thus not made available until after the command line options have been processed and the AutoGen definitions have been loaded. They may, of course, be used in Scheme functions that get defined at those times, but they cannot be invoked.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (ag-function? ag-name)
return SCM_BOOL_T if a specified name is a user-defined AutoGen
macro, otherwise return SCM_BOOL_F.
Arguments:
ag-name - name of AutoGen macro
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (base-name)
Returns a string containing the base name of the output file(s).
Generally, this is also the base name of the definitions file.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (count ag-name)
Count the number of entries for a definition.
The input argument must be a string containing the name
of the AutoGen values to be counted. If there is no
value associated with the name, the result is an SCM
immediate integer value of zero.
Arguments:
ag-name - name of AutoGen value
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (def-file)
Get the name of the definitions file.
Returns the name of the source file containing the AutoGen
definitions.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (dne prefix [ first_prefix ] [ optpfx ])
Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string.
Which depends on whether or not the --writable command line
option was set. The first argument is a per-line string prefix.
The optional second argument is a prefix for the first-line and,
in read-only mode, activates the editor hints.
-*- buffer-read-only: t -*- vi: set ro: |
The optional third argument is used when the first argument is actually
an invocation option and the prefix arguments get shifted.
The first argument must be, specifically, "-d". That is used
to signify that the date stamp should not be inserted into the output.
Arguments:
prefix - string for starting each output line
first_prefix - Optional - for the first output line
optpfx - Optional - shifted prefix
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (error message)
The argument is a string that printed out as part of an error
message. The message is formed from the formatting string:
DEFINITIONS ERROR in %s line %d for %s: %s\n |
The first three arguments to this format are provided by the routine and are: The name of the template file, the line within the template where the error was found, and the current output file name.
After displaying the message, the current output file is removed and autogen exits with the EXIT_FAILURE error code. IF, however, the argument begins with the number 0 (zero), or the string is the empty string, then processing continues with the next suffix.
Arguments:
message - message to display before exiting
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (exist? ag-name)
return SCM_BOOL_T iff a specified name has an AutoGen value.
The name may include indexes and/or member names.
All but the last member name must be an aggregate definition.
For example:
(exist? "foo[3].bar.baz") |
baz for some group value bar that
is a member of the foo group with index 3.
There may be multiple entries of bar within
foo, only one needs to contain a value for baz.
Arguments:
ag-name - name of AutoGen value
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (find-file file-name [ suffix ])
AutoGen has a search path that it uses to locate template and definition
files. This function will search the same list for `file-name', both
with and without the `.suffix', if provided.
Arguments:
file-name - name of file with text
suffix - Optional - file suffix to try, too
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (first-for? [ for_var ])
Returns SCM_BOOL_T if the named FOR loop (or, if not named, the
current innermost loop) is on the first pass through the data.
Outside of any FOR loop, it returns SCM_UNDEFINED.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (for-by by)
This function records the "step by" information
for an AutoGen FOR function.
Outside of the FOR macro itself, this function will emit an error.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
by - the iteration increment for the AutoGen FOR macro
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (for-from from)
This function records the initial index information
for an AutoGen FOR function.
Outside of the FOR macro itself, this function will emit an error.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
from - the initial index for the AutoGen FOR macro
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (for-index [ for_var ])
Returns the current index for the named FOR loop.
If not named, then the index for the innermost loop.
Outside of any FOR loop, it returns SCM_UNDEFINED.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (for-sep separator)
This function records the separation string that is to be inserted
between each iteration of an AutoGen FOR function. This is often
nothing more than a comma.
Outside of the FOR macro itself, this function will emit an error.
Arguments:
separator - the text to insert between the output of
each FOR iteration
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (for-to to)
This function records the terminating value information
for an AutoGen FOR function.
Outside of the FOR macro itself, this function will emit an error.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
to - the final index for the AutoGen FOR macro
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (get ag-name [ alt-val ])
Get the first string value associated with the name.
It will either return the associated string value (if
the name resolves), the alternate value (if one is provided),
or else the empty string.
Arguments:
ag-name - name of AutoGen value
alt-val - Optional - value if not present
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (high-lim ag-name)
Returns the highest index associated with an array of definitions.
This is generally, but not necessarily, one less than the
count value. (The indexes may be specified, rendering a
non-zero based or sparse array of values.)
This is very useful for specifying the size of a zero-based array of values where not all values are present. For example:
tMyStruct myVals[ [+ (+ 1 (high-lim "my-val-list")) +] ]; |
Arguments:
ag-name - name of AutoGen value
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (last-for? [ for_var ])
Returns SCM_BOOL_T if the named FOR loop (or, if not named, the
current innermost loop) is on the last pass through the data.
Outside of any FOR loop, it returns SCM_UNDEFINED.
See section 3.6.13 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (len ag-name)
If the named object is a group definition, then "len" is
the same as "count". Otherwise, if it is one or more text
definitions, then it is the sum of their string lengths.
If it is a single text definition, then it is equivalent to
(string-length (get "ag-name")).
Arguments:
ag-name - name of AutoGen value
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (low-lim ag-name)
Returns the lowest index associated with an array of definitions.
Arguments:
ag-name - name of AutoGen value
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (match-value? op ag-name test-str)
This function answers the question, "Is there an AutoGen value named
ag-name with a value that matches the pattern test-str
using the match function op?" Return SCM_BOOL_T iff at least
one occurrence of the specified name has such a value. The operator
can be any function that takes two string arguments and yields a
boolean. It is expected that you will use one of the string matching
functions provided by AutoGen.
The value name must follow the same rules as the
ag-name argument for exist? (see section 3.4.7 `exist?' - test for value name).
Arguments:
op - boolean result operator
ag-name - name of AutoGen value
test-str - string to test against
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-delete)
Remove the current output file. Cease processing the template for
the current suffix. It is an error if there are push-ed
output files. Use the (error "0") scheme function instead.
See section 3.7 Redirecting Output.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-depth)
Returns the depth of the output file stack.
See section 3.7 Redirecting Output.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-move new-name)
Rename current output file. See section 3.7 Redirecting Output.
Please note: changing the name will not save a temporary
file from being deleted. It may, however, be used on the
root output file.
Arguments:
new-name - new name for the current output file
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-name)
Returns the name of the current output file. If the current file
is a temporary, unnamed file, then it will scan up the chain until
a real output file name is found.
See section 3.7 Redirecting Output.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-pop [ disp ])
If there has been a push on the output, then close that
file and go back to the previously open file. It is an error
if there has not been a push. See section 3.7 Redirecting Output.
If there is no argument, no further action is taken. Otherwise,
the argument should be #t and the contents of the file
are returned by the function.
Arguments:
disp - Optional - return contents of the file
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-push-add file-name)
Identical to push-new, except the contents are not
purged, but appended to. See section 3.7 Redirecting Output.
Arguments:
file-name - name of the file to append text to
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-push-new [ file-name ])
Leave the current output file open, but purge and create
a new file that will remain open until a pop delete
or switch closes it. The file name is optional and, if omitted,
the output will be sent to a temporary file that will be deleted when
it is closed.
See section 3.7 Redirecting Output.
Arguments:
file-name - Optional - name of the file to create
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-resume suspName)
If there has been a suspended output, then make that output descriptor
current again. That output must have been suspended with the same tag
name given to this routine as its argument.
Arguments:
suspName - A name tag for reactivating
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-suspend suspName)
If there has been a push on the output, then set aside the
output descriptor for later reactiviation with (out-resume "xxx").
The tag name need not reflect the name of the output file. In fact,
the output file may be an anonymous temporary file. You may also
change the tag every time you suspend output to a file, because the
tag names are forgotten as soon as the file has been "resumed".
Arguments:
suspName - A name tag for reactivating
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (out-switch file-name)
Switch output files - close current file and make the current
file pointer refer to the new file. This is equivalent to
out-pop followed by out-push-new, except that
you may not pop the base level output file, but you may
switch it. See section 3.7 Redirecting Output.
Arguments:
file-name - name of the file to create
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (set-option opt)
The text argument must be an option name followed by any needed
option argument. Returns SCM_UNDEFINED.
Arguments:
opt - AutoGen option name + its argument
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (set-writable [ set? ])
This function will set the current output file to be writable
(or not). This is only effective if neither the --writable
nor --not-writable have been specified. This state
is reset when the current suffix's output is complete.
Arguments:
set? - Optional - boolean arg, false to make output non-writable
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (stack ag-name)
Create a scheme list of all the strings that are associated
with a name. They must all be text values or we choke.
Arguments:
ag-name - AutoGen value name
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (suffix)
Returns the current active suffix (see section 3.1 Format of the Pseudo Macro).
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (tpl-file)
Returns the name of the current template file.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (tpl-file-line [ msg-fmt ])
Returns the file and line number of the current template macro
using either the default format, "from %s line %d", or else
the format you supply. For example, if you want to insert a "C"
language file-line directive, you would supply the format "# %2$d %1$s".
Arguments:
msg-fmt - Optional - formatting for line message
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emit a #ifndef/#define sequence based upon the output
file name and the provided prefix. It will also define a scheme
variables named, header-file and header-guard.
The #define name is composed as follows:
_GUARD".
The final #define name is stored in an SCM symbol named
header-guard. Consequently, the concluding #endif for the
file should read something like:
#endif /* [+ (. header-guard) +] */ |
The name of the header file (the current output file) is also stored in an SCM
symbol, header-file. Therefore, if you are also generating a
C file that uses the previously generated header file, you can put
this into that generated file:
#include "[+ (. header-file) +]" |
Obviously, if you are going to produce more than one header file from a particular template, you will need to be careful how these SCM symbols get handled.
Arguments:
prefix - first segment of #define name
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is a symbol defining the current AutoGen version number string. It was first defined in AutoGen-5.2.14. It is currently "5.5.4".
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes a number of general purpose functions that make the kind of string processing that AutoGen does a little easier. Unlike the AutoGen specific functions (see section 3.4 AutoGen Scheme Functions), these functions are available for direct use during definition load time.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (bsd prog_name owner prefix)
Emit a string that contains the Free BSD Public License.
It takes three arguments:
prefix contains the string to start each output line.
owner contains the copyright owner.
prog_name contains the name of the program the copyright is about.
Arguments:
prog_name - name of the program under the BSD
owner - Grantor of the BSD License
prefix - String for starting each output line
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (c-string string)
Reform a string so that, when printed, the C compiler will be able to
compile the data and construct a string that contains exactly what the
current string contains. Many non-printing characters are replaced with
escape sequences. Newlines are replaced with a backslash, an n, a
closing quote, a newline, seven spaces and another re-opening quote. The
compiler will implicitly concatenate them. The reader will see line
breaks.
A K&R compiler will choke. Use kr-string for that compiler.
Arguments:
string - string to reformat
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (error-source-line)
This function is only invoked just before Guile displays
an error message. It displays the file name and line number
that triggered the evaluation error. You should not need to
invoke this routine directly. Guile will do it automatically.
This Scheme function takes no arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (extract file-name marker-fmt [ caveat ] [ default ])
This function is used to help construct output files that may contain
text that is carried from one version of the output to the next.
The first two arguments are required, the second are optional:
file-name argument is used to name the file that
contains the demarcated text.
marker-fmt is a formatting string that is used to construct
the starting and ending demarcation strings. The sprintf function is
given the marker-fmt with two arguments. The first is either
"START" or "END". The second is either "DO NOT CHANGE THIS COMMENT"
or the optional caveat argument.
caveat is presumed to be absent if it is the empty string
(""). If absent, "DO NOT CHANGE THIS COMMENT" is used
as the second string argument to the marker-fmt.
default argument is supplied and no pre-existing text
is found, then this text will be inserted between the START and END
markers.
[+ (extract "fname" "// %s - SOMETHING - %s" "" "example default") +] |
// START - SOMETHING - DO NOT CHANGE THIS COMMENT example default // END - SOMETHING - DO NOT CHANGE THIS COMMENT |
example default" string can then be carried forward to
the next generation of the output, provided the output
is not named "fname" and the old output is renamed to
"fname" before AutoGen-eration begins.
[+ AutoGen5 Template -*- Mode: text -*- h=%s-fsm.h c=%s-fsm.c (shellf "[ -f %1$s-fsm.h ] && mv -f %1$s-fsm.h .fsm.head [ -f %1$s-fsm.c ] && mv -f %1$s-fsm.c .fsm.code" (base-name)) +] |
This code will move the two previously produced output files to files named ".fsm.head" and ".fsm.code". At the end of the 'c' output processing, I delete them.
Arguments:
file-name - name of file with text
marker-fmt - format for marker text
caveat - Optional - warn about changing marker
default - Optional - default initial text
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (format-arg-count format)
Sometimes, it is useful to simply be able to figure out how many
arguments are required by a format string. For example, if you
are extracting a format string for the purpose of generating a
macro to invoke a printf-like function, you can run the
formatting string through this function to determine how many
arguments to provide for in the macro. e.g. for this extraction
text:
/*=fumble bumble * fmt: 'stumble %s: %d\n' =*/ |
You may wish to generate a macro:
#define BUMBLE(a1,a2) printf_like(something,(a1),(a2)) |
You can do this by knowing that the format needs two arguments.
Arguments:
format - formatting string
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (fprintf port format [ format-arg ... ])
Format a string using arguments from the alist.
Write to a specified port. The result will NOT appear in your
output. Use this to print information messages to a template user.
Arguments:
port - Guile-scheme output port
format - formatting string
format-arg - Optional - list of arguments to formatting string
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (gperf name str)
Perform the perfect hash on the input string. This is only useful if
you have previously created a gperf program with the make-gperf
function See section 3.5.15 `make-gperf' - build a perfect hash function program. The name you supply here must
match the name used to create the program and the string to hash must
be one of the strings supplied in the make-gperf string list.
The result will be a perfect hash index.
See the documentation for gperf(1GNU) for more details.
Arguments:
name - name of hash list
str - string to hash
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (gpl prog-name prefix)
Emit a string that contains the GNU General Public License.
It takes two arguments:
prefix contains the string to start each output line, and
prog_name contains the name of the program the copyright is
about.
Arguments:
prog-name - name of the program under the GPL
prefix - String for starting each output line
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (hide-email display eaddr)
Hides an email address as a java scriptlett.
The 'mailto:' tag and the email address are coded bytes
rather than plain text. They are also broken up.
Arguments:
display - display text
eaddr - email address
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (in? test-string string-list ...)
Return SCM_BOOL_T if the first argument string is found
in one of the entries in the second (list-of-strings) argument.
Arguments:
test-string - string to look for
string-list - list of strings to check
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (join separator list ...)
With the first argument as the separator string,
joins together an a-list of strings into one long string.
The list may contain nested lists, partly because you
cannot always control that.
Arguments:
separator - string to insert between entries
list - list of strings to join
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (kr-string string)
Reform a string so that, when printed, a K&R C compiler will be able
to compile the data and construct a string that contains exactly
what the current string contains. Many non-printing characters are
replaced with escape sequences. New-lines are replaced with a
backslash-n-backslash and newline sequence,
Arguments:
string - string to reformat
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (lgpl prog_name owner prefix)
Emit a string that contains the GNU Library General Public License.
It takes three arguments: prefix contains the string to
start each output line. owner contains the copyright owner.
prog_name contains the name of the program the copyright is about.
Arguments:
prog_name - name of the program under the LGPL
owner - Grantor of the LGPL
prefix - String for starting each output line
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (license lic_name prog_name owner prefix)
Emit a string that contains the named license. The license text
is read from a file named, lic_name.lic, searching the standard
directories. The file contents are used as a format argument
to printf(3), with prog_name and owner as
the two string formatting arguments. Each output line is automatically
prefixed with the string prefix.
Arguments:
lic_name - file name of the license
prog_name - name of the licensed program or library
owner - Grantor of the License
prefix - String for starting each output line
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (make-gperf name strings ...)
Build a program to perform perfect hashes of a known list of input
strings. This function produces no output, but prepares a program
named, `gperf_<name>' for use by the gperf