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.

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

The "apply code" selected determines the method of evaluating the expression. There are five apply codes, including the non-use of an apply code.

‘no apply code’

This is the most common expression type. Expressions of this sort come in three flavors:

‘<value-name>’

The result is the value of value-name, if defined. Otherwise it is the empty string.

‘<basic-expr>’

The result of the basic expression is the result of the full expression, See section Basic Expression.

‘<value-name> <basic-expr>’

If there is a defined value for value-name, then the basic-expr is evaluated. Otherwise, the result is the empty string.

‘% <value-name> <basic-expr>’

If 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` +]

This would cause the shell to evaluate "‘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.

‘? <value-name> <basic-expr-1> <basic-expr-2>’

Two basic-expr-s are required. If the value-name is defined, then the first basic-expr-1 is evaluated, otherwise basic-expr-2 is.

‘- <value-name> <basic-expr>’

Evaluate basic-expr only if value-name is not defined.

‘?% <value-name> <basic-expr-1> <basic-expr-2>’

This combines the functions of ‘?’ and ‘%’. If 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` +]

This would cause the shell to evaluate "‘cat $stumble’". If ‘fumble’ were not defined, then the result would be the name of our current directory.

3.3.2 Basic Expression

A basic expression can have one of the following forms:

‘'STRING'’

A single quoted string. Backslashes can be used to protect single quotes ('), 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"’

A double quoted string. This is a cooked text string as in C, except that they are not concatenated with adjacent strings. Evaluating "‘STRING’" will output STRING with all backslash sequences interpreted.

‘`STRING`’

A back quoted string. When this expression is evaluated, STRING is first interpreted as a cooked string (as in ‘"STRING"’) and evaluated as a shell expression by the AutoGen server shell. This expression is replaced by the ‘stdout’ output of the shell.

‘(STRING)’

A parenthesized expression. It will be passed to the Guile interpreter for evaluation and replaced by the resulting value. If there is a Scheme error in this expression, Guile 1.4 and Guile 1.6 will report the template line number where the error occurs. Guile 1.7 has lost this capability.

Guile has the capability of creating and manipulating variables that can be referenced later on in the template processing. If you define such a variable, it is invisible to AutoGen. To reference its value, you must use a Guile expression. For example,

[+ (define my-var "some-string-value") +]

can have that string inserted later, but only as in:

[+ (. my-var) +]

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 result of the last Guile expression evaluated.

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