Go to the first, previous, next, last section, table of contents.
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 DEFINE - Define a user AutoGen macro.
The pseudo-macro starts with up to seven (7) punctuation characters used
for the template start-macro marker, followed by the autogen magic
marker (autogen5), the template marker (template), zero or
more suffix specifications, scheme expressions and the end-macro marker.
It may also consist of up to seven (7) punctuation characters. Interspersed
may be comment lines (blank lines or lines starting with a hash mark
[#]) and edit mode markers (text between pairs of -*-
characters).
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: (setup "SHELL" "/bin/sh") +]
Note 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.
Detailed description:
The starting macro marker must be the first non-white space characters encountered in the file. The marker consists of all the contiguous ASCII punctuation characters found there. With optional intervening white space, this marker must be immediately followed by the keywords, "autogen5" and "template". Capitalization of these words is not important. This is followed by zero, one or more suffix specifications and, possibly, a scheme expression.
Suffix specifications consist 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.) If there are
no suffix specifications, then the generated file will be written to the
stdout file descriptor.
The scheme expression is intended to allow the template writer to specify the shell program that must be used to interpret the shell commands in the template. It can have no effect on any shell commands in the definitions file, as that file will have been processed by the time the pseudo macro is interpreted. You can specify the shell as follows:
(setenv "SHELL" "/bin/sh")
This works because AutoGen examines the value of the SHELL environment
variable in order to select the shell to run. If that shell is allowed
to be csh, AutoGen will break. If it is allowed to be zsh,
AutoGen may break. Your milage may vary.
The pseudo macro ends with an end macro marker. Like the starting macro marker, it consists of a contiguous sequence of arbitrary punctuation characters. However, additionally, it may not begin with any of the POSIX file name characters and it may not contain the start macro marker.
This pseudo macro may appear on one or several lines of text.
Intermixed may be comment lines (completely blank or starting with the
hash character # in column 1), and file content markers (text
between -*- pairs on a single line). This may be used to
establish editing "modes" for the file. These are ignored by
AutoGen.
The template proper starts after the pseudo-macro. The starting character is either the first non-whitespace character or the first character after the new-line that follows the end macro marker.
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. :-)
The syntax of a full AutoGen expression is:
[[ <apply-code> ] <value-name> ] [ <simple-expr-1> [ <simple-expr-2> ]]
Where
-, ?, % or ?% (see below).
; or (;
a shell expression surrounded with `; or a string, quoted or
unquoted.
? or ?% apply-code has
been specified.
There are some places where only a simple expression (i.e. just the
<simple-expr-1> clause) is allowed. I hope I have clearly
marked which macros have those requirements. Otherwise, in the
macro descriptions that follow, a full expression refers to
what we are describing here.
The result of the expression evaluation will depend on what apply code has been provided, whether or not there is an associated value for the value name, and whether or not expressions are specified.
The syntax rules are:
? or ?%, then two
expressions must be provided, otherwise only one expression
may be provided.
The apply codes used are as follows:
-'
?'
%'
% character.
?%'
?and %, but for
obvious reasons, only the first expression will be used as a
format argument.
<value-name>. If there is an associated value, then the
expression result is the result of evaluating <expression-1>
(if present), otherwise it is the value associated with
<value-name>.
The simple expression clauses are interpreted differently, depending on the first character:
; (semi-colon)'
( (open parenthesis)'
' (single quote)'
'), the hash character (#) and
backslash (\).
" (double quote)'
` (back quote)'
AutoGen uses Guile to interpret Scheme expressions within AutoGen macros. All of the normal Guile functions are available, plus several extensions (see section 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.
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
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.
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
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.
Usage: (dne prefix [ first_prefix ])
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 argument is a per-line string prefix.
The optional second argument is a first-line prefix and,
in read-only mode, activates the editor hints:
-*- buffer-read-only: t -*- vi: set ro:
Arguments:
prefix - string for starting each output line
first_prefix - Optional - for the first output line
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
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.
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")
will yield true if all of the following is true:
There is a member value of either group or string type
named 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
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 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
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 FOR - Emit a template block multiple times.
Arguments:
by - the iteration increment for the AutoGen FOR macro
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 FOR - Emit a template block multiple times.
Arguments:
from - the initial index for the AutoGen FOR macro
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 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
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
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 FOR - Emit a template block multiple times.
Arguments:
to - the final index for the AutoGen FOR macro
Usage: (get ag-name)
Get the first string value associated with the name.
It will always return either the associated string value, or
the empty string.
Arguments:
ag-name - name of AutoGen value
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
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 FOR - Emit a template block multiple times.
Arguments:
for_var - Optional - which for loop
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
Usage: (low-lim ag-name)
Returns the lowest index associated with an array of definitions.
Arguments:
ag-name - name of AutoGen value
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 `exist?' - test for value name).
Arguments:
op - boolean result operator
ag-name - name of AutoGen value
test-str - string to test against
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 Redirecting Output.
This Scheme function takes no arguments.
Usage: (out-depth)
Returns the depth of the output file stack.
See section Redirecting Output.
This Scheme function takes no arguments.
Usage: (out-move new-name)
Rename current output file. See section 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
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 Redirecting Output.
This Scheme function takes no arguments.
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 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
Usage: (out-push-add file-name)
Identical to push-new, except the contents are not
purged, but appended to. See section Redirecting Output.
Arguments:
file-name - name of the file to append text to
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 Redirecting Output.
Arguments:
file-name - Optional - name of the file to create
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
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
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 Redirecting Output.
Arguments:
file-name - name of the file to create
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
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
Usage: (suffix)
Returns the current active suffix. See generate in the
Declarations Input section above.
This Scheme function takes no arguments.
Usage: (tpl-file)
Returns the name of the current template file.
This Scheme function takes no arguments.
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 only the line
number, you would supply the format "%2$d".
Arguments:
msg-fmt - Optional - formatting for line message
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 AutoGen Scheme Functions), these functions are available for direct use during definition load time.
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
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
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.
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.
The resulting strings are presumed to be unique within the subject file. As a simplified example:
[+ (extract "fname" "// %s - SOMETHING - %s" "" "example default") +]
will result in the following text being inserted into the output:
// START - SOMETHING - DO NOT CHANGE THIS COMMENT example default // END - SOMETHING - DO NOT CHANGE THIS COMMENT
The "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.
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
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
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 `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 @command{gperf(1GNU)} for more details.
Arguments:
name - name of hash list
str - string to hash
Usage: (gpl prog-name prefix)
Emit a string that contains the GNU 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
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
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
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
Usage: (lgpl prog_name owner prefix)
Emit a string that contains the GNU Library 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 (obsolete)
prefix - String for starting each output line
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
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 `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
Usage: (max list ...)
Return the maximum value in the list
Arguments:
list - list of values. Strings are converted to numbers
Usage: (min list ...)
Return the minimum value in the list
Arguments:
list - list of values. Strings are converted to numbers
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
The result string will contain:
# two # lines
Arguments:
prefix - string to insert at start of each line
text - multi-line block of text
Usage: (printf format [ format-arg ... ])
Format a string using arguments from the alist.
Write to the default output port. The result will NOT appear in your
output. Use this to print information messages to a template user.
Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string
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
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
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
Arguments:
string - string to transform
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
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
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.
Arguments:
str - input string
Usage: (string-capitalize! str)
capitalize all the words in an SCM string.
Arguments:
str - input/output string
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
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
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.
Arguments:
str - input string
Usage: (string-downcase! str)
Change to lower case all the characters in an SCM string.
Arguments:
str - input/output string
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
Arguments:
str - input string
Usage: (string-upcase! str)
Change to upper case all the characters in an SCM string.
Arguments:
str - input/output string
Usage: (sum list ...)
Compute the sum of the list of expressions.
Arguments:
list - list of values. Strings are converted to numbers
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.
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 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> ] ... ]or
INVOKE <name-expression> [ <name> [ = <expression> ] ... ]
FOR <name> [ <separator-string> ]or
FOR <name> (...Scheme expression list)where
<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 FOR - Emit a template block multiple times, and section AutoGen Scheme Functions)
DEFINE macros must be followed by a simple name.
Anything after that is ignored. See section 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 section COMMENT - A block of comment to be ignored)
The arguments are evaluated and converted to a string, if necessary. (see section 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 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 Common Scheme Functions).
If the native macro name code is #, then the
entire macro function is treated as a comment and ignored.
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 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 simple expressions are evaluated. See section Macro Expression Syntax.
The resulting definitions are handled much like regular definitions, except:
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 IF - Conditionally Emit a Template Block.
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 IF - Conditionally Emit a Template Block.
This macro ends the DEFINE function template block.
For a complete description See section DEFINE - Define a user AutoGen macro.
FOR function template block
This macro ends the FOR function template block.
For a complete description See section FOR - Emit a template block multiple times.
IF Template Block
This macro ends the IF function template block.
For a complete description See section IF - Conditionally Emit a Template Block.
WHILE Template Block
This macro ends the WHILE function template block.
For a complete description See section WHILE - Conditionally loop over a Template Block.
CASE Template Block
This macro ends the CASE function template block.
For a complete description, See section CASE - Select one of several template blocks.
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 Macro Expression Syntax) is written to the current output.
This macro has a slight variation on the standard syntax:
FOR <value-name> [ <separator-string> ]
or
FOR <value-name> (...Scheme expression list
The first argument must be the name of an AutoGen value. If there is
no value associated with the name, the FOR loop block is skipped
entirely. The scope of the FOR function extends to the
corresponding ENDFOR macro.
If there are any further arguments, 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 AutoGen Scheme Functions. 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 various substitutions ...[+
ENDFOR var+]
this will repeat the ... text with <number>+1 times. Each repetition,
except for the last, will have a comma various
substitutions ..., after it.
[+FOR var ",\n" +]
... text with various substitutions ...[+
ENDFOR var +]
This will do the same thing, but only for the index
values of var that have actually been defined.
Conditional block. Its arguments are evaluated (see section 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.
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 `IF', `FOR', `WHILE', and `CASE' and extending through the respective terminating macro functions.
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 simple 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 simple 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.
This macro selects a block of text by matching an expression
against the sample text expression evaluated in the CASE
macro. See section 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.
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.
Conditionally repeated block. Its arguments are evaluated (see section 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.
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 AutoGen Scheme Functions).
These functions allow you to logically "push" output files onto a stack and return to previous files by "pop"ing them back off. At the end of processing the template for a particular suffix (see section Format of the Pseudo Macro), all the files in the output stack are closed and popped off. Consequently, at the start of the processing of a template, there is only one output file on the stack. That file cannot be popped off.
There are also several functions for determining the output status. See section AutoGen Scheme Functions.
Go to the first, previous, next, last section, table of contents.