Using macros

Chapter 9 Generation Reference Guide (GTL)

Using macros

Macros can be used to express template logic, and to loop on object collections. Each macro keyword must be preceded by a . (dot) character and has to be the first non blank character of a line. Make sure you also respect the macro syntax in terms of line breaks.

You define a macro inside a template, or a command entry.

There are three types of macros:

Block macros consist of a begin and an end keyword delimiting an input block over which the macro is applied. They have the following structure:

'.'<macro-name> ['(' <parameters> ')' ]
<macro-block-input>
'.'end<macro-name > [ '(' <tail> ')' ]

<tail> is an optional string constant appended to the generated text, if there is one.

Loop macros are used for iteration. At each iteration, a new scope is created. The template specified inside the block is translated successively with respect to the iteration scope.

'.'foreach_<macro-name> ['(' <parameters> [',' <head> [',' <tail>]] ')' ]
<complex-template>
'.'next [ '(' <separator> ')' ]

<head> and <tail> are both optional string constants. <head> is generated before, and <tail> is appended to the generated text, if there is one.

A <separator> may optionally be specified as an argument to the .next keyword, it is placed between non-empty evaluations of <complex-template>.

Simple macros are macros that hold on a single line.

Macro parameters delimiters
Macro parameters may be delimited by double quotes. The delimiters are required whenever the parameter value includes commas, braces, leading or trailing blanks. The escape sequence for double quotes inside a parameter value is \".

You can use the following macros:

Conditional macros

These macros are used for conditional generation. See if macro.

Loop / Iterative macros

These macros are used for iterating on object collections (see foreach_item macro) or on the lines (see foreach_line macro) or the parts (see foreach_part macro) of the result of the evaluation of the input template specified as the first argument to the macro. The break macro is used to break the loops (see break macro).

Assignment macros

These macros are used to define a local variable of object or value type as well as volatile attributes. See set_object macro, set_value macro, and unset macro.

Output & error reporting macros

These macros are used for communicating messages or warnings during translation. See log macro, warning macro, and error macro.

Command macros

These commands are used to embed VB script code inside a template (see vbscript macro), to launch executables (see execute_vbscript macro, and execute_command macro), and stop command execution (see abort_command macro). You can also use them for changing a directory (see change_dir macro) and creating a specified path (see create_path macro). These macros are only available in the context of the execution of a generic command.

Comment macros

These macros are used for inserting a comment in a template. See comment and // macro.

Formatting macros

These macros are used for transforming a text block in lowercase (see lowercase macro) or uppercase characters (see uppercase macro). They can also be used for converting names into code or code into names with a conversion table (see convert_name macro, and convert_code macro).

String manipulation macros

These macros are used for manipulating strings (replace, delete, define as unique) and add a header and a footer to a text block.

See replace macro, delete macro, unique macro, and block macro.

Miscellaneous macros

This collection and object macros return a collection of objects based on the specified scope and condition, see collection macro and object macro.

The bool macro is used to evaluate a condition, see bool macro.

The set_interactive_mode macro is used to define if the GTL execution must interact with the user or not, see set_interactive_mode macro.

The following sections provide more details on each macro.