3.6 AutoGen Native Macros

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

This macro has scope through the ESAC macro. The scope is subdivided by SELECT macros. You must have at least one SELECT macro.

DEFINE

This macro has scope through the ENDDEF macro. The defined user macro can never be a block macro. This macro is extracted from the template before the template is processed. Consequently, you cannot select a definition based on context. You can, however, place them all at the end of the file.

FOR

This macro has scope through the ENDFOR macro.

IF

This macro has scope through the 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

This macro has the scope of the included file. It is a block macro in the sense that the included file must not contain any incomplete block macros.

WHILE

This macro has scope through the ENDWHILE macro.

3.6.1 AutoGen Macro Syntax

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:

1. 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 one of these two:

   <user-macro-name> [ <name> [ = <expression> ] ... ] INVOKE <name-expression> [ <name> [ = <expression> ] ... ]

2. AutoGen FOR macros must be in one of three forms:

   FOR <name> [ <separator-string> ] FOR <name> (...Scheme expression list) FOR <name> IN <string-entry> [ ... ]

   where:

   ‘<name>’

   must be a simple name.

   ‘<separator-string>’

   is inserted between copies of the enclosed block. Do not try to use “IN” as your separator string. It won’t work.

   ‘<string-entry>’

   is an entry in a list of strings. “<name>” is assigned each value from the “IN” list before expanding the FOR block.

   ‘(...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 AutoGen Scheme Functions)

   The first two forms iterate over the FOR block if <name> is found in the AutoGen values. The last form will create the AutoGen value named <name>.

3. AutoGen DEFINE macros must be followed by a simple name. Anything after that is ignored. Consequently, that “comment space” may be used to document any named values the macro expects to have set up as arguments. See section DEFINE - Define a user AutoGen macro.
4. The AutoGen COMMENT, ELSE, ESAC and the END* macros take no arguments and ignore everything after the macro name (e.g. see COMMENT - A block of comment to be ignored)

3.6.2 BREAK - Leave a FOR or WHILE macro

This will unwind the loop context and resume after ENDFOR/ENDWHILE. Note that unless this happens to be the last iteration anyway, the (last-for?) function will never yield "#t".

3.6.3 CASE - Select one of several template blocks

The arguments are evaluated and converted to a string, if necessary. A simple name will be interpreted as an AutoGen value name and its value will be used by the SELECT macros (see the example below and the expression evaluation function, see section EXPR - Evaluate and emit an Expression). The scope of the macro is up to the matching ESAC macro. 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 matches may be performed, plus an "always true", "true if the AutoGen value was found", and "true if no AutoGen value was found" matches. The codes for the nineteen match macros are formed as follows:

1. Must the match start matching from the beginning of the string? If not, then the match macro code starts with an asterisk (*).
2. Must the match finish matching at the end of the string? If not, then the match macro code ends with an asterisk (*).
3. Is the match a pattern match or a string comparison? If a comparison, use an equal sign (=). If a pattern match, use a tilde (~).
4. Is the match case sensitive? If alphabetic case is important, double the tilde or equal sign.
5. Do you need a default match when none of the others match? Use a single asterisk (*).
6. Do you need to distinguish between an empty string value and a value that was not found? Use the non-existence test (!E) before testing a full match against an empty string (== ''). There is also an existence test (+E), more for symmetry than for practical use.

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
[+ !E             +]not exists - matches if no AutoGen value found
[+ ==   ""        +]expression yielded a zero-length string
[+ +E             +]exists - matches if there is any value result
[+ *              +]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. They are documented in this texi doc as “string-*?” predicates (see section Common Scheme Functions).

3.6.4 COMMENT - A block of comment to be ignored

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.

