First, let us prepare the data necessary for this example.

Create a directory named Greetings. This directory will represent a template group with the given name.

Create two files in that directory, Greetings.tpl and Greetings.cfg. The former file will contain the main (top-level) template of the group. The latter will define special parameters used when generating the output file, the most important of which is the path to that output file.

Greetings/Greetings.tpl should contain the following:

Someone says:
<$Salutation$>, <$Subject$>!

<$Salutation$> and <$Subject$> are special placeholders with respective names that will me replaced by the actual values of Salutation and Subject parameters by mist_engine. The rest of the contents of Greetings.tpl will be copied verbatim (including spaces, newlines, etc.) to the output file.

Suppose we want to have the resulting text saved in out.txt in the current directory. Then Greetings/Greetings.cfg should contain the following:

# Template of the path to the output file
FILE_PATH_TEMPLATE = out.txt

The line beginning with '#' is a comment and will be ignored. The next line assigns the value “out.txt” to the special parameter FILE_PATH_TEMPLATE.

We are done with the template group for now.

Let us then define the values of Salutation and Subject parameters. Create file values.in (you may use a different name if you want to) with the following contents:

Salutation = Hello
Subject = World

Here, Salutation parameter is assigned the value “Hello” and Subject parameter - the value “World”.

If no value is assigned to a parameter, its value is assumed to be an empty string.

Now that we have a template group and the values to stick in the templates, we can execute mist_engine tool to produce the resulting file. The path to the directory of the template group and the path to the file with parameter values are passed to mist_engine as the arguments.

mist_engine ./Greetings ./values.in

If everything is OK, out.txt file should appear in the current directory with the following contents:

Someone says:
Hello, World!

If we now change values.in to contain the following

Salutation = Hail to you
Subject = Dr. Freeman

and execute mist_engine again, out.txt will contain the following:

Someone says:
Hail to you, Dr. Freeman!

As you can see, the overall structure of the output file (defined by the template) remains the same, only the “replaceable parts” (designated by <$Salutation$> and <$Subject$>) differ.

Each parameter that can be referred to by a template may be assigned more than one value. For example, let values.in file now have the following contents:

Salutation = Hello
Subject = World

Salutation = Hail to you
Subject = Dr. Freeman

Salutation = You are the guy who owes me a beer
Subject = Barney

The order in which the values are assigned to a particular parameter is important. For example, the first value of Salutation parameter (“Hello”) corresponds to the first value of Subject parameter (“World”) and so on.

The values for different parameters, however, may go in any order. For example, values.in containing the following is equivalent to the one above:

Salutation = Hello
Salutation = Hail to you
Salutation = You are the guy who owes me a beer

Subject = World
Subject = Dr. Freeman
Subject = Barney

If a template refers to a multi-valued parameter like these and does not join the values as described below, the template itself will have more than one value. The first value of the template will be created using the first values of the parameters and the templates it refers to, the second one - using the second ones, etc. If not enough values are assigned to a particular parameter, its last value will be used (see Section 3, “Templates for Output Files” for details).

To see, how multi-valued parameters are processed, we need to make some changes in the template group first.

Create Greetings/Hello.tpl with the following contents:

<$Salutation$>, <$Subject$>!

That is, you make this a separate template, a subtemplate, actually. Other templates from “Greetings” template group may refer to this subtemplate the same way as if it were a parameter.

Change Greetings/Greetings.tpl to the following:

Someone says:
<$Hello$>

“Greetings” template now refers to “Hello” subtemplate. As Salutation and Subject parameters have 3 values each, “Hello” subtemplate and hence “Greetings” template will also have 3 values. If you now execute mist_engine as above, it will report this as an error because unlike MiST Engine API functions, the command line tool expects the top-level template to have only one value.

Let us change Greetings/Greetings.tpl a bit:

Someone says:
<$Hello : join(\n)$>

Here, we instruct MiST Engine to join the values of “Hello” subtemplate using a newline character ('\n') between each two adjacent values (see also Section 3.3, “Joining values”).

If you now execute mist_engine ./Greetings ./values.in, no error will be reported and out.txt file will contain the following:

Someone says:
Hello, World!
Hail to you, Dr. Freeman!
You are the guy who owes me a beer, Barney!

Multi-valued parameters and joining allow to create list-like structures in the output files, i.e. the sequences of elements of some kind, like the phrases in the example above.

Sometimes it can be necessary to use a default value for a parameter in case its current value is empty. Consider the following example of values.in file:

Salutation = Hello
Subject = 

Salutation = Hail to you
Subject = Dr. Freeman

Salutation = You are the guy who owes me a beer
Subject = 

The first and the last values of Subject parameter are empty. If you do not change the templates and execute mist_engine tool now, you will get the following in the output file:

Someone says:
Hello, !
Hail to you, Dr. Freeman!
You are the guy who owes me a beer, !

This does not really look very neat. Let us use “stranger” instead of the value of Subject parameter if this values is empty. Change Hello template as follows:

<$Salutation$>, <$if Subject$><$Subject$><$else$>stranger<$endif$>!

That is, if the current value of Subject parameter is not empty, it will be used there. If not, “stranger” will be used instead.

The result will now be as follows:

Someone says:
Hello, stranger!
Hail to you, Dr. Freeman!
You are the guy who owes me a beer, stranger!

Conditional constructs in the templates are described in detail in Section 3.4, “Conditionals”.

In some cases, it can be necessary to determine if a parameter has at least one non-empty value (or, equivalently, if the concatenation of all its values is not an empty string). concat-expressions in the conditional constructs allow to do this (see Section 3.4, “Conditionals” for details).

Let us change Greetings template as follows:

Someone says<$if concat(Salutation)$>:
<$Hello : join(\n)$><$else$> nothing.<$endif$>

Suppose first that values.in file is as follows (same as above):

Salutation = Hello
Subject = 

Salutation = Hail to you
Subject = Dr. Freeman

Salutation = You are the guy who owes me a beer
Subject = 

The result will also be the same as above in this case, namely:

Someone says:
Hello, stranger!
Hail to you, Dr. Freeman!
You are the guy who owes me a beer, stranger!

This is because Salutation parameter has at least one non-empty value (actually, it has 3 non-empty values but this does not matter here). But if you now remove (or comment out) all assignments of values to this parameter from values.in, the result will be as follows:

Someone says nothing.