--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" 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::Manual::Variables 3"
+.TH Template::Manual::Variables 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Template::Manual::Variables \- Template variables and code bindings
+.SH "Template Variables"
+.IX Header "Template Variables"
+A reference to a hash array may be passed as the second argument to the
+\&\fIprocess()\fR method, containing definitions of template
+variables. The \f(CW\*(C`VARIABLES\*(C'\fR (a.k.a. \f(CW\*(C`PRE_DEFINE\*(C'\fR) option can also be used to
+pre-define variables for all templates processed by the object.
+.PP
+.Vb 6
+\& my $tt = Template\->new({
+\& VARIABLES => {
+\& version => 3.14,
+\& release => 'Sahara',
+\& },
+\& });
+.Ve
+.PP
+.Vb 3
+\& my $vars = {
+\& serial_no => 271828,
+\& };
+.Ve
+.PP
+.Vb 1
+\& $tt\->process('myfile', $vars);
+.Ve
+.PP
+\&\fImyfile\fR template:
+.PP
+.Vb 2
+\& This is version [% version %] ([% release %]).
+\& Serial number: [% serial_no %]
+.Ve
+.PP
+Generated Output:
+.PP
+.Vb 2
+\& This is version 3.14 (Sahara)
+\& Serial number: 271828
+.Ve
+.PP
+Variable names may contain any alphanumeric characters or underscores. They
+may be lower, upper or mixed case although the usual convention is to use
+lower case. The case \fIis\fR significant however, and '\f(CW\*(C`foo\*(C'\fR', '\f(CW\*(C`Foo\*(C'\fR' and
+\&'\f(CW\*(C`FOO\*(C'\fR' are all different variables. Upper case variable names are permitted,
+but not recommended due to a possible conflict with an existing or future
+reserved word. As of version 2.00, these are:
+.PP
+.Vb 5
+\& GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
+\& IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
+\& USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
+\& TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
+\& CLEAR TO STEP AND OR NOT MOD DIV END
+.Ve
+.PP
+The variable values may be of virtually any Perl type, including
+simple scalars, references to lists, hash arrays, subroutines or
+objects. The Template Toolkit will automatically apply the correct
+procedure to accessing these values as they are used in the template.
+.PP
+Example data:
+.PP
+.Vb 11
+\& my $vars = {
+\& article => 'The Third Shoe',
+\& person => {
+\& id => 314,
+\& name => 'Mr. Blue',
+\& email => 'blue@nowhere.org',
+\& },
+\& primes => [ 2, 3, 5, 7, 11, 13 ],
+\& wizard => sub { return join(' ', 'Abracadabra!', @_) },
+\& cgi => CGI\->new('mode=submit&debug=1'),
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 1
+\& [% article %]
+.Ve
+.PP
+.Vb 1
+\& [% person.id %]: [% person.name %] <[% person.email %]>
+.Ve
+.PP
+.Vb 2
+\& [% primes.first %] \- [% primes.last %], including [% primes.3 %]
+\& [% primes.size %] prime numbers: [% primes.join(', ') %]
+.Ve
+.PP
+.Vb 2
+\& [% wizard %]
+\& [% wizard('Hocus Pocus!') %]
+.Ve
+.PP
+.Vb 1
+\& [% cgi.param('mode') %]
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 1
+\& The Third Shoe
+.Ve
+.PP
+.Vb 1
+\& 314: Mr. Blue <blue@nowhere.org>
+.Ve
+.PP
+.Vb 2
+\& 2 \- 13, including 7
+\& 6 prime numbers: 2, 3, 5, 7, 11, 13
+.Ve
+.PP
+.Vb 2
+\& Abracadabra!
+\& Abracadabra! Hocus Pocus!
+.Ve
+.PP
+.Vb 1
+\& submit
+.Ve
+.Sh "Scalar Values"
+.IX Subsection "Scalar Values"
+Regular scalar variables are accessed by simply specifying their name.
+As these are just entries in the top-level variable hash they can be
+considered special cases of hash array referencing as described below,
+with the main namespace hash automatically implied.
+.PP
+.Vb 1
+\& [% article %]
+.Ve
+.Sh "Hash Array References"
+.IX Subsection "Hash Array References"
+Members of hash arrays are accessed by specifying the hash reference
+and key separated by the dot '\f(CW\*(C`.\*(C'\fR' operator.
+.PP
+Example data:
+.PP
+.Vb 8
+\& my $vars = {
+\& 'home' => 'http://www.myserver.com/homepage.html',
+\& 'page' => {
+\& 'this' => 'mypage.html',
+\& 'next' => 'nextpage.html',
+\& 'prev' => 'prevpage.html',
+\& },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 3
+\& <a href="[% home %]">Home</a>
+\& <a href="[% page.prev %]">Previous Page</a>
+\& <a href="[% page.next %]">Next Page</a>
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 3
+\& <a href="http://www.myserver.com/homepage.html">Home</a>
+\& <a href="prevpage.html">Previous Page</a>
+\& <a href="nextpage.html">Next Page</a>
+.Ve
+.PP
+Any key in a hash which starts with a '\f(CW\*(C`_\*(C'\fR' or '\f(CW\*(C`.\*(C'\fR' character will be
+considered private and cannot be evaluated or updated from within a
+template. The undefined value will be returned for any such variable
+accessed which the Template Toolkit will silently ignore (unless the
+\&\f(CW\*(C`DEBUG\*(C'\fR option is enabled).
+.PP
+Example data:
+.PP
+.Vb 9
+\& my $vars = {
+\& message => 'Hello World!',
+\& _secret => "On the Internet, no\-one knows you're a dog",
+\& thing => {
+\& public => 123,
+\& _private => 456,
+\& '.hidden' => 789,
+\& },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 5
+\& [% message %] # outputs "Hello World!"
+\& [% _secret %] # no output
+\& [% thing.public %] # outputs "123"
+\& [% thing._private %] # no output
+\& [% thing..hidden %] # ERROR: unexpected token (..)
+.Ve
+.PP
+You can disable this feature by setting the \f(CW$Template::Stash::PRIVATE\fR
+package variable to a false value.
+.PP
+.Vb 1
+\& $Template::Stash::PRIVATE = undef; # now you can thing._private
+.Ve
+.PP
+To access a hash entry using a key stored in another variable, prefix
+the key variable with '\f(CW\*(C`$\*(C'\fR' to have it interpolated before use (see
+\&\*(L"Variable Interpolation\*(R").
+.PP
+.Vb 2
+\& [% pagename = 'next' %]
+\& [% page.$pagename %] # same as [% page.next %]
+.Ve
+.PP
+When you assign to a variable that contains multiple namespace
+elements (i.e. it has one or more '\f(CW\*(C`.\*(C'\fR' characters in the name),
+any hashes required to represent intermediate namespaces will be
+created automatically. In this following example, the \f(CW\*(C`product\*(C'\fR
+variable automatically springs into life as a hash array unless
+otherwise defined.
+.PP
+.Vb 4
+\& [% product.id = 'XYZ\-2000'
+\& product.desc = 'Bogon Generator'
+\& product.price = 666
+\& %]
+.Ve
+.PP
+.Vb 2
+\& The [% product.id %] [% product.desc %]
+\& costs $[% product.price %].00
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 2
+\& The XYZ\-2000 Bogon Generator
+\& costs $666.00
+.Ve
+.PP
+You can use Perl's familiar \f(CW\*(C`{\*(C'\fR ... \f(CW\*(C`}\*(C'\fR construct to explicitly create
+a hash and assign it to a variable. Note that commas are optional
+between key/value pairs and \f(CW\*(C`=\*(C'\fR can be used in place of \f(CW\*(C`=>\*(C'\fR.
+.PP
+.Vb 7
+\& # minimal TT style
+\& [% product = {
+\& id = 'XYZ\-2000'
+\& desc = 'Bogon Generator'
+\& price = 666
+\& }
+\& %]
+.Ve
+.PP
+.Vb 7
+\& # perl style
+\& [% product = {
+\& id => 'XYZ\-2000',
+\& desc => 'Bogon Generator',
+\& price => 666,
+\& }
+\& %]
+.Ve
+.Sh "List References"
+.IX Subsection "List References"
+Items in lists are also accessed by use of the dot operator.
+.PP
+Example data:
+.PP
+.Vb 3
+\& my $vars = {
+\& people => [ 'Tom', 'Dick', 'Larry' ],
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 3
+\& [% people.0 %] # Tom
+\& [% people.1 %] # Dick
+\& [% people.2 %] # Larry
+.Ve
+.PP
+The \f(CW\*(C`FOREACH\*(C'\fR directive can be used to iterate through items in a list.
+.PP
+.Vb 3
+\& [% FOREACH person IN people %]
+\& Hello [% person %]
+\& [% END %]
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 3
+\& Hello Tom
+\& Hello Dick
+\& Hello Larry
+.Ve
+.PP
+Lists can be constructed in-situ using the regular anonymous list
+\&\f(CW\*(C`[\*(C'\fR ... \f(CW\*(C`]\*(C'\fR construct. Commas between items are optional.
+.PP
+.Vb 1
+\& [% cols = [ 'red', 'green', 'blue' ] %]
+.Ve
+.PP
+.Vb 3
+\& [% FOREACH c IN cols %]
+\& [% c %]
+\& [% END %]
+.Ve
+.PP
+or:
+.PP
+.Vb 3
+\& [% FOREACH c IN [ 'red', 'green', 'blue' ] %]
+\& [% c %]
+\& [% END %]
+.Ve
+.PP
+You can also create simple numerical sequences using the \f(CW\*(C`..\*(C'\fR range
+operator:
+.PP
+.Vb 1
+\& [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ]
+.Ve
+.PP
+.Vb 4
+\& [% x = 4
+\& y = 8
+\& z = [x..y] # z is [ 4, 5, 6, 7, 8 ]
+\& %]
+.Ve
+.Sh "Subroutines"
+.IX Subsection "Subroutines"
+Template variables can contain references to Perl subroutines. When
+the variable is used, the Template Toolkit will automatically call the
+subroutine, passing any additional arguments specified. The return
+value from the subroutine is used as the variable value and inserted
+into the document output.
+.PP
+.Vb 3
+\& my $vars = {
+\& wizard => sub { return join(' ', 'Abracadabra!', @_) },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 2
+\& [% wizard %] # Abracadabra!
+\& [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus!
+.Ve
+.Sh "Objects"
+.IX Subsection "Objects"
+Template variables can also contain references to Perl objects.
+Methods are called using the dot operator to specify the method
+against the object variable. Additional arguments can be specified
+as with subroutines.
+.PP
+.Vb 1
+\& use CGI;
+.Ve
+.PP
+.Vb 4
+\& my $vars = {
+\& # hard coded CGI params for purpose of example
+\& cgi => CGI\->new('mode=submit&debug=1'),
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 3
+\& [% FOREACH p IN cgi.param %] # returns list of param keys
+\& [% p %] => [% cgi.param(p) %] # fetch each param value
+\& [% END %]
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 2
+\& mode => submit
+\& debug => 1
+.Ve
+.PP
+Object methods can also be called as lvalues. That is, they can appear on
+the left side of an assignment. The method will be called passing the
+assigning value as an argument.
+.PP
+.Vb 1
+\& [% myobj.method = 10 %]
+.Ve
+.PP
+equivalent to:
+.PP
+.Vb 1
+\& [% myobj.method(10) %]
+.Ve
+.Sh "Passing Parameters and Returning Values"
+.IX Subsection "Passing Parameters and Returning Values"
+Subroutines and methods will be passed any arguments specified in the
+template. Any template variables in the argument list will first be
+evaluated and their resultant values passed to the code.
+.PP
+.Vb 3
+\& my $vars = {
+\& mycode => sub { return 'received ' . join(', ', @_) },
+\& };
+.Ve
+.PP
+template:
+.PP
+.Vb 2
+\& [% foo = 10 %]
+\& [% mycode(foo, 20) %] # received 10, 20
+.Ve
+.PP
+Named parameters may also be specified. These are automatically collected
+into a single hash array which is passed by reference as the \fBlast\fR
+parameter to the sub\-routine. Named parameters can be specified using
+either \f(CW\*(C`=>\*(C'\fR or \f(CW\*(C`=\*(C'\fR and can appear anywhere in the argument list.
+.PP
+.Vb 3
+\& my $vars = {
+\& myjoin => \e&myjoin,
+\& };
+.Ve
+.PP
+.Vb 5
+\& sub myjoin {
+\& # look for hash ref as last argument
+\& my $params = ref $_[\-1] eq 'HASH' ? pop : { };
+\& return join($params\->{ joint } || ' + ', @_);
+\& }
+.Ve
+.PP
+Example template:
+.PP
+.Vb 3
+\& [% myjoin(10, 20, 30) %]
+\& [% myjoin(10, 20, 30, joint = ' \- ' %]
+\& [% myjoin(joint => ' * ', 10, 20, 30 %]
+.Ve
+.PP
+Generated output:
+.PP
+.Vb 3
+\& 10 + 20 + 30
+\& 10 \- 20 \- 30
+\& 10 * 20 * 30
+.Ve
+.PP
+Parenthesised parameters may be added to any element of a variable,
+not just those that are bound to code or object methods. At present,
+parameters will be ignored if the variable isn't \*(L"callable\*(R" but are
+supported for future extensions. Think of them as \*(L"hints\*(R" to that
+variable, rather than just arguments passed to a function.
+.PP
+.Vb 2
+\& [% r = 'Romeo' %]
+\& [% r(100, 99, s, t, v) %] # outputs "Romeo"
+.Ve
+.PP
+User code should return a value for the variable it represents. This
+can be any of the Perl data types described above: a scalar, or
+reference to a list, hash, subroutine or object. Where code returns a
+list of multiple values the items will automatically be folded into a
+list reference which can be accessed as per normal.
+.PP
+.Vb 5
+\& my $vars = {
+\& # either is OK, first is recommended
+\& items1 => sub { return [ 'foo', 'bar', 'baz' ] },
+\& items2 => sub { return ( 'foo', 'bar', 'baz' ) },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 3
+\& [% FOREACH i IN items1 %]
+\& ...
+\& [% END %]
+.Ve
+.PP
+.Vb 3
+\& [% FOREACH i IN items2 %]
+\& ...
+\& [% END %]
+.Ve
+.Sh "Error Handling"
+.IX Subsection "Error Handling"
+Errors can be reported from user code by calling \f(CW\*(C`die()\*(C'\fR. Errors raised
+in this way are caught by the Template Toolkit and converted to
+structured exceptions which can be handled from within the template.
+A reference to the exception object is then available as the \f(CW\*(C`error\*(C'\fR
+variable.
+.PP
+.Vb 5
+\& my $vars = {
+\& barf => sub {
+\& die "a sick error has occurred\en";
+\& },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 5
+\& [% TRY %]
+\& [% barf %] # calls sub which throws error via die()
+\& [% CATCH %]
+\& [% error.info %] # outputs "a sick error has occurred\en"
+\& [% END %]
+.Ve
+.PP
+Error messages thrown via \f(CW\*(C`die()\*(C'\fR are converted to exceptions of type
+\&\f(CW\*(C`undef\*(C'\fR (the literal string \*(L"undef\*(R" rather than the undefined value).
+Exceptions of user-defined types can be thrown by calling \f(CW\*(C`die()\*(C'\fR with
+a reference to a Template::Exception object.
+.PP
+.Vb 1
+\& use Template::Exception;
+.Ve
+.PP
+.Vb 6
+\& my $vars = {
+\& login => sub {
+\& ...do something...
+\& die Template::Exception\->new( badpwd => 'password too silly' );
+\& },
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 7
+\& [% TRY %]
+\& [% login %]
+\& [% CATCH badpwd %]
+\& Bad password: [% error.info %]
+\& [% CATCH %]
+\& Some other '[% error.type %]' error: [% error.info %]
+\& [% END %]
+.Ve
+.PP
+The exception types \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`return\*(C'\fR are used to implement the
+\&\f(CW\*(C`STOP\*(C'\fR and \f(CW\*(C`RETURN\*(C'\fR directives. Throwing an exception as:
+.PP
+.Vb 1
+\& die (Template::Exception\->new('stop'));
+.Ve
+.PP
+has the same effect as the directive:
+.PP
+.Vb 1
+\& [% STOP %]
+.Ve
+.SH "Virtual Methods"
+.IX Header "Virtual Methods"
+The Template Toolkit implements a number of \*(L"virtual methods\*(R" which
+can be applied to scalars, hashes or lists. For example:
+.PP
+.Vb 2
+\& [% mylist = [ 'foo', 'bar', 'baz' ] %]
+\& [% newlist = mylist.sort %]
+.Ve
+.PP
+Here \f(CW\*(C`mylist\*(C'\fR is a regular reference to a list, and 'sort' is
+a virtual method that returns a new list of the items in sorted
+order. You can chain multiple virtual methods together. For
+example:
+.PP
+.Vb 1
+\& [% mylist.sort.join(', ') %]
+.Ve
+.PP
+Here the \f(CW\*(C`join\*(C'\fR virtual method is called to join the sorted list into
+a single string, generating the following output:
+.PP
+.Vb 1
+\& bar, baz, foo
+.Ve
+.PP
+See Template::Manual::VMethods for details of all the virtual
+methods available.
+.SH "Variable Interpolation"
+.IX Header "Variable Interpolation"
+The Template Toolkit uses \f(CW\*(C`$\*(C'\fR consistently to indicate that a variable
+should be interpolated in position. Most frequently, you see this in
+double-quoted strings:
+.PP
+.Vb 1
+\& [% fullname = "$honorific $firstname $surname" %]
+.Ve
+.PP
+Or embedded in plain text when the \f(CW\*(C`INTERPOLATE\*(C'\fR option is set:
+.PP
+.Vb 1
+\& Dear $honorific $firstname $surname,
+.Ve
+.PP
+The same rules apply within directives. If a variable is prefixed
+with a \f(CW\*(C`$\*(C'\fR then it is replaced with its value before being used. The
+most common use is to retrieve an element from a hash where the key is
+stored in a variable.
+.PP
+.Vb 2
+\& [% uid = 'abw' %]
+\& [% users.$uid %] # same as 'userlist.abw'
+.Ve
+.PP
+Curly braces can be used to delimit interpolated variable names where
+necessary.
+.PP
+.Vb 1
+\& [% users.${me.id}.name %]
+.Ve
+.PP
+Directives such as \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR, etc., that accept a template name
+as the first argument, will automatically quote it for convenience.
+.PP
+.Vb 1
+\& [% INCLUDE foo/bar.txt %]
+.Ve
+.PP
+The above example is equivalent to:
+.PP
+.Vb 1
+\& [% INCLUDE "foo/bar.txt" %]
+.Ve
+.PP
+To \f(CW\*(C`INCLUDE\*(C'\fR a template whose name is stored in a variable, simply
+prefix the variable name with \f(CW\*(C`$\*(C'\fR to have it interpolated.
+.PP
+.Vb 2
+\& [% myfile = 'header' %]
+\& [% INCLUDE $myfile %]
+.Ve
+.PP
+This is equivalent to:
+.PP
+.Vb 1
+\& [% INCLUDE header %]
+.Ve
+.PP
+Note also that a variable containing a reference to a Template::Document
+object can also be processed in this way.
+.PP
+.Vb 3
+\& my $vars = {
+\& header => Template::Document\->new({ ... }),
+\& };
+.Ve
+.PP
+Example template:
+.PP
+.Vb 1
+\& [% INCLUDE $header %]
+.Ve
+.SH "Local and Global Variables"
+.IX Header "Local and Global Variables"
+Any simple variables that you create, or any changes you make to
+existing variables, will only persist while the template is being
+processed. The top-level variable hash is copied before processing
+begins and any changes to variables are made in this copy, leaving the
+original intact.
+.PP
+The same thing happens when you \f(CW\*(C`INCLUDE\*(C'\fR another template. The current
+namespace hash is cloned to prevent any variable changes made in the included
+template from interfering with existing variables. The \f(CW\*(C`PROCESS\*(C'\fR option bypasses
+the localisation step altogether making it slightly faster, but requiring
+greater attention to the possibility of side effects caused by creating or
+changing any variables within the processed template.
+.PP
+.Vb 3
+\& [% BLOCK change_name %]
+\& [% name = 'bar' %]
+\& [% END %]
+.Ve
+.PP
+.Vb 5
+\& [% name = 'foo' %]
+\& [% INCLUDE change_name %]
+\& [% name %] # foo
+\& [% PROCESS change_name %]
+\& [% name %] # bar
+.Ve
+.PP
+Dotted compound variables behave slightly differently because the
+localisation process is only skin deep. The current variable
+namespace hash is copied, but no attempt is made to perform a
+deep-copy of other structures within it (hashes, arrays, objects,
+etc). A variable referencing a hash, for example, will be copied to
+create a new reference but which points to the same hash. Thus, the
+general rule is that simple variables (undotted variables) are
+localised, but existing complex structures (dotted variables) are not.
+.PP
+.Vb 4
+\& [% BLOCK all_change %]
+\& [% x = 20 %] # changes copy
+\& [% y.z = 'zulu' %] # changes original
+\& [% END %]
+.Ve
+.PP
+.Vb 6
+\& [% x = 10
+\& y = { z => 'zebra' }
+\& %]
+\& [% INCLUDE all_change %]
+\& [% x %] # still '10'
+\& [% y.z %] # now 'zulu'
+.Ve
+.PP
+If you create a complex structure such as a hash or list reference
+within a local template context then it will cease to exist when
+the template is finished processing.
+.PP
+.Vb 5
+\& [% BLOCK new_stuff %]
+\& [% # define a new 'y' hash array in local context
+\& y = { z => 'zulu' }
+\& %]
+\& [% END %]
+.Ve
+.PP
+.Vb 4
+\& [% x = 10 %]
+\& [% INCLUDE new_stuff %]
+\& [% x %] # outputs '10'
+\& [% y %] # nothing, y is undefined
+.Ve
+.PP
+Similarly, if you update an element of a compound variable which
+\&\fIdoesn't\fR already exists then a hash will be created automatically
+and deleted again at the end of the block.
+.PP
+.Vb 3
+\& [% BLOCK new_stuff %]
+\& [% y.z = 'zulu' %]
+\& [% END %]
+.Ve
+.PP
+However, if the hash \fIdoes\fR already exist then you will modify the
+original with permanent effect. To avoid potential confusion, it is
+recommended that you don't update elements of complex variables from
+within blocks or templates included by another.
+.PP
+If you want to create or update truly global variables then you can
+use the 'global' namespace. This is a hash array automatically created
+in the top-level namespace which all templates, localised or otherwise
+see the same reference to. Changes made to variables within this
+hash are visible across all templates.
+.PP
+.Vb 1
+\& [% global.version = 123 %]
+.Ve
+.SH "Compile Time Constant Folding"
+.IX Header "Compile Time Constant Folding"
+In addition to variables that get resolved each time a template is
+processed, you can also define variables that get resolved just once
+when the template is compiled. This generally results in templates
+processing faster because there is less work to be done.
+.PP
+To define compile-time constants, specify a \f(CW\*(C`CONSTANTS\*(C'\fR hash as a
+constructor item as per \f(CW\*(C`VARIABLES\*(C'\fR. The \f(CW\*(C`CONSTANTS\*(C'\fR hash can contain any
+kind of complex, nested, or dynamic data structures, just like regular
+variables.
+.PP
+.Vb 13
+\& my $tt = Template\->new({
+\& CONSTANTS => {
+\& version => 3.14,
+\& release => 'skyrocket',
+\& col => {
+\& back => '#ffffff',
+\& fore => '#000000',
+\& },
+\& myobj => My::Object\->new(),
+\& mysub => sub { ... },
+\& joint => ', ',
+\& },
+\& });
+.Ve
+.PP
+Within a template, you access these variables using the \f(CW\*(C`constants\*(C'\fR
+namespace prefix.
+.PP
+.Vb 2
+\& Version [% constants.version %] ([% constants.release %])
+\& Background: [% constants.col.back %]
+.Ve
+.PP
+When the template is compiled, these variable references are replaced
+with the corresponding value. No further variable lookup is then
+required when the template is processed.
+.PP
+You can call subroutines, object methods, and even virtual methods on
+constant variables.
+.PP
+.Vb 3
+\& [% constants.mysub(10, 20) %]
+\& [% constants.myobj(30, 40) %]
+\& [% constants.col.keys.sort.join(', ') %]
+.Ve
+.PP
+One important proviso is that any arguments you pass to subroutines
+or methods must also be literal values or compile time constants.
+.PP
+For example, these are both fine:
+.PP
+.Vb 2
+\& # literal argument
+\& [% constants.col.keys.sort.join(', ') %]
+.Ve
+.PP
+.Vb 2
+\& # constant argument
+\& [% constants.col.keys.sort.join(constants.joint) %]
+.Ve
+.PP
+But this next example will raise an error at parse time because
+\&\f(CW\*(C`joint\*(C'\fR is a runtime variable and cannot be determined at compile
+time.
+.PP
+.Vb 2
+\& # ERROR: runtime variable argument!
+\& [% constants.col.keys.sort.join(joint) %]
+.Ve
+.PP
+The \f(CW\*(C`CONSTANTS_NAMESPACE\*(C'\fR option can be used to provide a different
+namespace prefix for constant variables. For example:
+.PP
+.Vb 7
+\& my $tt = Template\->new({
+\& CONSTANTS => {
+\& version => 3.14,
+\& # ...etc...
+\& },
+\& CONSTANTS_NAMESPACE => 'const',
+\& });
+.Ve
+.PP
+Constants would then be referenced in templates as:
+.PP
+.Vb 1
+\& [% const.version %]
+.Ve
+.SH "Special Variables"
+.IX Header "Special Variables"
+A number of special variables are automatically defined by the Template
+Toolkit.
+.Sh "template"
+.IX Subsection "template"
+The \f(CW\*(C`template\*(C'\fR variable contains a reference to the main template being
+processed, in the form of a Template::Document object. This variable is
+correctly defined within \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR
+templates, allowing standard headers, footers, etc., to access metadata items
+from the main template. The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`modtime\*(C'\fR metadata items are
+automatically provided, giving the template name and modification time in
+seconds since the epoch.
+.PP
+Note that the \f(CW\*(C`template\*(C'\fR variable always references the top-level
+template, even when processing other template components via \f(CW\*(C`INCLUDE\*(C'\fR,
+\&\f(CW\*(C`PROCESS\*(C'\fR, etc.
+.Sh "component"
+.IX Subsection "component"
+The \f(CW\*(C`component\*(C'\fR variable is like \f(CW\*(C`template\*(C'\fR but always contains a
+reference to the current, innermost template component being processed.
+In the main template, the \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variable will
+reference the same Template::Document object. In any other template
+component called from the main template, the \f(CW\*(C`template\*(C'\fR variable
+will remain unchanged, but \f(CW\*(C`component\*(C'\fR will contain a new reference
+to the current component.
+.PP
+This example should demonstrate the difference:
+.PP
+.Vb 2
+\& $template\->process('foo')
+\& || die $template\->error(), "\en";
+.Ve
+.PP
+\&\fIfoo\fR template:
+.PP
+.Vb 3
+\& [% template.name %] # foo
+\& [% component.name %] # foo
+\& [% PROCESS footer %]
+.Ve
+.PP
+\&\fIfooter\fR template:
+.PP
+.Vb 2
+\& [% template.name %] # foo
+\& [% component.name %] # footer
+.Ve
+.PP
+Additionally, the \f(CW\*(C`component\*(C'\fR variable has two special fields:
+\&\f(CW\*(C`caller\*(C'\fR and \f(CW\*(C`callers\*(C'\fR. \f(CW\*(C`caller\*(C'\fR contains the name of the template
+that called the current template (or undef if the values of \f(CW\*(C`template\*(C'\fR
+and \f(CW\*(C`component\*(C'\fR are the same). \f(CW\*(C`callers\*(C'\fR contains a reference to a
+list of all the templates that have been called on the road to calling
+the current component template (like a call stack), with the
+outer-most template first.
+.PP
+Here's an example:
+.PP
+\&\fIouter.tt2\fR template:
+.PP
+.Vb 4
+\& [% component.name %] # 'outer.tt2'
+\& [% component.caller %] # undef
+\& [% component.callers %] # undef
+\& [% PROCESS 'middle.tt2' %]
+.Ve
+.PP
+\&\fImiddle.tt2\fR template:
+.PP
+.Vb 4
+\& [% component.name %] # 'middle.tt2'
+\& [% component.caller %] # 'outer.tt2'
+\& [% component.callers %] # [ 'outer.tt2' ]
+\& [% PROCESS 'inner.tt2' %]
+.Ve
+.PP
+\&\fIinner.tt2\fR template:
+.PP
+.Vb 3
+\& [% component.name %] # 'inner.tt2'
+\& [% component.caller %] # 'middle.tt2'
+\& [% component.callers %] # [ 'outer.tt2', 'middle.tt2' ]
+.Ve
+.Sh "loop"
+.IX Subsection "loop"
+Within a \f(CW\*(C`FOREACH\*(C'\fR loop, the \f(CW\*(C`loop\*(C'\fR variable references the
+Template::Iterator object responsible for controlling the loop.
+.PP
+.Vb 4
+\& [% FOREACH item = [ 'foo', 'bar', 'baz' ] \-%]
+\& [% "Items:\en" IF loop.first \-%]
+\& [% loop.count %]/[% loop.size %]: [% item %]
+\& [% END %]
+.Ve
+.Sh "error"
+.IX Subsection "error"
+Within a \f(CW\*(C`CATCH\*(C'\fR block, the \f(CW\*(C`error\*(C'\fR variable contains a reference to the
+Template::Exception object thrown from within the \f(CW\*(C`TRY\*(C'\fR block. The
+\&\f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR methods can be called or the variable itself can
+be printed for automatic stringification into a message of the form
+"\f(CW\*(C`$type error \- $info\*(C'\fR". See Template::Exception for further details.
+.PP
+.Vb 5
+\& [% TRY %]
+\& ...
+\& [% CATCH %]
+\& [% error %]
+\& [% END %]
+.Ve
+.Sh "content"
+.IX Subsection "content"
+The \f(CW\*(C`WRAPPER\*(C'\fR method captures the output from a template block and then
+includes a named template, passing the captured output as the 'content'
+variable.
+.PP
+.Vb 4
+\& [% WRAPPER box %]
+\& Be not afeard; the isle is full of noises,
+\& Sounds and sweet airs, that give delight and hurt not.
+\& [% END %]
+.Ve
+.PP
+.Vb 5
+\& [% BLOCK box %]
+\& <blockquote class="prose">
+\& [% content %]
+\& </blockquote>
+\& [% END %]
+.Ve
+.SH "Compound Variables"
+.IX Header "Compound Variables"
+Compound 'dotted' variables may contain any number of separate
+elements. Each element may evaluate to any of the permitted variable
+types and the processor will then correctly use this value to evaluate
+the rest of the variable. Arguments may be passed to any of the
+intermediate elements.
+.PP
+.Vb 1
+\& [% myorg.people.sort('surname').first.fullname %]
+.Ve
+.PP
+Intermediate variables may be used and will behave entirely as expected.
+.PP
+.Vb 2
+\& [% sorted = myorg.people.sort('surname') %]
+\& [% sorted.first.fullname %]
+.Ve
+.PP
+This simplified dotted notation has the benefit of hiding the
+implementation details of your data. For example, you could implement
+a data structure as a hash array one day and then change it to an
+object the next without requiring any change to the templates.
projects / catagits/Gitalist.git / blobdiff