[+ # say what you want, but no '+' before any ']' chars +]

3.6.5 CONTINUE - Skip to end of a FOR or WHILE macro.

This will skip the remainder of the loop and start the next.

3.6.6 DEBUG - Print debug message to trace output

If the tracing level is at "debug-message" or above (see autogen trace), this macro prints a debug message to trace output. This message is not evaluated. This macro can also be used to set useful debugger breakpoints. By inserting [+DEBUG n+] into your template, you can set a debugger breakpoint on the #n case element below (in the AutoGen source) and step through the processing of interesting parts of your template.

To be useful, you have to have access to the source tree where autogen was built and the template being processed. The definitions are also helpful, but not crucial. Please contact the author if you think you might actually want to use this.

3.6.7 DEFINE - Define a user AutoGen macro

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 (see section INVOKE - Invoke a User Defined Macro) 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.

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 Macro Expression Syntax.

The resulting definitions are handled much like regular definitions, except:

1. The values may not be compound. That is, they may not contain nested name/value pairs.
2. The bindings go away when the macro is complete.
3. The name/value pairs are separated by whitespace instead of semi-colons.
4. Sequences of strings are not concatenated.

NB: The macro is extracted from the template as the template is scanned. You cannot conditionally define a macro by enclosing it in an IF/ENDIF (see section IF - Conditionally Emit a Template Block) macro pair. If you need to dynamically select the format of a DEFINEd macro, then put the flavors into separate template files that simply define macros. INCLUDE (see section INCLUDE - Read in and emit a template block) the appropriate template when you have computed which you need.

Due to this, it is acceptable and even a good idea to place all the DEFINE macros at the end of the template. That puts the main body of the template at the beginning of the file.

3.6.8 ELIF - Alternate Conditional Template Block

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.

3.6.9 ELSE - Alternate 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.

3.6.10 ENDDEF - Ends a macro definition.

This macro ends the DEFINE function template block. For a complete description See section DEFINE - Define a user AutoGen macro.

3.6.11 ENDFOR - Terminates the 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.

3.6.12 ENDIF - Terminate the IF Template Block

This macro ends the IF function template block. For a complete description See section IF - Conditionally Emit a Template Block.

3.6.13 ENDWHILE - Terminate the WHILE Template Block

This macro ends the WHILE function template block. For a complete description See section WHILE - Conditionally loop over a Template Block.

3.6.14 ESAC - Terminate the CASE Template Block

This macro ends the CASE function template block. For a complete description, See section CASE - Select one of several template blocks.

3.6.15 EXPR - Evaluate and emit an Expression

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.

3.6.16 FOR - Emit a template block multiple times

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 "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 ‘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 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 found-for? (see section ‘found-for?’ - is current index in list?) or other 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? for-index, and found-for? functions are disabled outside of the range of a FOR block.

Also: the <value-name> must be a single level name, not a compound name (see section Naming a value).

[+FOR var (for-from 0) (for-to <number>) (for-sep ",") +]
... text with various substitutions ...[+
ENDFOR var+]

this will repeat the ... text with various substitutions ... <number>+1 times. Each repetition, except for the last, will have a comma , 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.

3.6.17 IF - Conditionally Emit a Template Block

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.

3.6.18 INCLUDE - Read in and emit a template block

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.

3.6.19 INVOKE - Invoke a User Defined Macro

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.

3.6.20 RETURN - Leave an INVOKE-d (DEFINE) macro

This will unwind looping constructs inside of a DEFINE-d macro and return to the invocation point. The output files and diversions are left alone. This means it is unwise to start diversions in a DEFINEd macro and RETURN from it before you have handled the diversion. Unless you are careful. Here is some rope for you. Please be careful using it.

3.6.21 SELECT - Selection block for CASE function

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 19 match operators described in the CASE macro description.

3.6.22 UNKNOWN - Either a user macro or a value name.

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.

3.6.23 WHILE - Conditionally loop over a Template Block

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.

3.6.24 Inserting text from a shell script

If the text between the start and end macro markers starts with an opening curly brace (’{’) or is surrounded by back quotes (’`’), then the text is handed off to the server shell for evaluation. The output to standard out is inserted into the document. If the text starts with the curly brace, all the text is passed off as is to the shell. If surrounded by back quotes, then the string is “cooked” before being handed off to the shell.

3.6.25 Inserting text from a scheme script

If the text between the start and end macro markers starts with a semi-colon or an opening parenthesis, all the text is handed off to the Guile/scheme processor. If the last result is text or a number, it is added (as text) to the output document.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.