Chapter 9 Generation Reference Guide (GTL)

GTL 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 and loop / iterative macros:
- .if macro
- .foreach_item macro – iterates on object collections
- .foreach_line macro – iterates on lines
- .foreach_part macro – iterates on parts
- .break macro – breaks the loop
Assignment macros - define a local variable of object or value type as well as volatile attributes:
Output and error reporting macros:
Command macros - only available in the context of the execution of a generic command:
- .vbscript macro - embed VB script code inside a template
- .execute_vbscript macro - launch vbscripts
- .execute_command macro - launch executables
- .abort_command macro - stop command execution
- .change_dir macro - changing a directory
- .create_path macro - creating a specified path
Formatting macros:
- .lowercase macro
- .uppercase macro
- .convert_name macro - converts names into codes
- .convert_code macro – converts codes into names
String manipulation macros:
- .replace macro
- .delete macro
- .unique macro
- .block macro - adds a header and a footer to a text block
Miscellaneous macros:
- .comment and .// macro - inserts a comment in a template
- .collection macro - returns a collection of objects based on the specified scope and condition
- .object macro - returns an object based on the specified scope and condition
- .bool macro - evaluates a condition
- .set_interactive_mode macro – defines whether the GTL execution must interact with the user