3. Template File

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.

3.1 Format of the Pseudo Macro

The pseudo macro is used to tell AutoGen how to process a template. It tells autogen:

1. The start macro marker. It consists of punctuation characters used to demarcate the start of a macro. It may be up to seven characters long and must be the first non-whitespace characters in the file.

   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.

2. That start marker must be immediately followed by the identifier strings "AutoGen5" and then "template", though capitalization is not important.

The next several components may be intermingled:

1. Zero, one or more suffix specifications tell AutoGen how many times to process the template file. No suffix specifications mean that it is to be processed once and that the generated text is to be written to `stdout'. The current suffix for each pass can be determined with the (suffix) scheme function (see section `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 formatting specification. That specification may be either an ordinary sequence of file name characters with zero, one or two "%s" formatting sequences in it, or else it may be a Scheme expression that, when evaluated, produces such a string. The Scheme result may not be empty. The two string arguments allowed for that string are 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 the suffix begins with one of these three latter characters and a formatting string is not specified, then that character is presumed to be the suffix separator. Otherwise, without a specified format string, a single period will separate the suffix from the base name in constructing the output file name.

2. Comments: blank lines, lines starting with a hash mark [#]), and edit mode comments (text between pairs of -*- strings).
3. Some scheme expressions may be inserted in order to make configuration changes before template processing begins. "before template processing begins" means that there is no current output file, no current suffix and, basically, none of the AutoGen specific functions (see section AutoGen Scheme Functions) may be invoked.

   It is used, for example, 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.

   (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 `extract' - extract text from another file).

   (shellf "mv -f %1$s.c %1$s.sav" (base-name))

After these must come the end macro marker:

1. The punctuation characters used to demarcate the end of a macro. Like the start marker, it must consist of seven or fewer punctuation characters.

The ending macro marker has a few constraints on its content. Some of them are just advisory, though. There is no special check for advisory restrictions.

• It must not begin with a POSIX file name character (hyphen -, underscore _ or period .), the backslash (\) or open parenthesis ((). These are used to identify a suffix specification, indicate Scheme code and trim white space.
• If it begins with an equal sign, then it must be separated from any suffix specification by white space.
• The closing marker may not begin with an open parenthesis, as that is used to enclose a scheme expression.
• It cannot begin with a backslash, as that is used to indicate white space trimming after the end macro mark. If, in the body of the template, you put the backslash character (\) before the end macro mark, then any white space characters after the mark and through the newline character are trimmed.
• It is also helpful to avoid using the comment marker (#). It might be seen as a comment within the pseudo macro.
• You should avoid using any of the quote characters double, single or back-quote. It won't confuse AutoGen, but it might well confuse you and/or your editor.

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 pseudo macro might 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.

3.2 Naming a value

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. :-)

3.3 Macro Expression Syntax

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 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 DEFINE - Define a user AutoGen macro.