The templates are often organized in groups (template groups). It is a template group rather than a single template that the template engine (and hence the file generator) usually operates on. Each group corresponds to a single file to be generated.
Each group has a main (“top-level”) template. This template usually defines the structure of the file to be generated from this group. Name of the group is the name of its main template.
A template group is represented in the file system by a directory with the same name as the group. This directory should contain at least two files:
The file containing the main template of the group. This file has .tpl extension and the same name as the template (and the group).
The configuration file for the group. This file has .cfg extension and the same name as the group. The contents of this file are described below.
Each template from a group is stored in a file with .tpl extension and the same name as the template in the directory of the group.
For example, the templates considered in Section 3.3, “Joining values” could be organized as “GoodMorning” template group as follows in the file system:
GoodMorning // directory for "GoodMorning" template group
|
+- GoodMorning.cfg // configuration file for the group
+- GoodMorning.tpl // main template ("GoodMorning")
+- Person.tpl // "Person" template
Only the configuration file of a template group and .tpl files contained in the directory of this group are loaded by the template engine. All other files are ignored.
The configuration file for a template group has the same format as the configuration files defining the values of parameters referred to by the templates. The format is described in Section 5, “Parameters and “Value” Files”.
The following parameters are recognized by the template engine in the configuration file for a template group (all other parameters are ignored):
PH_BEGIN_MARKER
(optional) A character sequence that marks the beginning of each placeholder in the templates from the template group as well as in the template defined in FILE_PATH_TEMPLATE parameter (see below).
Default value: <$
PH_END_MARKER
(optional) A character sequence that marks the end of each placeholder in the templates from the template group as well as in the template defined in FILE_PATH_TEMPLATE parameter (see below).
Default value: $>
FILE_PATH_TEMPLATE(required) Template of the path to the file to be generated. This template must not refer to subtemplates, but it may refer to the parameters of the tests (default parameters, parameters defined for the test suite or for a particular group of tests).
For example, here is a sample template of the path to the test source file:
FILE_PATH_TEMPLATE = <$SUITE_ROOT_DIR$>/tests/<$T2C_FILE_NAME$>.cpp
When the file generator is about to create the resulting file for a template group, it evaluates the template from FILE_PATH_TEMPLATE parameter to obtain the path to that file. If some directories in the path do not exist at the moment, the file generator will attempt to create them.
Sometimes (for example, for debugging purposes) it can be useful to define this parameter without any placeholders, like this:
FILE_PATH_TEMPLATE = output.txt
This instructs the file generator to place the result to output.txt file in the current working directory.
FILE_PATH_TEMPLATE parameter must be defined in the configuration file for test_case template group too, even though it is not used there. You may specify any value for FILE_PATH_TEMPLATE in this case.
If a custom begin or end marker has been specified in the configuration file for the template group, it will affect not only the templates from this group but also the template in FILE_PATH_TEMPLATE parameter.
Example:
# Custom begin and end markers of placeholders in the templates.
PH_BEGIN_MARKER = $$
PH_END_MARKER = $$
# The template of the path to the file to be generated.
# Note the use of the custom markers ('$$') here.
FILE_PATH_TEMPLATE = some_dir/$$OUT_DIR$$/Good Morning.txt
A template may refer to other templates (subtemplates) from the same group. These templates may in turn refer to subtemplates of their own and so on. A template may refer to any number of subtemplates and any number of templates may refer to the same template. This allows to use the templates as the building blocks to factor out common parts of the generated file, etc. From this point of view, the templates are a bit similar to macros (preprocessor definitions, #define constructs) used in C source code, macro definitions processed by m4 tool, etc.
Currently, there is no way for a template to refer to a subtemplate from another group.
Avoid creating recursion in the template references. Here are two common examples of recursion:
Template “A” has a placeholder that refers to template “A”.
Template “A” has a placeholder that refers to template “B”, template “B” (or some other template “B” refers to, etc.) has a placeholder that refers to template “A”.
Currently, the template engine does not detect the recursion in the template references. If there is a recursion, the following is guaranteed though:
The template engine will neither hang nor crash, the evaluation of the group will complete (but it is undefined what the result will look like).
When the group is evaluated, each template will be evaluated no more than once.
Each template in a group must have a unique name. It is the name that is used to refer to this template from other templates in the group. The names are case sensitive.
The name of a template is a string of single-byte characters. It must not begin with a dot or a space and must consist only of characters listed below:
latin letters: 'A'..'Z', 'a'..'z' (character codes 0x41-0x5A, 0x61-0x7A)
digits: '0'..'9' (character codes 0x30-0x39)
space: ' ' (character code 0x20)
hyphen: '-' (character code 0x2D)
dot: '.' (character code 0x2E)
underscore: '_' (character code 0x5F)
In addition, the name must not end with “-t2c”.
If a template group is to be loaded from the file system, this may impose additional system-specific restrictions on the names of the templates. This is because the name of a template is the name of the corresponding file (without .tpl extension) in this case. In addition, the name of the main template of the group is the name of the directory where the group is located. For example, this may impose a restriction on the length of the name.
The following keywords have special meaning and must not be used as the names of templates or parameters:
ifelseendifWhen the group is evaluated, the template engine starts with the main template. It looks for the templates it refers to, processes these templates and their subtemplates recursively in a similar way and so on. If the template engine encounters a template that does not refer to any other templates (it may refer to parameters, though), the values of the template are prepared, that is, evaluation of the template is complete. The template engine continues until all the necessary templates are evaluated and finally, the main template is evaluated.
This process can be viewed as traversing a tree (a hierarchy) of the templates. The main template is the root node, the parameters and subtemplates it directly refers to are its child nodes. A child node may have children of its own, etc. The nodes representing the parameters are the leaf nodes of this tree. The template engine goes deep to these leaf nodes first and then back to the root evaluating the nodes in its path.
With this approach, only the templates needed to evaluate the main template are actually evaluated. Nevertheless, all the templates from the group are loaded when the group is loaded by the template engine including the ones that will not actually be used. In particular, syntax checking will be performed for each template in the group.