Control macros are used to control the processing and formatting of the templates. The basic types of control macro include:
- The list macro, for generating multiple element features, such as attributes and operations
- The branching macros, which form if-then-else constructs to conditionally execute parts of a template
- The PI macro, which takes effect from the next non-empty line
- A PI function macro that enables setting PI to a variable and adds the ability to set the PI that is generated before the next line
- The PI macro for formatting new lines in the output
- The synchronization macros.
In general, control macros are named according to Camel casing.
The list macro is used to generate multiple elements. The basic structure is:
%list=<TemplateName> @separator=<string> @indent=<string> [<conditions>]%
where <string> is a double-quoted literal string and <TemplateName> can be one of the following template names:
- Custom Template (custom templates enable you to define your own templates; for more information see Custom Templates).
<conditions> is optional and appears the same as the conditions for if and elseIf statements.
%list="Attribute" @separator="\n" @indent=" "%
The separator attribute, denoted above by @separator, specifies the space that should be used between the list items. This excludes the last item in the list.
The indent attribute, denoted by @indent, specifies the space by which each line in the generated output should be indented.
The above example would output the result of processing the Attribute template, for each attribute element of the Class in scope. The resultant list would separate its items with a single new line and indent them two spaces respectively. If the Class in scope had any stereotyped attributes, they would be generated using the appropriately specialized template.
There are some special cases to consider when using the list macro:
- If the Attribute template is used as an argument to the list macro, this also generates attributes derived from associations by executing the appropriate LinkedAttribute template
- If the ClassBase template is used as an argument to the list macro, this also generates Class bases derived from links in the model by executing the appropriate LinkedClassBase template
- If the ClassInterface template is used as an argument to the list macro, this also generates Class bases derived from links in the model by executing the appropriate LinkedClassInterface template
- If InnerClass or InnerClassImpl is used as an argument to the list macro, these Classes are generated using the Class and ClassImpl templates respectively. These arguments tell Enterprise Architect that it should process the templates based on the inner Classes of the Class in scope.
Branching (if-then-else Constructs)
The CTF supports a limited form of branching through the following macros:
The basic structure of the if and elseIf macros is:
%if <test> <operator> <test>%
where <operator> can be one of:
and <test> can be one of:
- a string literal, enclosed within double quotation marks
- a direct substitution macro, without the enclosing percent signs
- a variable reference.
Branches can be nested, and multiple conditions can be specified using one of:
When specifying multiple conditions, and and or have the same order of precedence, and conditions are processed left to right.
The endif or endTemplate macros must be used to signify the end of a branch. In addition, the endTemplate macro causes the template to return immediately, if the corresponding branch is being executed.
%if elemType == "Interface"%
$bases=%list="ClassBase" @separator=", "%
$interfaces=%list="ClassInterface" @separator=", "%
%if $bases != "" and $interfaces != ""%
: $bases, $interfaces
%elseIf $bases != ""%
%elseIf $interfaces != ""%
There are two primary means of generating whitespace from the templates:
- Explicitly using the newline, space and tab characters (\n, ,\t) as part of Literal Text
- Using the PI macro to format lines in the template that result in non-empty substitutions in the output.
By default, each template line that generates a non-empty substitution also results in a newline being produced in the output. This behavior can be changed through the PI macro.
To demonstrate the use of the PI macro, consider the default C# Operation template:
%opTag:"unsafe"=="true" ? "unsafe" : ""%
%opTag:"new"=="true" ? "new" : ""%
%opAbstract=="T" ? "abstract" : ""%
%opConst=="T" ? "sealed" : ""%
%opStatic=="T" ? "static" : ""%
%opTag:"extern"=="true" ? "extern" : ""%
%opTag:"delegate"=="true" ? "delegate" : ""%
%opTag:"override"=="true" ? "override" : ""%
%opTag:"virtual"=="true" ? "virtual" : ""%
%opReturnType%%opReturnArray=="T" ? "" : ""%
%opStereotype=="operator" ? "operator" : ""%
%opName%(%list="Parameter" @separator=", "%)
Default PI is \n, so any attributes would be on their own line
Blank lines have no effect on the output
Set the PI, so keywords are separated by a space
Any keyword that does not apply - that is, the macro produces an empty result - does not result in a space
Only one space is generated for this line
The final line in the template does not generate a space
In the above example macros for the various keywords are to be arranged vertically for readability. In the output, however, each relevant keyword is to be separated by a single space. This is achieved by the line:
Notice how you do not specify the space between each of the possible keywords. This space is already implied by setting the PI to a single space. Essentially the PI acts as a convenience mechanism for formatting the output from within the templates.
The structure for setting the processing instruction is:
where <value> can be a literal string enclosed by double quotes.
The following points apply to the PI macro:
- The value of the PI is not accessed explicitly
- Only template lines that result in a non-empty substitution cause the PI to be generated
- The last non-empty template line does not cause the PI to be generated
- The PI is not appended to the last substitution, regardless of which template line caused that substitution.
The synchronization macros are used to provide formatting hints to Enterprise Architect when inserting new sections into the source code, during forward synchronization. The values for synchronization macros must be set in the File templates.
The structure for setting synchronization macros is:
where <name> can be one of the macros listed below and <value> is a literal string enclosed by double quotes.
Space to append to a new Class note. Default value: \n.
Space to append to a new attribute note. Default value: \n.
Space to append to a new operation note. Default value: \n.
Space to append to a new operation body. Default value: \n.
Indent applied to Classes within non-global namespaces. Default value: \t.