Template usage

TExpressive can be used on all difficulty levels, from simple insert-data-here templates to complex text and data processing applications. Here we start with the basics of using TExpressive templates.

When you use TExpressive you start with a template. The template itself is no more than a textual file with some pieces of "script" sprinkled in. These scripts control where TExpressive will perform some actions on your template to create the final resulting file. Scripts are the dynamic part of your template. In scrips you add "functions" that each perform a certain function. Scripts are basically written in the format:

<#FunctionName Argument:"Value"#>

where <# starts the script, "FunctionName" stands for the name of the function to use, "Argument" stands for an argument the function takes which supplies information to the function, and #> ends the script again.

Example 1

To make things more tangible, we start with a simple example:

The sum of 1 and 2 is: <#Sum Value:"1" Value:"2"#>

When you save this to a template file and process it with TExpressive, the resulting file will contain:

The sum of 1 and 2 is: 3

The first part of the line starts with normal text, so this is used as-is in the result. Then the script will be processed by TExpressive, which only contains the "Sum" function. The result of this function is the value "3", so in stead of the script with the "Sum" function, TExpressive writes out the value 3.

Example 2

A more useable example:

<#Set Param:"PetName" To:"Woezel"#>
My pet's name is: <#Use Param:"PetName"#>

When this get's processed with TExpressive, the result will be:


My pet's name is: Woezel

There are a few points of interest in the above example;

The above example contains two scripts; one contains the "Set" function and the other contains the "Use" function.
There is a piece of regular text in between the scripts, which will not be processed and will be used as-is in the result.
The result starts with an empty line.

The first script will be processed first, then the text in between the scripts is added to the result, and finally the second script is processed and it's output is again added to the result.

These two scripts use the functions "Set" and "Use" in conjunction. The "Set" function puts a value in a parameter. You can think of parameters as drawers in a file cabinet; each drawer is labeled with a name, and can contain information. In the above example, the "Set" function creates a drawer with the name "PetName" on it, and stores the information "Woezel" in it. Parameters can in turn be used again by other functions, like the "Use" in this example (which just writes out the value of the parameter).

The "Set" function doesn't leave a trace in the final result, and since this is the only function in the first script the first script also doesn't generate any output. Since the first script was the only content on the first line, the first line remains blank in the result. After the first script comes a piece of text which is used as-is, so that text is then added to the result. After the text comes the script with the "Use" function, which searches for the drawer named "PetName" and writes out it's information.

When you do not want the empty first line in the final result, you should contruct the template differently, e.g. like this:

<#
  Set Param:"PetName" To:"Woezel"
#>My pet's name is: <#Use Param:"PetName"#>

This gives the result:

My pet's name is: Woezel

Note that it's perfectly OK to add spacing and even line breaks between parts of a function in a script; they will not influence the outcome of the function and script. So, by putting the actual function content (the name "Set" and the argument "To") on a separate line and indenting it, it stands out more that a TExpressive function is located there. And by starting the text right after the end of the first script (by putting the word "My" right after the script's ending "#>"), the first word will start at the start of the template's result.

Example 3

A final more elaborate example:

<#
  Set Param:"AnimalName" To:"Cat";
  Set Param:"FileName" To:(
    Use Param:"AnimalName"#>Name.txt<#
  );
  Set Param:"PetName" To:(
    Input File:FileName
  )
#>My pet's name is: <#Use Param:"PetName"#>

Add to that a file named "CatName.txt" with the contents:

Woezel

Then process it with TExpressive, and the result will again be:

My pet's name is: Woezel

In this example there are three "Set" functions in the first script. In stead of opening and closing a new script for every "Set", we just place a ";" in between them which has the same effect.

The first "Set" function works like the one in the previous example; it sets the parameter called "AnimalName" to the value "Cat".

The second "Set" in turn sets the parameter "FileName", but this time the value to use is the result of an in-line piece of TExpressive script. Wherever you specify a value to use for a function argument (by specifying that value within quotes), you can also specify a piece of in-line TExpressive script by using "(" and ")" instead, and placing the in-line script in between. In this case the in-line script first writes out the value of the parameter "AnimalName" (which is set to "Cat"), and appends the text "Name.txt" to that. This in-line script thus results in the overal result "CatName.txt", which is then stored in the parameter called "FileName".

The third "Set" works with an in-line script as well. It uses the "Input" function, which brings in the content of another file. The filename of the file to use is specified via the argument "File". Here the third method of specifying information to a function is used - supplying the value of a parameter. When specifying a piece of text you can give it in quotes, like "some piece of text". When specifying an in-line TExpressive script fragment you can use the format (in-line script). And when using a parameter value you can use it's name directly like ParameterName. So, since the parameter "FileName" is set to "CatName.txt", the "Input" function will read the content of that file, which in turn holds the text "Woezel".

Note that while the "Input" function used the name of the parameter to use without quotes, the "Set" function did not. This is because the "Set" function asks for the name of the parameter to set, which is in fact just a piece of text.

More information

This should bring you up to speed with how TExpressive templates and scripts are contructed. More in-depth information on the exact language syntax can be seen on the Language syntax help page. A complete list of all available functions and how to use them can be found on the Available functions help page. When you start to create more complex templates it might also be time to consult the Creating script fragments help page, which shows you how to make common template parts even more common and how to create your own functions.

Sitemap

Information