Perl Template Toolkit Basics

PCS Howtos

Basics of Using the Perl Template Toolkit

This page will try to cover some of the real basics of using the Perl Template Toolkit package (TT for short). I intend to discuss some basic syntax, give examples of some of the more commonly used commands, and a few tips. This is not intended to be a tutorial or reference for the Perl Template Toolkit. For more information, look at the following references:

Basic Syntax

Basically, TT processes a file by reading lines in and spitting it back out verbatim, until it encounters a start tag. The start tag tells it to start looking for and interpretting TT commands, until a close tag occurs and it goes back to echoing the input verbatim, until another start tag is encountered, and so on. (Actually, it is possible to run TT in such a way that some processing is done even outside the start and close tags, but in general that is not done in Physics Dept.)

The basic start tag is [%, but you may also encounter [%#, [%+, and [%-. The basic closing tag is %], with variants +%] and -%].

The [% start tag starts a comment block. Everything from the start tag to the next closing tag (any variant) is considered a comment, and is ignored by TT and is not echoed to the output.

The '+' and '-' and vanilla variants are all pretty much the same, with the only difference being how whitespace before or after the tag is treated. The '+' variants retain whitespace before the opening tag or after the closing tag, the '-' variants omit that same whitespace. The default vanilla version ([% or %]), can behave either way depending on how the module is called; in Physics code they generally behave like the '+' variants. For most purposes, the vanilla variants are fine. Also note that you can mix and match variants on the starting and closing tags, e.g.

[%+ INCLUDE -%]
is perfectly valid.

When inside the TT blocks, a # symbol means that everything after it, until the end of the line, is a comment. Note that [%# is different; when there is no space between the start tag and the # symbol, the entire template language block is treated as a comment.

Commands in the TT block are terminated by semi-colon, and can span multiple lines. The last command before a closing tag does not require the final semi-colon (although can have one); it is mandatory for all other commands (including in a few places you might be inclined to leave it out, e.g. after the ELSE command). In general, extra whitespace is not a problem.

Standard TT commands are generally all capital letters, although you will often see macros, variables, object methods on these variables, etc. which do not follow that format. TT is case sensitive.

You can use either single or double quotes to quote literals, and string literals must be quoted.

Some macros take arguments; these can be either positional and/or named depending on the macro, or both. A positional argument looks like a standard C language function call, e.g. something like

[% myfunct(1,2,"abc") %]
where 1, 2, and abc are all positional args. Which variables they are assigned to depends on the way the macro was defined.

Named arguments look like

[% myfunct(name="abc",version=1,copy=2) %]
where the assignment of the arguments to the variables name, version, and copy variables is explicit. It is also often possible to mix notations in a single call, e.g.
[% myfunct(1,name="abc",copy=2); %]

When processing a block (via INCLUDE or PROCESS) variables from the calling block can generally be accessed. You can also do a temporary variable assignment (sort of an argument list) via name like [% INCLUDE myblock version=1, name="abc"; %].

One of the simplest and commonest TT commands is GET, which just evaluates the argument to the command and outputs it. Indeed, it is so common, that the GET keyword can be omitted, so basically if there is just an expression on the line, e.g. a string literal or a variable, it is evaluated and printed.

TT also has a variable assignment mechanism, although is actually probably a bit more like an output redirection. Any command can be preceded by a variable name and an equal sign, and the output of the command will be suppressed and assigned to that variable instead (This is actually the SET command, but the command word is optional.) When combined with the GET command (especially when both keywords are omitted), you get something that looks like a typical C assignment statement. E.g.

[% x = y + 1; %]

Note that in addition to variables defined the variable assignment mechanism above, the perl script invoking the template can (and often will) provide variables, usually perl objects. Data members and methods can be accessed via the dot notation, e.g.

[% x.result = obj.fancyMethod(5,4,7); %]
All variables are actually scalars or references (including blessed references or objects), and indeed even the scalars are really objects, and have "virtual" methods available on them. Hash and array dereferencing is also done with the dot notation, although dereferencing a variable element in the hash or array requires a dollar sign ($) before the variable name, e.g.
[% x=[1,2,3]; y=2; z=x.$y; a=x.1;
s1={};"0000ff";; b="blue"; s3=s2.$b; %]

Some Common TT Commands

Some Hints/Tricks/Workarounds

The following is a short list of hints and tricks for working with TT that I have found useful:

  1. Use postfix conditionals with care (or not at all), especially with SET command. TT allows statements like
    [% GET x+y/z IF z > 0; %]
    This is usually fine with simple (or implicit) GETs like above, but can cause problems with SET (explicit or implicit) due to issues with order of operations. (TT applies the IF to what is right of the equal sign, not to the assignment).
  2. Break you TT blocks into small, logical units, even if just exitting and re-entering TT blocks. TT's error mechanism often cannot isolate a problem more finely than the lines of the block it is in (and sometimes not even that well). Smaller blocks, fewer lines where the problem can be.
  3. Use whitespace in expressions. TT seems to like whitespace between operators in mathematical, etc. expressions. It seems to digest better.
  4. Avoid complex expressions (e.g. more than one term?) inside of arguments to methods, functions, or macros. These seem to confuse TT, so use a temp variable. E.g. instead of
    [% obj.set_result( a + 3 * b ); %]
    do something like
    [% tmp= a + 3 * b; obj.set_result(tmp); %]

Main Physics Dept site Main UMD site

Valid HTML 4.01! Valid CSS!