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 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. Scheme expressions may be inserted in order to make configuration changes before template processing begins. 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.

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