Control macros are used to control the processing and formatting of the templates. The basic types of control macros include:
| · | The list macro, for generating multiple elements, such as attributes and operations |
| · | The branching macros, which form if-then-else constructs to conditionally execute parts of a template |
| · | The PI macro takes effect from the next non-empty line |
| · | A PI function macro is available 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.
Lists
The list 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:
| · | Namespace |
| · | Class |
| · | ClassImpl |
| · | Attribute |
| · | InnerClass |
| · | InnerClassImpl |
| · | Operation |
| · | OperationImpl |
| · | Parameter |
| · | ClassBase |
| · | ClassInterface |
| · | 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.
Example:
%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:
| · | if |
| · | elseIf |
| · | endIf |
| · | endTemplate |
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:
| · | and |
| · | or. |
Note: 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.
Example:
%if elemType == "Interface"%
;
%else%
%OperationBody%
%endIf%
Example:
$bases=%list="ClassBase" @separator=", "%
$interfaces=%list="ClassInterface" @separator=", "%
%if $bases != "" and $interfaces != ""%
: $bases, $interfaces
%elseIf $bases != ""%
: $bases
%elseIf $interfaces != ""%
: $interfaces
%endIf%
The PI Macro
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:"Attribute"%
%PI=" "% %opTag:"unsafe"=="true" ? "unsafe" : ""% %CONVERT_SCOPE(opScope)% %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, ie. 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 we want to arrange macros for the various keywords vertically for readability. In the output, however, we want each relevant keyword to be separated by a single space. This is achieved by the line:
%PI=" "%
Notice how we 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:
%PI=<value>%
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
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:
%<name>=<value>%
where <name> can be one of the macros listed below and <value> is a literal string enclosed by double quotes.
Macro Name |
Description |
synchNewClassNotesSpace |
Space to append to a new class note. Default value: \n. |
synchNewAttributeNotesSpace |
Space to append to a new attribute note. Default value: \n. |
synchNewOperationNotesSpace |
Space to append to a new operation note. Default value: \n. |
synchNewOperationBodySpace |
Space to append to a new operation body. Default value: \n. |
synchNamespaceBodyIndent |
Indent applied to classes within non-global namespaces. Default value: \t. |