File: //usr/local/ssl/local/share/man/man3/Template.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Template 3"
.TH Template 3 "2012-02-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Template \- Front\-end module to the Template Toolkit
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Template;
.Ve
.PP
.Vb 8
\& # some useful options (see below for full list)
\& my $config = {
\& INCLUDE_PATH => '/search/path', # or list ref
\& INTERPOLATE => 1, # expand "$var" in plain text
\& POST_CHOMP => 1, # cleanup whitespace
\& PRE_PROCESS => 'header', # prefix each template
\& EVAL_PERL => 1, # evaluate Perl code blocks
\& };
.Ve
.PP
.Vb 2
\& # create Template object
\& my $template = Template->new($config);
.Ve
.PP
.Vb 8
\& # define template variables for replacement
\& my $vars = {
\& var1 => $value,
\& var2 => \e%hash,
\& var3 => \e@list,
\& var4 => \e&code,
\& var5 => $object,
\& };
.Ve
.PP
.Vb 2
\& # specify input filename, or file handle, text reference, etc.
\& my $input = 'myfile.html';
.Ve
.PP
.Vb 3
\& # process input template, substituting variables
\& $template->process($input, $vars)
\& || die $template->error();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This documentation describes the Template module which is the direct
Perl interface into the Template Toolkit. It covers the use of the
module and gives a brief summary of configuration options and template
directives. Please see Template::Manual for the complete reference
manual which goes into much greater depth about the features and use
of the Template Toolkit. The Template::Tutorial is also available
as an introductory guide to using the Template Toolkit.
.SH "METHODS"
.IX Header "METHODS"
.Sh "new(\e%config)"
.IX Subsection "new(%config)"
The \f(CW\*(C`new()\*(C'\fR constructor method (implemented by the
Template::Base base class) instantiates a new
\&\f(CW\*(C`Template\*(C'\fR object. A reference to a hash array of configuration items may be
passed as a parameter.
.PP
.Vb 4
\& my $tt = Template->new({
\& INCLUDE_PATH => '/usr/local/templates',
\& EVAL_PERL => 1,
\& }) || die $Template::ERROR, "\en";
.Ve
.PP
A reference to a new \f(CW\*(C`Template\*(C'\fR object is returned, or undef on error. In the
latter case, the error message can be retrieved by calling \fIerror()\fR as a
class method or by examining the \f(CW$Template::ERROR\fR package variable
directly.
.PP
.Vb 2
\& my $tt = Template->new(\e%config)
\& || die Template->error(), "\en";
.Ve
.PP
.Vb 2
\& my $tt = Template->new(\e%config)
\& || die $Template::ERROR, "\en";
.Ve
.PP
For convenience, configuration items may also be specified as a list
of items instead of a hash array reference. These are automatically
folded into a hash array by the constructor.
.PP
.Vb 2
\& my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
\& || die $Template::ERROR, "\en";
.Ve
.ie n .Sh "process($template, \e%vars, $output\fP, \f(CW%options)"
.el .Sh "process($template, \e%vars, \f(CW$output\fP, \f(CW%options\fP)"
.IX Subsection "process($template, %vars, $output, %options)"
The \f(CW\*(C`process()\*(C'\fR method is called to process a template. The first parameter
indicates the input template as one of: a filename relative to
\&\f(CW\*(C`INCLUDE_PATH\*(C'\fR, if defined; a reference to a text string containing the
template text; or a file handle reference (e.g. \f(CW\*(C`IO::Handle\*(C'\fR or sub\-class) or
\&\f(CW\*(C`GLOB\*(C'\fR (e.g. \f(CW\*(C`\e*STDIN\*(C'\fR), from which the template can be read. A reference to
a hash array may be passed as the second parameter, containing definitions of
template variables.
.PP
.Vb 3
\& # filename
\& $tt->process('welcome.tt2')
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 4
\& # text reference
\& $text = "[% INCLUDE header %]\enHello world!\en[% INCLUDE footer %]";
\& $tt->process(\e$text)
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 3
\& # file handle (GLOB)
\& $tt->process(\e*DATA)
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 5
\& __END__
\& [% INCLUDE header %]
\& This is a template defined in the __END__ section which is
\& accessible via the DATA "file handle".
\& [% INCLUDE footer %]
.Ve
.PP
By default, the processed template output is printed to \f(CW\*(C`STDOUT\*(C'\fR. The
\&\f(CW\*(C`process()\*(C'\fR method then returns \f(CW1\fR to indicate success. A third parameter
may be passed to the \f(CW\*(C`process()\*(C'\fR method to specify a different output location.
This value may be one of: a plain string indicating a filename which will be
opened (relative to \f(CW\*(C`OUTPUT_PATH\*(C'\fR, if defined) and the output written to; a file
\&\s-1GLOB\s0 opened ready for output; a reference to a scalar (e.g. a text string) to
which output/error is appended; a reference to a subroutine which is called,
passing the output as a parameter; or any object reference which implements a
\&\f(CW\*(C`print()\*(C'\fR method (e.g. \f(CW\*(C`IO::Handle\*(C'\fR, \f(CW\*(C`Apache::Request\*(C'\fR, etc.) which will be called,
passing the generated output as a parameter.
.PP
Examples:
.PP
.Vb 3
\& # output filename
\& $tt->process('welcome.tt2', $vars, 'welcome.html')
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 7
\& # reference to output subroutine
\& sub myout {
\& my $output = shift;
\& ...
\& }
\& $tt->process('welcome.tt2', $vars, \e&myout)
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 4
\& # reference to output text string
\& my $output = '';
\& $tt->process('welcome.tt2', $vars, \e$output)
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 1
\& print "output: $output\en";
.Ve
.PP
In an Apache/mod_perl handler:
.PP
.Vb 2
\& sub handler {
\& my $req = shift;
.Ve
.PP
.Vb 1
\& # ...your code here...
.Ve
.PP
.Vb 7
\& # direct output to Apache::Request via $req->print($output)
\& $tt->process($file, $vars, $req) || do {
\& $req->log_reason($tt->error());
\& return SERVER_ERROR;
\& };
\& return OK;
\& }
.Ve
.PP
After the optional third output argument can come an optional
reference to a hash or a list of \f(CW\*(C`(name, value)\*(C'\fR pairs providing further
options for the output. The only option currently supported is
\&\f(CW\*(C`binmode\*(C'\fR which, when set to any true value will ensure that files
created (but not any existing file handles passed) will be set to
binary mode.
.PP
.Vb 3
\& # either: hash reference of options
\& $tt->process($infile, $vars, $outfile, { binmode => 1 })
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 3
\& # or: list of name, value pairs
\& $tt->process($infile, $vars, $outfile, binmode => 1)
\& || die $tt->error(), "\en";
.Ve
.PP
Alternately, the \f(CW\*(C`binmode\*(C'\fR argument can specify a particular \s-1IO\s0 layer such
as \f(CW\*(C`:utf8\*(C'\fR.
.PP
.Vb 2
\& $tt->process($infile, $vars, $outfile, binmode => ':utf8')
\& || die $tt->error(), "\en";
.Ve
.PP
The \f(CW\*(C`OUTPUT\*(C'\fR configuration item can be used to specify a default output
location other than \f(CW\*(C`\e*STDOUT\*(C'\fR. The \f(CW\*(C`OUTPUT_PATH\*(C'\fR specifies a directory
which should be prefixed to all output locations specified as filenames.
.PP
.Vb 5
\& my $tt = Template->new({
\& OUTPUT => sub { ... }, # default
\& OUTPUT_PATH => '/tmp',
\& ...
\& }) || die Template->error(), "\en";
.Ve
.PP
.Vb 3
\& # use default OUTPUT (sub is called)
\& $tt->process('welcome.tt2', $vars)
\& || die $tt->error(), "\en";
.Ve
.PP
.Vb 3
\& # write file to '/tmp/welcome.html'
\& $tt->process('welcome.tt2', $vars, 'welcome.html')
\& || die $tt->error(), "\en";
.Ve
.PP
The \f(CW\*(C`process()\*(C'\fR method returns \f(CW1\fR on success or \f(CW\*(C`undef\*(C'\fR on error. The
error message generated in the latter case can be retrieved by calling the
\&\fIerror()\fR method. See also \*(L"\s-1CONFIGURATION\s0 \s-1SUMMARY\s0\*(R" which describes how error
handling may be further customised.
.Sh "\fIerror()\fP"
.IX Subsection "error()"
When called as a class method, it returns the value of the \f(CW$ERROR\fR package
variable. Thus, the following are equivalent.
.PP
.Vb 2
\& my $tt = Template->new()
\& || die Template->error(), "\en";
.Ve
.PP
.Vb 2
\& my $tt = Template->new()
\& || die $Template::ERROR, "\en";
.Ve
.PP
When called as an object method, it returns the value of the internal
\&\f(CW\*(C`_ERROR\*(C'\fR variable, as set by an error condition in a previous call to
\&\fIprocess()\fR.
.PP
.Vb 2
\& $tt->process('welcome.tt2')
\& || die $tt->error(), "\en";
.Ve
.PP
Errors are represented in the Template Toolkit by objects of the
Template::Exception class. If the \fIprocess()\fR method returns a false value
then the \f(CW\*(C`error()\*(C'\fR method can be called to return an object of this class.
The \fItype()\fR and
\&\fIinfo()\fR methods can called on the object to
retrieve the error type and information string, respectively. The
\&\fIas_string()\fR
method can be called to return a string of the form \f(CW\*(C`$type \- $info\*(C'\fR. This
method is also overloaded onto the stringification operator allowing the
object reference itself to be printed to return the formatted error string.
.PP
.Vb 6
\& $tt->process('somefile') || do {
\& my $error = $tt->error();
\& print "error type: ", $error->type(), "\en";
\& print "error info: ", $error->info(), "\en";
\& print $error, "\en";
\& };
.Ve
.Sh "\fIservice()\fP"
.IX Subsection "service()"
The \f(CW\*(C`Template\*(C'\fR module delegates most of the effort of processing templates
to an underlying Template::Service object. This method returns a reference
to that object.
.Sh "\fIcontext()\fP"
.IX Subsection "context()"
The Template::Service module uses a core Template::Context object for
runtime processing of templates. This method returns a reference to
that object and is equivalent to \f(CW\*(C`$template\->service\->context()\*(C'\fR.
.Sh "template($name)"
.IX Subsection "template($name)"
This method is a simple wrapper around the Template::Context method of the
same name. It returns a compiled template for the source provided as an
argument.
.SH "CONFIGURATION SUMMARY"
.IX Header "CONFIGURATION SUMMARY"
The following list gives a short summary of each Template Toolkit
configuration option. See Template::Manual::Config for full details.
.Sh "Template Style and Parsing Options"
.IX Subsection "Template Style and Parsing Options"
\fI\s-1START_TAG\s0, \s-1END_TAG\s0\fR
.IX Subsection "START_TAG, END_TAG"
.PP
Define tokens that indicate start and end of directives
(default: '\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR').
.PP
\fI\s-1TAG_STYLE\s0\fR
.IX Subsection "TAG_STYLE"
.PP
Set \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR according to a pre-defined style (default:
\&'\f(CW\*(C`template\*(C'\fR', as above).
.PP
\fI\s-1PRE_CHOMP\s0, \s-1POST_CHOMP\s0\fR
.IX Subsection "PRE_CHOMP, POST_CHOMP"
.PP
Removes whitespace before/after directives (default: 0/0).
.PP
\fI\s-1TRIM\s0\fR
.IX Subsection "TRIM"
.PP
Remove leading and trailing whitespace from template output (default: 0).
.PP
\fI\s-1INTERPOLATE\s0\fR
.IX Subsection "INTERPOLATE"
.PP
Interpolate variables embedded like \f(CW$this\fR or \f(CW\*(C`${this}\*(C'\fR (default: 0).
.PP
\fI\s-1ANYCASE\s0\fR
.IX Subsection "ANYCASE"
.PP
Allow directive keywords in lower case (default: 0 \- \s-1UPPER\s0 only).
.Sh "Template Files and Blocks"
.IX Subsection "Template Files and Blocks"
\fI\s-1INCLUDE_PATH\s0\fR
.IX Subsection "INCLUDE_PATH"
.PP
One or more directories to search for templates.
.PP
\fI\s-1DELIMITER\s0\fR
.IX Subsection "DELIMITER"
.PP
Delimiter for separating paths in \f(CW\*(C`INCLUDE_PATH\*(C'\fR (default: '\f(CW\*(C`:\*(C'\fR').
.PP
\fI\s-1ABSOLUTE\s0\fR
.IX Subsection "ABSOLUTE"
.PP
Allow absolute file names, e.g. \f(CW\*(C`/foo/bar.html\*(C'\fR (default: 0).
.PP
\fI\s-1RELATIVE\s0\fR
.IX Subsection "RELATIVE"
.PP
Allow relative filenames, e.g. \f(CW\*(C`../foo/bar.html\*(C'\fR (default: 0).
.PP
\fI\s-1DEFAULT\s0\fR
.IX Subsection "DEFAULT"
.PP
Default template to use when another not found.
.PP
\fI\s-1BLOCKS\s0\fR
.IX Subsection "BLOCKS"
.PP
Hash array pre-defining template blocks.
.PP
\fI\s-1AUTO_RESET\s0\fR
.IX Subsection "AUTO_RESET"
.PP
Enabled by default causing \f(CW\*(C`BLOCK\*(C'\fR definitions to be reset each time a
template is processed. Disable to allow \f(CW\*(C`BLOCK\*(C'\fR definitions to persist.
.PP
\fI\s-1RECURSION\s0\fR
.IX Subsection "RECURSION"
.PP
Flag to permit recursion into templates (default: 0).
.Sh "Template Variables"
.IX Subsection "Template Variables"
\fI\s-1VARIABLES\s0\fR
.IX Subsection "VARIABLES"
.PP
Hash array of variables and values to pre-define in the stash.
.Sh "Runtime Processing Options"
.IX Subsection "Runtime Processing Options"
\fI\s-1EVAL_PERL\s0\fR
.IX Subsection "EVAL_PERL"
.PP
Flag to indicate if \f(CW\*(C`PERL\*(C'\fR/\f(CW\*(C`RAWPERL\*(C'\fR blocks should be processed (default: 0).
.PP
\fI\s-1PRE_PROCESS\s0, \s-1POST_PROCESS\s0\fR
.IX Subsection "PRE_PROCESS, POST_PROCESS"
.PP
Name of template(s) to process before/after main template.
.PP
\fI\s-1PROCESS\s0\fR
.IX Subsection "PROCESS"
.PP
Name of template(s) to process instead of main template.
.PP
\fI\s-1ERROR\s0\fR
.IX Subsection "ERROR"
.PP
Name of error template or reference to hash array mapping error types to
templates.
.PP
\fI\s-1OUTPUT\s0\fR
.IX Subsection "OUTPUT"
.PP
Default output location or handler.
.PP
\fI\s-1OUTPUT_PATH\s0\fR
.IX Subsection "OUTPUT_PATH"
.PP
Directory into which output files can be written.
.PP
\fI\s-1DEBUG\s0\fR
.IX Subsection "DEBUG"
.PP
Enable debugging messages.
.Sh "Caching and Compiling Options"
.IX Subsection "Caching and Compiling Options"
\fI\s-1CACHE_SIZE\s0\fR
.IX Subsection "CACHE_SIZE"
.PP
Maximum number of compiled templates to cache in memory (default:
undef \- cache all)
.PP
\fI\s-1COMPILE_EXT\s0\fR
.IX Subsection "COMPILE_EXT"
.PP
Filename extension for compiled template files (default: undef \- don't
compile).
.PP
\fI\s-1COMPILE_DIR\s0\fR
.IX Subsection "COMPILE_DIR"
.PP
Root of directory in which compiled template files should be written
(default: undef \- don't compile).
.Sh "Plugins and Filters"
.IX Subsection "Plugins and Filters"
\fI\s-1PLUGINS\s0\fR
.IX Subsection "PLUGINS"
.PP
Reference to a hash array mapping plugin names to Perl packages.
.PP
\fI\s-1PLUGIN_BASE\s0\fR
.IX Subsection "PLUGIN_BASE"
.PP
One or more base classes under which plugins may be found.
.PP
\fI\s-1LOAD_PERL\s0\fR
.IX Subsection "LOAD_PERL"
.PP
Flag to indicate regular Perl modules should be loaded if a named plugin
can't be found (default: 0).
.PP
\fI\s-1FILTERS\s0\fR
.IX Subsection "FILTERS"
.PP
Hash array mapping filter names to filter subroutines or factories.
.Sh "Customisation and Extension"
.IX Subsection "Customisation and Extension"
\fI\s-1LOAD_TEMPLATES\s0\fR
.IX Subsection "LOAD_TEMPLATES"
.PP
List of template providers.
.PP
\fI\s-1LOAD_PLUGINS\s0\fR
.IX Subsection "LOAD_PLUGINS"
.PP
List of plugin providers.
.PP
\fI\s-1LOAD_FILTERS\s0\fR
.IX Subsection "LOAD_FILTERS"
.PP
List of filter providers.
.PP
\fI\s-1TOLERANT\s0\fR
.IX Subsection "TOLERANT"
.PP
Set providers to tolerate errors as declinations (default: 0).
.PP
\fI\s-1SERVICE\s0\fR
.IX Subsection "SERVICE"
.PP
Reference to a custom service object (default: Template::Service).
.PP
\fI\s-1CONTEXT\s0\fR
.IX Subsection "CONTEXT"
.PP
Reference to a custom context object (default: Template::Context).
.PP
\fI\s-1STASH\s0\fR
.IX Subsection "STASH"
.PP
Reference to a custom stash object (default: Template::Stash).
.PP
\fI\s-1PARSER\s0\fR
.IX Subsection "PARSER"
.PP
Reference to a custom parser object (default: Template::Parser).
.PP
\fI\s-1GRAMMAR\s0\fR
.IX Subsection "GRAMMAR"
.PP
Reference to a custom grammar object (default: Template::Grammar).
.SH "DIRECTIVE SUMMARY"
.IX Header "DIRECTIVE SUMMARY"
The following list gives a short summary of each Template Toolkit directive.
See Template::Manual::Directives for full details.
.Sh "\s-1GET\s0"
.IX Subsection "GET"
Evaluate and print a variable or value.
.PP
.Vb 7
\& [% GET variable %] # 'GET' keyword is optional
\& [% variable %]
\& [% hash.key %]
\& [% list.n %]
\& [% code(args) %]
\& [% obj.meth(args) %]
\& [% "value: $var" %]
.Ve
.Sh "\s-1CALL\s0"
.IX Subsection "CALL"
As per \s-1GET\s0 but without printing result (e.g. call code)
.PP
.Vb 1
\& [% CALL variable %]
.Ve
.Sh "\s-1SET\s0"
.IX Subsection "SET"
Assign a values to variables.
.PP
.Vb 8
\& [% SET variable = value %] # 'SET' also optional
\& [% variable = other_variable
\& variable = 'literal text @ $100'
\& variable = "interpolated text: $var"
\& list = [ val, val, val, val, ... ]
\& list = [ val..val ]
\& hash = { var => val, var => val, ... }
\& %]
.Ve
.Sh "\s-1DEFAULT\s0"
.IX Subsection "DEFAULT"
Like \s-1SET\s0, but variables are only set if currently unset (i.e. have no
true value).
.PP
.Vb 1
\& [% DEFAULT variable = value %]
.Ve
.Sh "\s-1INSERT\s0"
.IX Subsection "INSERT"
Insert a file without any processing performed on the contents.
.PP
.Vb 1
\& [% INSERT legalese.txt %]
.Ve
.Sh "\s-1PROCESS\s0"
.IX Subsection "PROCESS"
Process another template file or block and insert the generated output.
Any template \s-1BLOCK\s0s or variables defined or updated in the \f(CW\*(C`PROCESS\*(C'\fRed
template will thereafter be defined in the calling template.
.PP
.Vb 2
\& [% PROCESS template %]
\& [% PROCESS template var = val, ... %]
.Ve
.Sh "\s-1INCLUDE\s0"
.IX Subsection "INCLUDE"
Similar to \f(CW\*(C`PROCESS\*(C'\fR, but using a local copy of the current variables.
Any template \f(CW\*(C`BLOCK\*(C'\fRs or variables defined in the \f(CW\*(C`INCLUDE\*(C'\fRd template
remain local to it.
.PP
.Vb 2
\& [% INCLUDE template %]
\& [% INCLUDE template var = val, ... %]
.Ve
.Sh "\s-1WRAPPER\s0"
.IX Subsection "WRAPPER"
The content between the \f(CW\*(C`WRAPPER\*(C'\fR and correspondng \f(CW\*(C`END\*(C'\fR directives is first
evaluated, with the output generated being stored in the \f(CW\*(C`content\*(C'\fR variable.
The named template is then process as per \f(CW\*(C`INCLUDE\*(C'\fR.
.PP
.Vb 3
\& [% WRAPPER layout %]
\& Some template markup [% blah %]...
\& [% END %]
.Ve
.PP
A simple \fIlayout\fR template might look something like this:
.PP
.Vb 3
\& Your header here...
\& [% content %]
\& Your footer here...
.Ve
.Sh "\s-1BLOCK\s0"
.IX Subsection "BLOCK"
Define a named template block for \s-1INCLUDE\s0, \s-1PROCESS\s0 and \s-1WRAPPER\s0
to use.
.PP
.Vb 3
\& [% BLOCK hello %]
\& Hello World
\& [% END %]
.Ve
.PP
.Vb 1
\& [% INCLUDE hello %]
.Ve
.Sh "\s-1FOREACH\s0"
.IX Subsection "FOREACH"
Repeat the enclosed \f(CW\*(C`FOREACH\*(C'\fR ... \f(CW\*(C`END\*(C'\fR block for each value in the list.
.PP
.Vb 4
\& [% FOREACH variable IN [ val, val, val ] %] # either
\& [% FOREACH variable IN list %] # or
\& The variable is set to [% variable %]
\& [% END %]
.Ve
.Sh "\s-1WHILE\s0"
.IX Subsection "WHILE"
The block enclosed between \f(CW\*(C`WHILE\*(C'\fR and \f(CW\*(C`END\*(C'\fR block is processed while
the specified condition is true.
.PP
.Vb 3
\& [% WHILE condition %]
\& content
\& [% END %]
.Ve
.Sh "\s-1IF\s0 / \s-1UNLESS\s0 / \s-1ELSIF\s0 / \s-1ELSE\s0"
.IX Subsection "IF / UNLESS / ELSIF / ELSE"
The enclosed block is processed if the condition is true / false.
.PP
.Vb 7
\& [% IF condition %]
\& content
\& [% ELSIF condition %]
\& content
\& [% ELSE %]
\& content
\& [% END %]
.Ve
.PP
.Vb 5
\& [% UNLESS condition %]
\& content
\& [% # ELSIF/ELSE as per IF, above %]
\& content
\& [% END %]
.Ve
.Sh "\s-1SWITCH\s0 / \s-1CASE\s0"
.IX Subsection "SWITCH / CASE"
Multi-way switch/case statement.
.PP
.Vb 8
\& [% SWITCH variable %]
\& [% CASE val1 %]
\& content
\& [% CASE [ val2, val3 ] %]
\& content
\& [% CASE %] # or [% CASE DEFAULT %]
\& content
\& [% END %]
.Ve
.Sh "\s-1MACRO\s0"
.IX Subsection "MACRO"
Define a named macro.
.PP
.Vb 5
\& [% MACRO name <directive> %]
\& [% MACRO name(arg1, arg2) <directive> %]
\& ...
\& [% name %]
\& [% name(val1, val2) %]
.Ve
.Sh "\s-1FILTER\s0"
.IX Subsection "FILTER"
Process enclosed \f(CW\*(C`FILTER\*(C'\fR ... \f(CW\*(C`END\*(C'\fR block then pipe through a filter.
.PP
.Vb 5
\& [% FILTER name %] # either
\& [% FILTER name( params ) %] # or
\& [% FILTER alias = name( params ) %] # or
\& content
\& [% END %]
.Ve
.Sh "\s-1USE\s0"
.IX Subsection "USE"
Load a plugin module (see \f(CW\*(C`Template::<Manual::Plugins\*(C'\fR), or any regular Perl
module when the \f(CW\*(C`LOAD_PERL\*(C'\fR option is set.
.PP
.Vb 6
\& [% USE name %] # either
\& [% USE name( params ) %] # or
\& [% USE var = name( params ) %] # or
\& ...
\& [% name.method %]
\& [% var.method %]
.Ve
.Sh "\s-1PERL\s0 / \s-1RAWPERL\s0"
.IX Subsection "PERL / RAWPERL"
Evaluate enclosed blocks as Perl code (requires the \f(CW\*(C`EVAL_PERL\*(C'\fR option to be
set).
.PP
.Vb 6
\& [% PERL %]
\& # perl code goes here
\& $stash->set('foo', 10);
\& print "set 'foo' to ", $stash->get('foo'), "\en";
\& print $context->include('footer', { var => $val });
\& [% END %]
.Ve
.PP
.Vb 4
\& [% RAWPERL %]
\& # raw perl code goes here, no magic but fast.
\& $output .= 'some output';
\& [% END %]
.Ve
.Sh "\s-1TRY\s0 / \s-1THROW\s0 / \s-1CATCH\s0 / \s-1FINAL\s0"
.IX Subsection "TRY / THROW / CATCH / FINAL"
Exception handling.
.PP
.Vb 11
\& [% TRY %]
\& content
\& [% THROW type info %]
\& [% CATCH type %]
\& catch content
\& [% error.type %] [% error.info %]
\& [% CATCH %] # or [% CATCH DEFAULT %]
\& content
\& [% FINAL %]
\& this block is always processed
\& [% END %]
.Ve
.Sh "\s-1NEXT\s0"
.IX Subsection "NEXT"
Jump straight to the next item in a \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop.
.PP
.Vb 1
\& [% NEXT %]
.Ve
.Sh "\s-1LAST\s0"
.IX Subsection "LAST"
Break out of \f(CW\*(C`FOREACH\*(C'\fR or \f(CW\*(C`WHILE\*(C'\fR loop.
.PP
.Vb 1
\& [% LAST %]
.Ve
.Sh "\s-1RETURN\s0"
.IX Subsection "RETURN"
Stop processing current template and return to including templates.
.PP
.Vb 1
\& [% RETURN %]
.Ve
.Sh "\s-1STOP\s0"
.IX Subsection "STOP"
Stop processing all templates and return to caller.
.PP
.Vb 1
\& [% STOP %]
.Ve
.Sh "\s-1TAGS\s0"
.IX Subsection "TAGS"
Define new tag style or characters (default: \f(CW\*(C`[%\*(C'\fR \f(CW\*(C`%]\*(C'\fR).
.PP
.Vb 2
\& [% TAGS html %]
\& [% TAGS <!-- --> %]
.Ve
.Sh "\s-1COMMENTS\s0"
.IX Subsection "COMMENTS"
Ignored and deleted.
.PP
.Vb 3
\& [% # this is a comment to the end of line
\& foo = 'bar'
\& %]
.Ve
.PP
.Vb 3
\& [%# placing the '#' immediately inside the directive
\& tag comments out the entire directive
\& %]
.Ve
.SH "SOURCE CODE REPOSITORY"
.IX Header "SOURCE CODE REPOSITORY"
The source code for the Template Toolkit is held in a public git repository
on Github: <https://github.com/abw/Template2>
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH "VERSION"
.IX Header "VERSION"
Template Toolkit version 2.23, released January 2012.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2012 Andy Wardley. All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.