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:

• The Official Template Toolkit Documentation
• O'Reilly's book on the Template Toolkit
• Randal Schwartz' column on TT for Linux Mag
• A lot of information is available in the Perldoc commands, e.g. perldoc Template::Manual::Intro

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.

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

Named arguments look like

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.

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.

Some Common TT Commands

• GET expression : The expression is evaluated and printed. The GET keyword is usually omitted. Example
  [% "The answer is "; 3+4; GET "\n"; %]
  (note that this is 3 'GET' statements, with only the last one explicitly given, and it needn't have been).
• SET var = COMMAND: The command is evaluated and the output is assigned to the named variable. COMMAND can be any TT command. Note: This does not work well with postfix conditional, due to order of operations, as you will generally interpret something like
  [% x=1 IF y==2; %]
  to assign 1 to x only if y is 2, and do nothing otherwise. TT interprets as assign to x the result of 1 IF y==2, which returns 1 or nil depending on y. So basically, avoid the postfix conditional clauses.
• DEFAULT var = expression If the named variable is not defined or not true (in the Perlish sense), the expression is evaluated and assigned to the variable. Multiple variables and expressions can be given in same command, separated by whitespace.
• INSERT file The file or block is inserted at the current position. No template processing of file is done.
• INCLUDE file The file or block is inserted at the current position. The file is run through the template processor, and has access to all current variables (plus any temporary variable assignments given on command line). However, the variables are provided as local copies, so changes in the included block do not propagate back up. In particular, any macros defined in the block do not affect the calling block.
• PROCESS file Basically the same as INCLUDE, but the variables are not localized first, so changes to variables made in the included block propagate back out to the calling block. In particular, if the included block contains macro definitions, these are now defined for the calling block.
• BLOCK allows one to create named or anonymous blocks in the same file. These can be included or processed, or can use with set for here document type of effect, e.g.
  [% tmp = BLOCK %]
This is some long text
More text
And more
[% END %]
  It must be terminated with an END command.
• IF, ELSIF, ELSE, END allow for conditional processing. There must be an END command for each IF command. Conditional operators are
  • == for equality
  • != for inequality
  • >, >=, <, and <= for comparison
  • not or ! for negation
  • and or && for AND command
  • or or || for OR command

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); %]