/usr/local/share/man/man3
Edit: /usr/local/share/man/man3/Template.3pm (27909B)
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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. \*(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-
.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" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "2014-04-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template \- Front\-end module to the Template Toolkit
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Template;
\&
\& # some useful options (see below for full list)
\& my $config = {
\& INCLUDE_PATH => \*(Aq/search/path\*(Aq, # or list ref
\& INTERPOLATE => 1, # expand "$var" in plain text
\& POST_CHOMP => 1, # cleanup whitespace
\& PRE_PROCESS => \*(Aqheader\*(Aq, # prefix each template
\& EVAL_PERL => 1, # evaluate Perl code blocks
\& };
\&
\& # create Template object
\& my $template = Template\->new($config);
\&
\& # define template variables for replacement
\& my $vars = {
\& var1 => $value,
\& var2 => \e%hash,
\& var3 => \e@list,
\& var4 => \e&code,
\& var5 => $object,
\& };
\&
\& # specify input filename, or file handle, text reference, etc.
\& my $input = \*(Aqmyfile.html\*(Aq;
\&
\& # 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"
.SS "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 => \*(Aq/usr/local/templates\*(Aq,
\& 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";
\&
\& 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 => \*(Aq/tmp\*(Aq, POST_CHOMP => 1)
\& || die $Template::ERROR, "\en";
.Ve
.ie n .SS "process($template, \e%vars, $output, %options)"
.el .SS "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(\*(Aqwelcome.tt2\*(Aq)
\& || die $tt\->error(), "\en";
\&
\& # text reference
\& $text = "[% INCLUDE header %]\enHello world!\en[% INCLUDE footer %]";
\& $tt\->process(\e$text)
\& || die $tt\->error(), "\en";
\&
\& # file handle (GLOB)
\& $tt\->process(\e*DATA)
\& || die $tt\->error(), "\en";
\&
\& _\|_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(\*(Aqwelcome.tt2\*(Aq, $vars, \*(Aqwelcome.html\*(Aq)
\& || die $tt\->error(), "\en";
\&
\& # reference to output subroutine
\& sub myout {
\& my $output = shift;
\& ...
\& }
\& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \e&myout)
\& || die $tt\->error(), "\en";
\&
\& # reference to output text string
\& my $output = \*(Aq\*(Aq;
\& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \e$output)
\& || die $tt\->error(), "\en";
\&
\& print "output: $output\en";
.Ve
.PP
In an Apache/mod_perl handler:
.PP
.Vb 2
\& sub handler {
\& my $req = shift;
\&
\& # ...your code here...
\&
\& # 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";
\&
\& # 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 => \*(Aq:utf8\*(Aq)
\& || 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 => \*(Aq/tmp\*(Aq,
\& ...
\& }) || die Template\->error(), "\en";
\&
\& # use default OUTPUT (sub is called)
\& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars)
\& || die $tt\->error(), "\en";
\&
\& # write file to \*(Aq/tmp/welcome.html\*(Aq
\& $tt\->process(\*(Aqwelcome.tt2\*(Aq, $vars, \*(Aqwelcome.html\*(Aq)
\& || 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 SUMMARY\*(R"\s0 which describes how error
handling may be further customised.
.SS "\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";
\&
\& 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(\*(Aqwelcome.tt2\*(Aq)
\& || 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(\*(Aqsomefile\*(Aq) || do {
\& my $error = $tt\->error();
\& print "error type: ", $error\->type(), "\en";
\& print "error info: ", $error\->info(), "\en";
\& print $error, "\en";
\& };
.Ve
.SS "\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.
.SS "\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.
.SS "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.
.SS "Template Style and Parsing Options"
.IX Subsection "Template Style and Parsing Options"
\fI\s-1ENCODING\s0\fR
.IX Subsection "ENCODING"
.PP
Specifies the character encoding.
.PP
\fI\s-1START_TAG, END_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, POST_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).
.SS "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).
.SS "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.
.SS "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, POST_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.
.SS "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).
.SS "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.
.SS "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.
.SS "\s-1GET\s0"
.IX Subsection "GET"
Evaluate and print a variable or value.
.PP
.Vb 7
\& [% GET variable %] # \*(AqGET\*(Aq keyword is optional
\& [% variable %]
\& [% hash.key %]
\& [% list.n %]
\& [% code(args) %]
\& [% obj.meth(args) %]
\& [% "value: $var" %]
.Ve
.SS "\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
.SS "\s-1SET\s0"
.IX Subsection "SET"
Assign a values to variables.
.PP
.Vb 8
\& [% SET variable = value %] # \*(AqSET\*(Aq also optional
\& [% variable = other_variable
\& variable = \*(Aqliteral text @ $100\*(Aq
\& variable = "interpolated text: $var"
\& list = [ val, val, val, val, ... ]
\& list = [ val..val ]
\& hash = { var => val, var => val, ... }
\& %]
.Ve
.SS "\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
.SS "\s-1INSERT\s0"
.IX Subsection "INSERT"
Insert a file without any processing performed on the contents.
.PP
.Vb 1
\& [% INSERT legalese.txt %]
.Ve
.SS "\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
.SS "\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
.SS "\s-1WRAPPER\s0"
.IX Subsection "WRAPPER"
The content between the \f(CW\*(C`WRAPPER\*(C'\fR and corresponding \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
.SS "\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 %]
\&
\& [% INCLUDE hello %]
.Ve
.SS "\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
.SS "\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
.SS "\s-1IF / UNLESS / ELSIF / ELSE\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 %]
\&
\& [% UNLESS condition %]
\& content
\& [% # ELSIF/ELSE as per IF, above %]
\& content
\& [% END %]
.Ve
.SS "\s-1SWITCH / CASE\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
.SS "\s-1MACRO\s0"
.IX Subsection "MACRO"
Define a named macro.
.PP
.Vb 5
\& [% MACRO name
%]
\& [% MACRO name(arg1, arg2) %]
\& ...
\& [% name %]
\& [% name(val1, val2) %]
.Ve
.SS "\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
.SS "\s-1USE\s0"
.IX Subsection "USE"
Load a plugin module (see \f(CW\*(C`Template::set(\*(Aqfoo\*(Aq, 10);
\& print "set \*(Aqfoo\*(Aq to ", $stash\->get(\*(Aqfoo\*(Aq), "\en";
\& print $context\->include(\*(Aqfooter\*(Aq, { var => $val });
\& [% END %]
\&
\& [% RAWPERL %]
\& # raw perl code goes here, no magic but fast.
\& $output .= \*(Aqsome output\*(Aq;
\& [% END %]
.Ve
.SS "\s-1TRY / THROW / CATCH / FINAL\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
.SS "\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
.SS "\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
.SS "\s-1RETURN\s0"
.IX Subsection "RETURN"
Stop processing current template and return to including templates.
.PP
.Vb 1
\& [% RETURN %]
.Ve
.SS "\s-1STOP\s0"
.IX Subsection "STOP"
Stop processing all templates and return to caller.
.PP
.Vb 1
\& [% STOP %]
.Ve
.SS "\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
.SS "\s-1COMMENTS\s0"
.IX Subsection "COMMENTS"
Ignored and deleted.
.PP
.Vb 3
\& [% # this is a comment to the end of line
\& foo = \*(Aqbar\*(Aq
\& %]
\&
\& [%# placing the \*(Aq#\*(Aq 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:
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley
.SH "VERSION"
.IX Header "VERSION"
Template Toolkit version 2.26, released January 2014.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2014 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.