.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 3pm"
.TH Template 3pm "2012-02-07" "perl v5.14.2" "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\s0 \s-1SUMMARY\s0\*(R" 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-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).
.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\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.
.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 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
.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\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 %]
\&
\&    [% UNLESS condition %]
\&       content
\&    [% # ELSIF/ELSE as per IF, above %]
\&       content
\&    [% END %]
.Ve
.SS "\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
.SS "\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
.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::<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
.SS "\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(\*(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\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
.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: <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.