[ < ] | [ > ] | [ << ] | [ 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 function
See section 3.5.7 `gperf' - perform a perfect hash function.
This program will be obliterated within a few seconds after AutoGen exits.
Arguments:
name - name of hash list
strings - list of strings to hash
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (makefile-script text)
This function will take ordinary shell script text and reformat it
so that it will work properly inside of a makefile shell script.
Not every shell construct can be supported; the intent is to have
most ordinary scripts work without much, if any, alteration.
The following transformations are performed on the source text:
make
renders it impossible to use multi-line
constructs anyway.
$(<command>)
will not work. Though some
make
s accept ${var}
constructs, this function will
assume it is for shell interpretation and double the dollar character.
You must use $(var)
for all make
substitutions.
This function is intended to be used approximately as follows:
$(TARGET) : $(DEPENDENCIES) <+ (out-push-new) +> ....mostly arbitrary shell script text.... <+ (makefile-script (out-pop #t)) +> |
Arguments:
text - the text of the script
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (max list ...)
Return the maximum value in the list
Arguments:
list - list of values. Strings are converted to numbers
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (min list ...)
Return the minimum value in the list
Arguments:
list - list of values. Strings are converted to numbers
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (prefix prefix text)
Prefix every line in the second string with the first string.
For example, if the first string is "# " and the second contains:
two lines |
# two # lines |
Arguments:
prefix - string to insert at start of each line
text - multi-line block of text
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (printf format [ format-arg ... ])
Format a string using arguments from the alist.
Write to the standard out port. The result will NOT appear in your
output. Use this to print information messages to a template user.
Use "(sprintf ...)" to add text to your document.
Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (raw-shell-str string)
Convert the text of the string into a singly quoted string
that a normal shell will process into the original string.
(It will not do macro expansion later, either.)
Contained single quotes become tripled, with the middle quote
escaped with a backslash. Normal shells will reconstitute the
original string.
NOTE: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.
Arguments:
string - string to transform
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (shell command)
Generate a string by writing the value to
a server shell and reading the output back in. The template
programmer is responsible for ensuring that it completes
within 10 seconds. If it does not, the server will be killed,
the output tossed and a new server started.
Arguments:
command - shell command - the result value is stdout
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (shell-str string)
Convert the text of the string into a double quoted string that a normal
shell will process into the original string, almost. It will add the
escape character \\
before two special characters to
accomplish this: the backslash \\
and double quote "
.
NOTE: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.
WARNING:
This function omits the extra backslash in front of a backslash, however,
if it is followed by either a backquote or a dollar sign. It must do this
because otherwise it would be impossible to protect the dollar sign or
backquote from shell evaluation. Consequently, it is not possible to
render the strings "\\$" or "\\`". The lesser of two evils.
All others characters are copied directly into the output.
The sub-shell-str
variation of this routine behaves identically,
except that the extra backslash is omitted in front of "
instead
of `
. You have to think about it. I'm open to suggestions.
Meanwhile, the best way to document is with a detailed output example.
If the backslashes make it through the text processing correctly,
below you will see what happens with three example strings. The first
example string contains a list of quoted foo
s, the second is
the same with a single backslash before the quote characters and the
last is with two backslash escapes. Below each is the result of the
raw-shell-str
, shell-str
and sub-shell-str
functions.
foo[0] 'foo' "foo" `foo` $foo raw-shell-str -> ''\''foo'\'' "foo" `foo` $foo' shell-str -> "'foo' \"foo\" `foo` $foo" sub-shell-str -> `'foo' "foo" \`foo\` $foo` foo[1] \'bar\' \"bar\" \`bar\` \$bar raw-shell-str -> '\'\''bar\'\'' \"bar\" \`bar\` \$bar' shell-str -> "\\'bar\\' \\\"bar\\\" \`bar\` \$bar" sub-shell-str -> `\\'bar\\' \"bar\" \\\`bar\\\` \$bar` foo[2] \\'BAZ\\' \\"BAZ\\" \\`BAZ\\` \\$BAZ raw-shell-str -> '\\'\''BAZ\\'\'' \\"BAZ\\" \\`BAZ\\` \\$BAZ' shell-str -> "\\\\'BAZ\\\\' \\\\\"BAZ\\\\\" \\\`BAZ\\\` \\\$BAZ" sub-shell-str -> `\\\\'BAZ\\\\' \\\"BAZ\\\" \\\\\`BAZ\\\\\` \\\$BAZ` |
There should be four, three, five and three backslashes for the four examples on the last line, respectively. The next to last line should have four, five, three and three backslashes. If this was not accurately reproduced, take a look at the agen5/test/shell.test test. Notice the backslashes in front of the dollar signs. It goes from zero to one to three for the "cooked" string examples.
Arguments:
string - string to transform
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (shellf format [ format-arg ... ])
Format a string using arguments from the alist,
then send the result to the shell for interpretation.
Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (sprintf format [ format-arg ... ])
Format a string using arguments from the alist.
Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-capitalize str)
Create a new SCM string containing the same text as the original,
only all the first letter of each word is upper cased and all
other letters are made lower case.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-capitalize! str)
capitalize all the words in an SCM string.
Arguments:
str - input/output string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*=* text match)
string-contains-eqv?: Test to see if a string contains an equivalent string.
`equivalent' means the strings match, but without regard
to character case and certain characters are considered `equivalent'.
Viz., '-', '_' and '^' are equivalent.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*==* text match)
string-contains?: Test to see if a string contains a substring. "strstr(3)"
will find an address.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-downcase str)
Create a new SCM string containing the same text as the original,
only all the upper case letters are changed to lower case.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-downcase! str)
Change to lower case all the characters in an SCM string.
Arguments:
str - input/output string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*~ text match)
string-end-eqv-match?: Test to see if a string ends with a pattern.
Case is not significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*~~ text match)
string-end-match?: Test to see if a string ends with a pattern.
Case is significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*= text match)
string-ends-eqv?: Test to see if a string ends with an equivalent string.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*== text match)
string-ends-with?: Test to see if a string ends with a substring.
strcmp(3) returns zero for comparing the string ends.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (== text match)
string-equals?: Test to see if two strings exactly match.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (~ text match)
string-eqv-match?: Test to see if a string fully matches a pattern.
Case is not significant, but any character equivalences
must be expressed in your regular expression.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (= text match)
string-eqv?: Test to see if two strings are equivalent. `equivalent' means the
strings match, but without regard to character case and certain
characters are considered `equivalent'. Viz., '-', '_' and '^' are
equivalent. If the arguments are not strings, then the result of the
numeric comparison is returned.
This is an overloaded operation. If the arguments are not both
strings, then the query is passed through to scm_num_eq_p()
.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*~* text match)
string-has-eqv-match?: Test to see if a string contains a pattern.
Case is not significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (*~~* text match)
string-has-match?: Test to see if a string contains a pattern.
Case is significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (~~ text match)
string-match?: Test to see if a string fully matches a pattern.
Case is significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (~* text match)
string-start-eqv-match?: Test to see if a string starts with a pattern.
Case is not significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (~~* text match)
string-start-match?: Test to see if a string starts with a pattern.
Case is significant.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (=* text match)
string-starts-eqv?: Test to see if a string starts with an equivalent string.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (==* text match)
string-starts-with?: Test to see if a string starts with a substring.
Arguments:
text - text to test for pattern
match - pattern/substring to search for
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-substitute source match repl)
match
and repl
may be either a single string or
a list of strings. Either way, they must have the same structure
and number of elements. For example, to replace all less than
and all greater than characters, do something like this:
(string-substitute source '("&" "<" ">") '("&" "<" ">")) |
Arguments:
source - string to transform
match - substring or substring list to be replaced
repl - replacement strings or substrings
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string->c-name! str)
Change all the graphic characters that are invalid in a C name token
into underscores. Whitespace characters are ignored. Any other
character type (i.e. non-graphic and non-white) will cause a failure.
Arguments:
str - input/output string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-tr source match translation)
This is identical to string-tr!
, except that it does not
over-write the previous value.
Arguments:
source - string to transform
match - characters to be converted
translation - conversion list
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-tr! source match translation)
This is the same as the tr(1)
program, except the
string to transform is the first argument. The second and
third arguments are used to construct mapping arrays for the
transformation of the first argument.
It is too bad this little program has so many different and incompatible implementations!
Arguments:
source - string to transform
match - characters to be converted
translation - conversion list
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-upcase str)
Create a new SCM string containing the same text as the original,
only all the lower case letters are changed to upper case.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (string-upcase! str)
Change to upper case all the characters in an SCM string.
Arguments:
str - input/output string
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (sub-shell-str string)
This function is substantially identical to shell-str
, except
that the quoting character is `
and the "leave the escape alone"
character is "
.
Arguments:
string - string to transform
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (sum list ...)
Compute the sum of the list of expressions.
Arguments:
list - list of values. Strings are converted to numbers
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Usage: (html-escape-encode str)
Substitute escape sequences for characters that are special to HTML/XML.
It will replace "&
", "<
" and ">
" with the strings,
"&
", "<
", and ">
", respectively.
Arguments:
str - string to transform
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the various AutoGen natively defined macros. Unlike the Scheme functions, some of these macros are "block macros" with a scope that extends through a terminating macro. Block macros must not overlap. That is to say, a block macro started within the scope of an encompassing block macro must have its matching end macro appear before the encompassing block macro is either ended or subdivided.
The block macros are these:
CASE
ESAC
macro.
The scope is subdivided by SELECT
macros.
You must have at least one SELECT
macro.
DEFINE
ENDDEF
macro.
The defined user macro can never be a block macro.
FOR
ENDFOR
macro.
IF
ENDIF
macro.
The scope may be subdivided by ELIF
and ELSE
macros. Obviously, there may be only one ELSE
macro
and it must be the last of these subdivisions.
INCLUDE
WHILE
ENDWHILE
macro.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The general syntax is:
[ { <native-macro-name> | <user-defined-name> } ] [ <arg> ... ] |
The syntax for <arg>
depends on the particular macro,
but is generally a full expression (see section 3.3 Macro Expression Syntax).
Here are the exceptions to that general rule:
INVOKE
macros, implicit or explicit, must be followed by
a list of name/string value pairs. The string values are
simple expressions, as described above.
That is, the INVOKE
syntax is either:
<user-macro-name> [ <name> [ = <expression> ] ... ] |
INVOKE <name-expression> [ <name> [ = <expression> ] ... ] |
FOR <name> [ <separator-string> ] |
FOR <name> (...Scheme expression list) |
<name>
must be a simple name and the Scheme expression list
is expected to contain one or more of the for-from
,
for-to
, for-by
, and for-sep
functions.
(See section 3.6.13 FOR - Emit a template block multiple times, and 3.4 AutoGen Scheme Functions)
DEFINE
macros must be followed by a simple name.
Anything after that is ignored. See section 3.6.4 DEFINE - Define a user AutoGen macro.
COMMENT
, ELSE
, ESAC
and the END*
macros take no arguments and ignore everything after the macro name
(e.g. see 3.6.3 COMMENT - A block of comment to be ignored)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The arguments are evaluated and converted to a string, if necessary. (see section 3.6.12 EXPR - Evaluate and emit an Expression) The scope of the macro is up to the matching ESAC function. Within the scope of a CASE, this string is matched against case selection macros. There are sixteen match macros that are derived from four different ways the test may be performed, plus an "always true" match. The code for each selection expression is formed as follows:
*
).
*
).
=
).
If a pattern match, use a tilde (~
).
*
).
For example:
[+ CASE <full-expression> +] [+ ~~* "[Tt]est" +]reg exp must match at start, not at end [+ == "TeSt" +]a full-string, case sensitive compare [+ = "TEST" +]a full-string, case insensitive compare [+ * +]always match - no testing [+ ESAC +] |
<full-expression>
(see section 3.3 Macro Expression Syntax) may be any expression,
including the use of apply-codes and value-names. If the expression yields
a number, it is converted to a decimal string.
These case selection codes have also been implemented as Scheme expression functions using the same codes (see section 3.5 Common Scheme Functions).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function can be specified by the user, but there will never be a situation where it will be invoked at emit time. The macro is actually removed from the internal representation.
If the native macro name code is #
, then the
entire macro function is treated as a comment and ignored.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function will define a new macro. You must provide a name for the macro. You do not specify any arguments, though the invocation may specify a set of name/value pairs that are to be active during the processing of the macro.
[+ define foo +] ... macro body with macro functions ... [+ enddef +] ... [+ foo bar='raw text' baz=<<text expression>> +] |
Once the macro has been defined, this new macro can be invoked by
specifying the macro name as the first token after the start macro
marker. Alternatively, you may make the invocation explicitly invoke a
defined macro by specifying INVOKE
in the macro invocation. If
you do that, the macro name can be computed with an expression that gets
evaluated every time the INVOKE macro is encountered. See section 3.6.16 INVOKE - Invoke a User Defined Macro.
Any remaining text in the macro invocation will be used to create new name/value pairs that only persist for the duration of the processing of the macro. The expressions are evaluated the same way basic expressions are evaluated. See section 3.3 Macro Expression Syntax.
The resulting definitions are handled much like regular definitions, except:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro must only appear after an IF
function, and
before any associated ELSE
or ENDIF
functions.
It denotes the start of an alternate template block for the
IF
function. Its expression argument is evaluated as are
the arguments to IF
. For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro must only appear after an IF
function,
and before the associated ENDIF
function.
It denotes the start of an alternate template block for
the IF
function. For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro ends the DEFINE
function template block.
For a complete description See section 3.6.4 DEFINE - Define a user AutoGen macro.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
FOR
function template block
This macro ends the FOR
function template block.
For a complete description See section 3.6.13 FOR - Emit a template block multiple times.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
IF
Template Block
This macro ends the IF
function template block.
For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
WHILE
Template Block
This macro ends the WHILE
function template block.
For a complete description See section 3.6.19 WHILE - Conditionally loop over a Template Block.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
CASE
Template Block
This macro ends the CASE
function template block.
For a complete description, See section 3.6.2 CASE - Select one of several template blocks.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro does not have a name to cause it to be invoked explicitly, though if a macro starts with one of the apply codes or one of the simple expression markers, then an expression macro is inferred. The result of the expression evaluation (see section 3.3 Macro Expression Syntax) is written to the current output.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro has a slight variation on the standard syntax:
FOR <value-name> [ <separator-string> ] |
FOR <value-name> (...Scheme expression list |
FOR <value-name> IN "quoted string" unquoted-string ... |
Other than for the last form, the first macro argument must be the name of
an AutoGen value. If there is no value associated with the name, the
FOR
template block is skipped entirely. The scope of the FOR
macro extends to the corresponding ENDFOR
macro. The last form will
create an array of string values named <value-name>
that only exists
within the context of this FOR
loop. With this form, in order to
use a separator-string
, you must code it into the end of the
template block using the (last-for?)
predicate function
(see section 3.4.17 `last-for?' - detect last iteration).
If there are any arguments after the value-name
, the initial
characters are used to determine the form. If the first character is
either a semi-colon (;
) or an opening parenthesis ((
), then
it is presumed to be a Scheme expression containing the FOR macro specific
functions for-from
, for-by
, for-to
, and/or
for-sep
. See section 3.4 AutoGen Scheme Functions. If it consists of an 'i
'
an 'n
' and separated by white space from more text, then the
FOR x IN
form is processed. Otherwise, the remaining text is
presumed to be a string for inserting between each iteration of the loop.
This string will be emitted one time less than the number of iterations of
the loop. That is, it is emitted after each loop, excepting for the last
iteration.
If the from/by/to functions are invoked, they will specify which copies of
the named value are to be processed. If there is no copy of the named
value associated with a particular index, the FOR
template block
will be instantiated anyway. The template must use methods for detecting
missing definitions and emitting default text. In this fashion, you can
insert entries from a sparse or non-zero based array into a dense, zero
based array.
NB: the for-from
, for-to
, for-by
and
for-sep
functions are disabled outside of the context of the
FOR
macro. Likewise, the first-for
, last-for
and for-index
functions are disabled outside of the range
of a FOR
block.
[+FOR var (for-from 0) (for-to <number>) (for-sep ",") +]
... text with |
this will repeat the ... text with
<number>+1 times. Each repetition,
except for the last, will have a comma var
ious
substitutions ...,
after it.
[+FOR var ",\n" +]
... text with |
This will do the same thing, but only for the index
values of var
that have actually been defined.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Conditional block. Its arguments are evaluated (see section 3.6.12 EXPR - Evaluate and emit an Expression) and
if the result is non-zero or a string with one or more bytes,
then the condition is true and the text from that point
until a matched ELIF
, ELSE
or ENDIF
is emitted.
ELIF
introduces a conditional alternative if the IF
clause evaluated FALSE and ELSE
introduces an unconditional
alternative.
[+IF <full-expression> +] emit things that are for the true condition[+ ELIF <full-expression-2> +] emit things that are true maybe[+ ELSE "This may be a comment" +] emit this if all but else fails[+ ENDIF "This may *also* be a comment" +] |
<full-expression>
may be any expression described in the
EXPR
expression function, including the use of apply-codes
and value-names. If the expression yields an empty string, it
is interpreted as false.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The entire contents of the named file is inserted at this point. The contents of the file are processed for macro expansion. The arguments are eval-ed, so you may compute the name of the file to be included. The included file must not contain any incomplete function blocks. Function blocks are template text beginning with any of the macro functions `CASE', `DEFINE', `FOR', `IF' and `WHILE'; extending through their respective terminating macro functions.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
User defined macros may be invoked explicitly or implicitly.
If you invoke one implicitly, the macro must begin with the
name of the defined macro. Consequently, this may not
be a computed value. If you explicitly invoke a user defined macro,
the macro begins with the macro name INVOKE
followed by
a basic expression that must yield a known user defined macro.
A macro name _must_ be found, or AutoGen will issue a diagnostic
and exit.
Arguments are passed to the invoked macro by name.
The text following the macro name must consist of a series of
names each of which is followed by an equal sign (=
) and
a basic expression that yields a string.
The string values may contain template macros that are parsed the first time the macro is processed and evaluated again every time the macro is evaluated.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This macro selects a block of text by matching an expression
against the sample text expression evaluated in the CASE
macro. See section 3.6.2 CASE - Select one of several template blocks.
You do not specify a SELECT
macro with the word "select".
Instead, you must use one of the 17 match operators described in
the CASE
macro description.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The macro text has started with a name not known to AutoGen. If, at run time, it turns out to be the name of a defined macro, then that macro is invoked. If it is not, then it is a conditional expression that is evaluated only if the name is defined at the time the macro is invoked.
You may not specify UNKNOWN
explicitly.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Conditionally repeated block. Its arguments are evaluated (see section 3.6.12 EXPR - Evaluate and emit an Expression)
and as long as the result is non-zero or a string with one or more bytes,
then the condition is true and the text from that point
until a matched ENDWHILE
is emitted.
[+WHILE <full-expression> +] emit things that are for the true condition[+ ENDWHILE +] |
<full-expression>
may be any expression described in the
EXPR
expression function, including the use of apply-codes
and value-names. If the expression yields an empty string, it
is interpreted as false.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AutoGen provides a means for redirecting the template output
to different files. It is accomplished by providing a set of
Scheme functions named out-*
(see section 3.4 AutoGen Scheme Functions).
There are also several functions for determining the output status. See section 3.4 AutoGen Scheme Functions.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |