#============================================================= -*-perl-*-
#
# Template.pod
#
# DESCRIPTION
#   This is the main documentation for the Template module and the 
#   Template Toolkit as a whole.  It is constructed automatically 
#   during the 'make dist' process from the document fragments in 
#   the doc/src distribution sub-directory.  
#
#   **************************** IMPORTANT ****************************
#     Any changes to this document should be made to the files in the 
#     doc/src directory and not the lib/Template.pod file itself.
#   *******************************************************************
#
# AUTHOR
#   Andy Wardley   <abw@kfs.org>
#
# COPYRIGHT
#   Copyright (C) 1996-2000 Andy Wardley.  All Rights Reserved.
#   Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
#
#   This module is free software; you can redistribute it and/or
#   modify it under the same terms as Perl itself.
#
#------------------------------------------------------------------------
#
#   $Id: Template.pod,v 2.6 2000/12/01 15:29:34 abw Exp $
#
#========================================================================



=head1 NAME

Template Toolkit - a fast, flexible and extensible template processing system

=head1 SYNOPSIS 

  use Template;

  # 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
  };

  # create Template object
  my $template = Template->new($config);

  # define template variables for replacement
  my $vars = {
      var1  => $value,
      var2  => \%hash,
      var3  => \@list,
      var4  => \&code,
      var5  => $object,
  };

  # specify input filename, or file handle, text reference, etc.
  my $input = 'myfile.html';

  # process input template, substituting variables
  $template->process($input, $vars)
      || die $template->error();

=head1  SUMMARY OF TEMPLATE DIRECTIVES

  GET       - evaluate and print a variable or value
	      [%   GET variable %]    # 'GET' keyword is optional
              [%       variable %]
              [%       hash.key %]
              [%         list.n %]
              [%     code(args) %]
	      [% obj.meth(args) %]
              [%  "value: $var" %]

  CALL      - as above without printing result (e.g. call code)
	      [%  CALL variable %]

  SET       - assign a value to a variable
	      [% 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, ... }
              %]

  DEFAULT   - as SET above, if variable(s) not set
              [% DEFAULT variable = value %]

  INSERT    - insert a file without any processing
	      [% INSERT legalese.txt %]

  INCLUDE   - process another template file/block, localising vars
              [% INCLUDE template %]
              [% INCLUDE template  var = val, ... %]

  PROCESS   - as above, without localising variables
              [% PROCESS template %]
              [% PROCESS template  var = val, ... %]

  WRAPPER   - process a template to enclose specified block
	      [% WRAPPER template %]
		 content
	      [% END %]

  BLOCK     - define a named template block for INCLUDE, etc.
              [% BLOCK template %]
                 content
	      [% END %]

  FOREACH   - repeat block for each value in a list
	      [% FOREACH variable = [ val, val, val ] %]
              [% FOREACH variable = list %]
              [% FOREACH list %]
                 content...
                 [% variable %]
              [% END %]

  WHILE     - iterate while condition is true
              [% WHILE condition %]
	         content
	      [% END %]

  IF / UNLESS / ELSIF / ELSE
	    - process block if condition is true/false.
              [% IF condition %]
                 content
  	      [% ELSIF condition %]
		 content
	      [% ELSE %]
		 content
              [% END %]

              [% UNLESS condition %]
                 content
              [% # ELSIF/ELSE as per IF, above %]
	         content
              [% END %]

  SWITCH / CASE
	    - multi-way switch/case statement
	      [% SWITCH variable %]
              [% CASE val1 %]
                 content
              [% CASE [ val2, val3 ] %]
                 content
              [% CASE %]         # or [% CASE DEFAULT %]
                 content
              [% END %]

  MACRO     - create a named macro for some other directive or block
              [% MACRO name <directive> %]
	      [% MACRO name(arg1, arg2) <directive> %]
	      ...
	      [% name %]
              [% name(val1, val2) %]

  FILTER    - post-process block through a filter
              [% FILTER name %]
              [% FILTER name( params ) %]
              [% FILTER alias = name( params ) %]
                 content
              [% END %]

  USE       - load a "plugin" module (or any regular Perl module 
              with LOAD_PERL option)
              [% USE name %]
              [% USE name( params ) %] 
              [% USE var = name( params ) %]
              ...
              [% name.method %]
              [% var.method %]

  PERL / RAWPERL
            - evaluate blocks of Perl code (requires EVAL_PERL option)
              [% PERL %]
		 # perl code goes here
		 $stash->set('foo', 10);
		 print "set 'foo' to ", $stash->get('foo'), "\n";
		 print $context->include('footer', { var => $val });
              [% END %]

	      [% RAWPERL %]
                 # raw perl code goes here, no magic but fast.
	         $output .= 'some output';
	      [% END %]

  TRY / THROW / CATCH / FINAL
            - exception handling
	      [% 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 %]

  NEXT      - next item in a FOREACH/WHILE loop
              [% NEXT %]
     
  LAST      - break out of FOREACH/WHILE loop
              [% LAST %]
     
  RETURN    - stop processing current template
              [% RETURN %]

  STOP      - stop processing all templates and return to caller
              [% STOP %]

  COMMENT   - ignored and deleted
              [% # this is a comment to the end of line
                 foo = 'bar'
              %]

              [%# placing the '#' immediately inside the directive
                  tag comments out the entire directive
              %]

  TAGS      - define new tag style or characters (default: [% %])
              [% TAGS html %]
              [% TAGS <!-- --> %]

=head1 VERSION

This is version 2.00 of the Template Toolkit.  

Please consult the F<Changes> file for information about visible changes
in the Template Toolkit between releases.  The F<TODO> file contains 
details of known bugs, planned enhancements, features, fixes, etc.

The latest version of the Template Toolkit can be downloaded from any 
CPAN site in the directory:

    /modules/by-module/Template/

For a list of CPAN sites, see:

    http://www.cpan.org/

Information regarding interim and development versions is posted to the
templates mailing list and available from the Template Toolkit web site:

    http://www.template-toolkit.org/

=head1 DESCRIPTION

The Template Toolkit is a collection of modules which implement a
fast, flexible, powerful and extensible template processing system.
It was originally designed and remains primarily useful for generating
dynamic web content, but it can be used equally well for processing
any kind of text documents.  This POD documentation is all generated
using the Template Toolkit batch mode utility F<ttree>, for example.

At the simplest level it provides an easy way to process template
files, filling in embedded variable references with their equivalent
values.

    Dear [% name %],

    It has come to our attention that your account is in 
    arrears to the sum of [% debt %].

    Please settle your account before [% deadline %] or we 
    will be forced to revoke your Licence to Thrill.

    The Management.

By default, template directives are embedded within the character
sequences '[%' ... '%]' but you can change these and various other
options to configure how the Template Toolkit looks, feels and works.
You can set the INTERPOLATE option, for example, if you prefer to
embed your variables in Perl style:

    Dear $name,

    It has come to our attention that your account is in 
    arrears to the sum of $debt.
    ...

The Template.pm module is the front end to the Template Toolkit,
providing access to the full range of functionality through a single
module with a simple interface.  It loads the other modules as
required and instantiates a default set of objects to handle
subsequent template processing requests.  Configuration parameters may
be passed to the Template.pm constructor, new(), which are then used
to configure the underlying objects.

    use Template;

    my $tt = Template->new({
	INCLUDE_PATH => '/usr/local/templates',
	INTERPOLATE  => 1,
    }) || die "$Template::ERROR\n";

The Template object implements a process() method for processing template
files or text.  The name of the input template (or various other sources) 
is passed as the first argument, followed by a reference to a hash array 
of variable definitions for substitution in the template.

    my $vars = {
	name     => 'Count Edward van Halen',
	debt     => '3 riffs and a solo',
	deadline => 'the next chorus',
    };

    $template->process('letters/overdrawn', $vars)
	|| die $template->error(), "\n";


The process() method returns true (1) on success and prints the
template output to STDOUT, by default.  On error, the process() method
returns false (undef).  The error() method can then be called to
retrieve details of the error.

A number of special directives are provided, such as INSERT, INCLUDE
and PROCESS, which allow content to be built up from smaller template
components.  This permits a modular approach to building a web site or
other content repository, promoting reusability, cross-site
consistency, ease of construction and subsequent maintenance.  Common
elements such as headers, footers, menu bars, tables, and so on, can
be created as separate template files which can then be processed into
other documents as required.  All defined variables are inherited by
these templates along with any additional "local" values specified.

    [% PROCESS header 
         title = "The Cat Sat on the Mat"
    %]

    [% PROCESS menu %]

    The location of the missing feline has now been established.
    Thank you for your assistance.

    [% INSERT legal/disclaimer %]

    [% PROCESS footer %]

You can also define a template as a BLOCK within the same file and
PROCESS it just like any other template file.  This can be invaluable
for building up repetitive elements such as tables, menus, etc.

    [% BLOCK tabrow %]
       <tr><td>[% name %]</td><td>[% email %]</td></tr>
    [% END %]

    <table>
    [% PROCESS tabrow name="tom"   email="tom@here.org"    %]
    [% PROCESS tabrow name="dick"  email="disk@there.org"  %]
    [% PROCESS tabrow name="larry" email="larry@where.org" %]
    </table>

One of the key features that sets the Template Toolkit apart from
other template processors is the ability to bind template variables to
any kind of Perl data: scalars, lists, hash arrays, sub-routines and
objects.

    my $vars = {
	root   => 'http://here.com/there',
	menu   => [ 'modules', 'authors', 'scripts' ],
	client => {
	    name => 'Doctor Joseph von Satriani',
	    id   => 'JVSAT',
	},
	checkout => sub { my $total = shift; ...; return $something },
	shopcart => My::Cool::Shopping::Cart->new(),
    };

The Template Toolkit will automatically Do The Right Thing to access
the data in an appropriate manner to return some value which can then
be output.  The dot operator '.' is used to accesses into lists and
hashes or to call object methods.  The FOREACH directive is provided for
iterating through lists, and various logicial tests are available using
directives such as IF, UNLESS, ELSIF, ELSE, SWITCH, CASE, etc.

    [% FOREACH section = menu %]
       <a href="[% root %]/[% section %]/index.html">[% section %]</a>
    [% END %]

    <b>Client</a>: [% client.name %] (id: [% client.id %])
    
    [% IF shopcart.nitems %]
       Your shopping cart contains the following items:
       <ul>
       [% FOREACH item = shopcart.contents %]
	  <li>[% item.name %] : [% item.qty %] @ [% item.price %]
       [% END %]
       </ul>

       [% checkout(shopcart.total) %]

    [% ELSE %]
       No items currently in shopping cart.
    [% END %]

The Template Toolkit also provides a number of additional directives
for advanced processing and programmatical functionality.  It supports
output filters (FILTER), allows custom macros to be defined (MACRO),
has a fully-featured exception handling system (TRY, THROW, CATCH,
FINAL) and supports a plugin architecture (USE) which allows special
plugin modules and even regular Perl modules to be loaded and used
with the minimum of fuss.  The Template Toolkit is "just" a template
processor but you can trivially extend it to incorporate the
functionality of any Perl module you can get your hands on.  Thus, it
is also a scalable and extensible template framework, ideally suited
for managing the presentation layer for application servers, content
management systems and other web applications.

Rather than embedding Perl code or some other scripting language
directly into template documents, it encourages you to keep functional
components (i.e. Perl code) separate from presentation components
(e.g. HTML templates).  The template variables provide the interface
between the two layers, allowing data to be generated in code and then
passed to a template component for displaying (pipeline model) or for
sub-routine or object references to be bound to variables which can
then be called from the template as and when required (callback
model).  

The directives that the Template Toolkit provide implement their own
mini programming language, but they're not really designed for
serious, general purpose programming.  Perl is a far more appropriate
language for that.  If you embed application logic (e.g. Perl or other
scripting language fragments) in HTML templates then you risk losing
the clear separation of concerns between functionality and
presentation.  It becomes harder to maintain the two elements in
isolation and more difficult, if not impossible, to reuse code or
presentation elements by themselves.  It is far better to write your
application code in separate Perl modules, libraries or scripts and
then use templates to control how the resulting data is presented as
output.  Thus you should think of the Template Toolkit language as a
set of layout directives for displaying data, not calculating it.

Having said that, the Template Toolkit doesn't force you into one
approach or the other.  It attempts to be pragmatic rather than
dogmatic in allowing you to do whatever best gets the job done.
Thus, if you enable the EVAL_PERL option then you can happily embed
real Perl code in your templates within PERL ... END directives.

The Template Toolkit uses a fast YACC-like parser which compiles
templates into Perl code for maximum runtime efficiency.  It also has
an advanced caching mechanism which manages in-memory and on-disk
(i.e. persistant) versions of compiled templates.  The modules that
comprise the toolkit are highly configurable and the architecture
around which they're built is designed to be extensible.  The Template
Toolkit provides a powerful framework around which content creation
and delivery systems can be built while also providing a simple
interface through the Template front-end module for general use.

=head1 METHODS

=head2 new(\%config)

The new() constructor method (implemented by the Template::Base base
class) instantiates a new Template object.  A reference to a hash
array of configuration items may be passed as a parameter.

    my $tt = Template->new({
	INCLUDE_PATH => '/usr/local/templates',
	EVAL_PERL    => 1,
    }) || die $Template::ERROR, "\n";

A reference to a new Template object is returned, or undef on error.
In the latter case, the error message can be retrieved by calling
error() as a class method (e.g. C<Template-E<gt>error()>) or by
examining the $ERROR package variable directly
(e.g. C<$Template::ERROR>).

    my $tt = Template->new(\%config)
        || die Template->error(), "\n";

    my $tt = Template->new(\%config)
        || die $Template::ERROR, "\n";

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.

    my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
	|| die $Template::ERROR, "\n";

=head2 process($template, \%vars, $output)

The process() method is called to process a template.  The first
parameter indicates the input template as one of: a filename relative
to INCLUDE_PATH, if defined; a reference to a text string containing
the template text; or a file handle reference (e.g. IO::Handle or
sub-class) or GLOB (e.g. \*STDIN), 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.

    $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]";

    # filename
    $tt->process('welcome.tt2')
        || die $tt->error(), "\n";

    # text reference
    $tt->process(\$text)
        || die $tt->error(), "\n";

    # GLOB
    $tt->process(\*DATA)
        || die $tt->error(), "\n";

    __END__
    [% INCLUDE header %]
    This is a template defined in the __END__ section which is 
    accessible via the DATA "file handle".
    [% INCLUDE footer %]

By default, the processed template output is printed to STDOUT.  The
process() method then returns 1 to indicate success.  A third
parameter may be passed to the process() 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 OUTPUT_PATH, if defined)
and the output written to; a file GLOB 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
'print' method (e.g. IO::Handle, Apache::Request, etc.) which will 
be called, passing the generated output as a parameter.

Examples:

    # output filename
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";

    # reference to output subroutine
    sub myout {
	my $output = shift;
	...
    }
    $tt->process('welcome.tt2', $vars, \&myout)
        || die $tt->error(), "\n";

    # reference to output text string
    my $output = '';
    $tt->process('welcome.tt2', $vars, \$output)
        || die $tt->error(), "\n";
    
    print "output: $output\n";

In an Apache/mod_perl handler:

    sub handler {
	my $req = shift;

        ...

	# 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;
    }

The OUTPUT configuration item can be used to specify a default output 
location other than \*STDOUT.  The OUTPUT_PATH specifies a directory
which should be prefixed to all output locations specified as filenames.

    my $tt = Template->new({
	OUTPUT      => sub { ... },       # default
	OUTPUT_PATH => '/tmp',
	...
    }) || die Template->error(), "\n";

    # use default OUTPUT (sub is called)
    $tt->process('welcome.tt2', $vars)
        || die $tt->error(), "\n";

    # write file to '/tmp/welcome.html'
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";

The process() method returns 1 on success or undef on error.  The error
message generated in the latter case can be retrieved by calling the
error() method.  See also L<CONFIGURATION OPTIONS> which describes how
error handling may be further customised.

=head2 error()

When called as a class method, it returns the value of the $ERROR package
variable.  Thus, the following are equivalent.

    my $tt = Template->new()
        || die Template->error(), "\n";

    my $tt = Template->new()
        || die $Template::ERROR, "\n";

When called as an object method, it returns the value of the internal
_ERROR variable, as set by an error condition in a previous call to
process().

    $tt->process('welcome.tt2')
        || die $tt->error(), "\n";

Errors are represented in the Template Toolkit by objects of the
Template::Exception class.  If the process() method returns a false
value then the error() method can be called to return an object of
this class.  The type() and info() methods can called on the object to
retrieve the error type and information string, respectively.  The
as_string() method can be called to return a string of the form "$type
- $info".  This method is also overloaded onto the stringification
operator allowing the object reference itself to be printed to return
the formatted error string.

    $tt->process('somefile') || do {
	my $error = $tt->error();
	print "error type: ", $error->type(), "\n";
	print "error info: ", $error->info(), "\n";
	print $error, "\n";
    };

=head2 service()

The Template module delegates most of the effort of processing templates
to an underlying Template::Service object.  This method returns a reference
to that object.

=head2 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 $template->service->context();

=head1 TEMPLATE SYNTAX

By default, template directives are embedded within the character sequences
'[%' and '%]'.  e.g.

    [% PROCESS header %]
  
    <h1>Hello World!</h1>
    <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
  
    [% PROCESS footer %]

You can change the tag characters using the START_TAG, END_TAG and
TAG_STYLE configuration options.  You can also use the TAGS directive
to define a new tag style for the current template file.

Directives may be embedded anywhere in a line of text and can be split
across several lines.  Insignificant whitespace is generally ignored
within the directive.

    [% INCLUDE header		   
       title = 'Hello World' 
       bgcol = '#ffffff' 
    %]
  
    [%INCLUDE menu align='right'%]
  
    Name: [% name %]  ([%id%])

You can also set the INTERPOLATE option to allow simple variable
references to be embedded directly in templates, prefixed by a '$'.

    # INTERPOLATE => 0
    <td>[% name %]</td>  <td>[% email %]</td>

    # INTERPOLATE => 1
    <td>$name</td>  <td>$email</td>

The '#' character is used to indicate comments within a directive.
When placed immediately inside the opening directive tag, it causes
the entire directive to be ignored.

    [%# this entire directive is ignored no
        matter how many lines it wraps onto
    %]

In any other position, it causes the remainder of the current line to 
be treated as a comment.

    [% # this is a comment
       theta = 20      # so is this
       rho   = 30      # <aol>me too!</aol>
    %]

You can add '-' or '+' to the immediate start or end of a directive
tag to control the whitespace chomping options.  See the PRE_CHOMP and
POST_CHOMP options for further details.

    [% BLOCK foo -%]		# remove trailing newline
    This is block foo
    [%- END %]			# remove leading newline

The simplest directives are GET and SET which retrieve and update
variable values respectively.  The GET and SET keywords are actually
optional as the parser is smart enough to see them for what they
really are (but note the caveat below on using side-effect notation).
Thus, you'll generally see:

    [% SET foo = 10 %]
    [% GET foo %]

written as:

    [% foo = 10 %]
    [% foo %]

You can also express simple logical statements as implicit GET directives:

    [% title or template.title or 'Default Title' %]

    [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]

All other directives should start with a keyword specified in UPPER
CASE (but see the ANYCASE option).  All directives keywords are in
UPPER CASE to make them visually distinctive and to distinguish them
from variables of the same name but different case.  It is perfectly
valid, for example, to define a variable called 'stop' which is
entirely separate from the STOP directive.

    [% stop = 'Clackett Lane Bus Depot' %]

    The bus will next stop at [% stop %]    # variable

    [% STOP %]                              # directive

Directives such as FOREACH, WHILE, BLOCK, FILTER, etc., mark the start
of a block which may contain text or other directives up to the
matching END directive.  Blocks may be nested indefinately.  The
IF, UNLESS, ELSIF and ELSE directives also define blocks and may be
grouped together in the usual manner.

    [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
       * Item: [% item %]
    [% END %]
  
    [% BLOCK footer %]
       Copyright 2000 [% me %]
       [% INCLUDE company/logo %]
    [% END %]
  
    [% IF foo %]
       [% FOREACH thing = foo.things %]
	  [% thing %]
       [% END %]
    [% ELSIF bar %]
       [% INCLUDE barinfo %]
    [% ELSE %]
       do nothing...
    [% END %]

Block directives can also be used in a convenient side-effect notation.

    [% INCLUDE userinfo FOREACH user = userlist %]

    [% INCLUDE debugtxt msg="file: $error.info" 
         IF debugging %] 

    [% "Danger Will Robinson" IF atrisk %]

versus:

    [% FOREACH user = userlist %]
       [% INCLUDE userinfo %]
    [% END %]

    [% IF debugging %]
       [% INCLUDE debugtxt msg="file: $error.info" %]
    [% END %]

    [% IF atrisk %]
    Danger Will Robinson
    [% END %]

The output of a directive can be captured by simply assigning the directive
to a variable.

    [% headtext = PROCESS header title="Hello World" %]

    [% people = PROCESS userinfo FOREACH user = userlist %]

This can be used in conjunction with the BLOCK directive for defining large 
blocks of text or other content.

    [% poem = BLOCK %]
       The boy stood on the burning deck,
       His fleece was white as snow.
       A rolling stone gathers no moss,
       And Keith is sure to follow.
    [% END %]

Note one important caveat of using this syntax in conjunction with side-effect
notation.  The following directive does not behave as might be expected:

    [% var = 'value' IF some_condition %]

In this case, the directive is interpreted as (spacing added for clarity)

    [% var = IF some_condition %]
       value
    [% END %]

rather than

    [% IF some_condition %]
       [% var = 'value' %]
    [% END %]

The variable is assigned the output of the IF block which returns
'value' if true, but nothing if false.  In other words, the following
directive will always cause 'var' to be cleared.

    [% var = 'value' IF 0 %]

To achieve the expected behaviour, the directive should be written as:

    [% SET var = 'value' IF some_condition %]

Multiple FILTER directives can be chained together in sequence.  They
are called in the order defined, piping the output of one into the 
input of the next.

    [% PROCESS somefile FILTER truncate(100) FILTER html %]

The pipe character, '|', can also be used as an alias for FILTER.

    [% PROCESS somefile | truncate(100) | html %]


Multiple directives can be included within a single tag when delimited
by semi-colons, ';'.  Note however that the TAGS directive must always
be specified in a tag by itself.

    [% IF title; 
          INCLUDE header; 
       ELSE; 
	  INCLUDE other/header  title="Some Other Title";
       END
    %]

versus

    [% IF title %]
       [% INCLUDE header %]
    [% ELSE %]
       [% INCLUDE other/header  title="Some Other Title" %]
    [% END %]

=head1 TEMPLATE VARIABLES

A reference to a hash array may be passed as the second argument to
the process() method, containing definitions of template variables.
The VARIABLES (a.k.a. PRE_DEFINE) option can also be used to pre-define
variables for all templates processed by the object.

    my $tt = Template->new({
	VARIABLES => {
	    version => 3.14,
	    release => 'Sahara',
	},
    });

    my $vars = {
	serial_no => 271828,
    };

    $tt->process('myfile', $vars);

'myfile':

    This is version [% version %] ([% release %]).
    Serial number: [% serial_no %]

output: 

    This is version 3.14 (Sahara)
    Serial number: 271828

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 I<is> significant however, and 'foo',
'Foo' and 'FOO' 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:

    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

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.

Example:

    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'),
    };

template:

    [% article %]

    [% person.id %]: [% person.name %] <[% person.email %]>

    [% primes.first %] - [% primes.last %], including [% primes.3 %]
    [% primes.size %] prime numbers: [% primes.join(', ') %]

    [% wizard %]
    [% wizard('Hocus Pocus!') %]

    [% cgi.param('mode') %]

output:

    The Third Shoe

    314: Mr. Blue <blue@nowhere.org>

    2 - 13, including 7
    6 prime numbers: 2, 3, 5, 7, 11, 13

    Abracadabra!
    Abracadabra! Hocus Pocus!
    
    submit

=head2 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.

    [% article %]

=head2 Hash Array References

Members of hash arrays are accessed by specifying the hash reference
and key separated by the dot '.' operator.

    my $vars = {
  	'home' => 'http://www.myserver.com/homepage.html',
  	'page' => {
  	    'this' => 'mypage.html',
  	    'next' => 'nextpage.html',
  	    'prev' => 'prevpage.html',
  	},
    };
  
template:

    <a href="[% home %]">Home</a>
    <a href="[% page.prev %]">Previous Page</a>
    <a href="[% page.next %]">Next Page</a>

output:

    <a href="http://www.myserver.com/homepage.html">Home</a>
    <a href="prevpage.html">Previous Page</a>
    <a href="nextpage.html">Next Page</a>

Any key in a hash which starts with a '_' or '.' 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
DEBUG option is enabled).

    my $vars = {
	message => 'Hello World!',
	_secret => "On the Internet, no-one knows you're a dog",
	thing   => {
	     public  => 123,
	    _private => 456,
	   '.hidden' => 789,
	},
    };

template:

    [% message %]		# outputs "Hello World!"
    [% _secret %]               # no output
    [% thing.public %]          # outputs "123"
    [% thing._private %]        # no output
    [% thing..hidden %]         # ERROR: unexpected token (..)

To access a hash entry using a key stored in another variable, prefix
the key variable with '$' to have it interpolated before use (see
L<Variable Interpolation>).

    [% pagename = 'next' %]
    [% page.$pagename %]       # same as [% page.next %]

When you assign to a variable that contains multiple namespace 
elements (i.e. it has one or more '.' characters in the name),
any hashes required to represent intermediate namespaces will be 
created automatically.  In this following example, the 'product' 
variable automatically springs into life as a hash array unless
otherwise defined.

    [% product.id    = 'XYZ-2000' 
       product.desc  = 'Bogon Generator'
       product.price = 666 
    %]
   
    The [% product.id %] [% product.desc %] 
    costs $[% product.price %].00

output:

    The XYZ-2000 Bogon Generator 
    costs $666.00

You can use Perl's familiar '{' ... '}' construct to explicitly create
a hash and assign it to a variable.  Note that commas are optional
between key/value pairs and '=' can be used in place of '=>'.

    [% product = {
  	 id    => 'XYZ-2000',
  	 desc  => 'Bogon Generator',
  	 price => 666,
       }
    %]

=head2 List References

Items in lists are also accessed by use of the dot operator.

    my $vars = {
  	'people' => [ 'Tom', 'Dick', 'Larry' ],
    };

template:

    [% people.0 %]			# Tom
    [% people.1 %]			# Dick
    [% people.2 %]			# Larry

The FOREACH directive can be used to iterate through items in a list.

    [% FOREACH person = people %]
    Hello [% person %]
    [% END %]

output:

    Hello Tom
    Hello Dick
    Hello Larry

Lists can be constructed in-situ using the regular anonymous list
'[' ... ']' construct.  Commas between items are optional.

    [% cols = [ 'red', 'green', 'blue' ] %]

    [% FOREACH c = cols %]
       ...

or:

    [% FOREACH c = [ 'red', 'green', 'blue' ] %]
       ...

You can also create simple numerical sequences using the familiar '..'
operator:

    [% n = [ 1 .. 4 ] %]    # n is [ 1, 2, 3, 4 ] 

    [% x = 4
       y = 8
       z = [x..y]           # z is [ 4, 5, 6, 7, 8 ]
    %]

=head2 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.

    my $vars = {
	wizard  => sub { return join(' ', 'Abracadabra!', @_) },
    };	

template:

    [% wizard %]			# Abracadabra!
    [% wizard('Hocus Pocus!') %]	# Abracadabra! Hocus Pocus!


=head2 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.

    use CGI;

    ...

    my $vars = {
	# hard coded CGI params for purpose of example
	cgi  => CGI->new('mode=submit&debug=1'),
    };

template:

    [% FOREACH p = cgi.param %]		# returns list of param keys
    [% p %] => [% cgi.param(p) %]	# fetch each param value
    [% END %]

output:

    mode => submit
    debug => 1

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.  

    [% myobj.method = 10 %]

equivalent to:

    [% myobj.method(10) %]

=head2 Parameters and Return 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.

    my $vars = {
	mycode => sub { return 'received ' . join(', ', @_) },
    };

template:

    [% foo = 10 %]
    [% mycode(foo, 20) %]		# received 10, 20

Named parameters may also be specified.  These are automatically collected
into a single hash array which is passed by reference as the B<last> 
parameter to the sub-routine.  Named parameters can be specified using
either '=>' or '=' and can appear anywhere in the argument list.

    my $vars = {
	myjoin => \&myjoin,
    };

    sub myjoin {
	# look for hash ref as last argument
	my $params = ref $_[-1] eq 'HASH' ? pop : { };
	return join($params->{ joint } || ' + ', @_);
    }

template:

    [% myjoin(10, 20, 30) %]
    [% myjoin(10, 20, 30, joint = ' - ' %]
    [% myjoin(joint => ' * ', 10, 20, 30 %]

output:

    10 + 20 + 30
    10 - 20 - 30
    10 * 20 * 30

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 "callable" but are 
supported for future extensions.  Think of them as "hints" to that 
variable, rather than just arguments passed to a function.

    [% r = 'Romeo' %]
    [% r(100, 99, s, t, v) %]		# outputs "Romeo"

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.

    my $vars = {
	# either is OK, first is recommended
	items1 => sub { return [ 'foo', 'bar', 'baz' ] },
	items2 => sub { return ( 'foo', 'bar', 'baz' ) },
    };

template:

    [% FOREACH i = items1 %]
       ...
    [% END %]

    [% FOREACH i = items2 %]
       ...
    [% END %]

=head2 Error Handling

Errors can be reported from user code by calling die().  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 'error'
variable.

    my $vars = {
	barf => sub { 
	    die "a sick error has occured\n";
	},
    };

template:

    [% TRY %]
       [% barf %]	    # calls sub which throws error via die()
    [% CATCH %]
       [% error.info %]	    # outputs "a sick error has occured\n"
    [% END %]

Error messages thrown via die() are converted to exceptions of type
'undef'.  Exceptions of user-defined types can be thrown by calling
die() with a reference to a Template::Exception object.

    use Template::Exception;

    ...
    
    my $vars = {
	login => sub { 
	    ...
	    die Template::Exception->new('badpwd',
					 'password too silly');
	},
    };

template:

    [% TRY %]
       [% login %]
    [% CATCH badpwd %]
       Bad password: [% error.info %]
    [% CATCH %]
       Some other '[% error.type %]' error: [% error.info %]
    [% END %]

The exception types 'stop' and 'return' are used to implement the 
STOP and RETURN directives.  Throwing an exception as:

    die Template::Exception->new('stop');

has the same effect as the directive:

    [% STOP %]

Subroutines and methods can also raise errors by returning a list or
reference to a list containing the undefined value (undef) followed by
an exception object or error message.  This is supported for backwards
compatability with version 1 but may be deprecated in some future
version.

    my $vars = {
	# currently equivalent
	barf => sub {
	    die "I'm sorry Dave, I can't do that";
	},
	yack => sub {
	    return (undef, "I'm sorry Dave, I can't do that");
	},
    };


=head2 Virtual Variable Methods

The Template Toolkit provides virtual methods for manipulating
variable values.  Most of them are analagous to regular Perl functions
of the same names.  

The following methods can be called against any scalar value:

=over 4 

=item defined

Returns true if the value is defined.

    [% user = get_user(uid) IF uid.defined %]

=item length

Returns the length of the string representation of the item:

    [% IF password.length < 8 %]
       Password too short, dumbass!
    [% END %]

=item repeat(n)

Repeat the string a specified number of times.

    [% name = 'foo' %]
    [% name.repeat(3) %]		# foofoofoo

=item replace(search, replace)

Outputs the string with all instances of the first argument (specified
as a Perl regular expression) with the second.

    [% name = 'foo, bar & baz' %]
    [% name.replace('\W+', '_') %]    # foo_bar_baz

=item search(pattern)

Returns true if the string matches the regular expression pattern passed 
as an argument.

    [% name = 'foo bar baz' %]
    [% name.search('bar') ? 'bar' : 'no bar' %]	    # bar

=item split(pattern)

Calls Perl's split() function to split a string into a list of
strings.

    [% FOREACH dir = mypath.split(':') %]
       [% dir %]
    [% END %]

=back

The following can be called against hash references.

=over 4

=item keys, values, each

The regular hash operators returning lists of keys, values or both.
Note how we use a '$' prefix on the 'key' variable in this example to
have it interpolated (i.e. replaced with its value) before use.

    [% FOREACH key = product.keys %]
       [% key %] => [% product.$key %]
    [% END %]

=item sort, nsort

Return a list of the keys, sorted alphabetically (sort) or numerically
(nsort) according to the corresponding values in the hash.

    [% FOREACH n = phones.sort %]
       [% phones.$n %] is [% n %],
    [% END %]

=item import

The import method can be called on a hash array to import the contents
of another hash array.

    [% hash1 = {
	   foo => 'Foo',
           bar => 'Bar',
       }
       hash2 = {
           wiz => 'Wiz',
           woz => 'Woz',
       }
    %]

    [% hash1.import(hash2) %]
    [% hash1.wiz %]			# Wiz

You can also call the import() method by itself to import a hash array
into the current namespace hash.

    [% user = { id => 'lwall', name => 'Larry Wall' } %]
    [% import(user) %]
    [% id %]: [% name %]		# lwall: Larry Wall

=back

The following virtual methods are provided for lists:

=over 4

=item first, last

Returns the first/last item in the list.  The item is not removed from the 
list.

    [% results.first %] to [% results.last %]

=item size, max

Returns the size of a list (number of elements) and the maximum 
index number (size - 1), respectively.

    [% results.size %] search results matched your query

=item reverse

Returns the items of the list in reverse order.

    [% FOREACH s = scores.reverse %]
       ...
    [% END %]

=item join

Joins the items in the list into a single string, using Perl's join 
function.

    [% items.join(', ') %]

=item sort, nsort

Returns the items in alpha (sort) or numerical (nsort) order.

    [% library = books.sort %]

Where the list contains hash array references, a hash key can be 
passed as an argument to specify the sort field.

    [% library = books.sort('author') %]

=item unshift(item), push(item)

Adds an item to the start/end of a list.

    [% mylist.unshift('prev item') %]
    [% mylist.push('next item')    %]

=item shift, pop

Removes the first/last item from the list and returns it.

    [% first = mylist.shift %]
    [% last  = mylist.pop   %]

=back

The following example demonstrates how an empty list ('folk') can be 
populated with formatted strings by using the push() method in conjunction
with a FOREACH loop.  The resultant list can then be printed using join.

    [% # define some initial data
       people   => [ 
           { id => 'tom',   name => 'Tom'     },
	   { id => 'dick',  name => 'Richard' },
           { id => 'larry', name => 'Larry'   },
       ]

       # define an empty list that list methods can be called against
       folk = [] 
    -%]

    [% folk.push("<a href=\"${person.id}.html\">$person.name</a>")
         FOREACH person = people.sort('name') -%]
    [% folk.join(",\n") %]

Output:

    <a href="larry.html">Larry</a>,
    <a href="dick.html">Richard</a>,
    <a href="tom.html">Tom</a>

You can define your own virtual methods for scalars, lists and hash
arrays.  The Template::Stash package variables $SCALAR_OPS, $LIST_OPS
and $HASH_OPS are references to hash arrays that define these virtual
methods.  HASH_OPS and LIST_OPS methods are subroutines that accept a
hash/list reference as the first item.  SCALAR_OPS are subroutines
that accept a scalar value as the first item.  Any other arguments
specified when the method is called will be passed to the subroutine.

    # load Template::Stash to make method tables visible
    use Template::Stash;

    # define list method to return new list of odd numbers only
    $Template::Stash::LIST_OPS->{ odd } = sub {
	my $list = shift;
	return [ grep { $_ % 2 } @$list ];
    };

template:

    [% primes = [ 2, 3, 5, 7, 9 %] %]
    [% primes.odd.join(', ') %]		# 3, 5, 7, 9

See also the examples in the t/vmeth.t test script.

=head2 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.

    [% myorg.people.sort('surname').first.fullname %]

Intermediate variables may be used and will behave entirely as expected.

    [% sorted = myorg.people.sort('surname') %]
    [% sorted.first.fullname %]

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.

=head2 Variable Interpolation

The Template Toolkit uses '$' consistently to indicate that a variable
should be interpolated in position.  Most frequently, you see this in 
double-quoted strings:

    [% fullname = "$honorific $firstname $surname" %]

Or embedded in plain text when the INTERPOLATE option is set:

    Dear $honorific $firstname $surname,

The same rules apply within directives.  If a variable is prefixed
with a '$' 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.

    [% uid = 'abw' %]
    [% userlist.$uid %]		    # same as 'userlist.abw'

Curly braces can be used to delimit interpolated variable names where
necessary.

    [% userlist.${me.id}.name %]    

Directives such as INCLUDE, PROCESS, etc., that accept a template name
as the first argument, will automatically quote it for convenience.

    [% INCLUDE foo/bar.txt %]

equivalent to:

    [% INCLUDE "foo/bar.txt" %]

To INCLUDE a template whose name is stored in a variable, simply
prefix the variable name with '$' to have it interpolated.

    [% myfile = 'header' %]
    [% INCLUDE $myfile %]

equivalent to:

    [% INCLUDE header %]

Note also that a variable containing a reference to a Template::Document
object can also be processed in this way.

    my $vars = {
	header => Template::Document->new({ ... }),
    };

template:

    [% INCLUDE $header %]

=head2 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.  The same thing happens when you INCLUDE another
template.  The current namespace hash is cloned to prevent any
variable changes made in the included template from interfering with
existing variables.  The PROCESS 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.

    [% BLOCK change_name %]
       [% name = 'bar' %]
    [% END %]

    [% name = 'foo' %] 
    [% INCLUDE change_name %]
    [% name %]			    # foo
    [% PROCESS change_name %]
    [% name %]			    # bar

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.

    [% BLOCK all_change %]
       [% x = 20 %]		    # changes copy
       [% y.z = 'zulu' %]	    # changes original
    [% END %]

    [% x = 10
       y = { z => 'zebra' }
    %]
    [% INCLUDE all_change %]
    [% x %]			    # still '10'
    [% y.z %]			    # now 'zulu'


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.  

    [% BLOCK new_stuff %]
       [% # define a new 'y' hash array in local context
          y = { z => 'zulu' }
       %]
    [% END %]

    [% x = 10 %]
    [% INCLUDE new_stuff %]
    [% x %]			    # outputs '10'
    [% y %]			    # nothing, y is undefined

Similarly, if you update an element of a compound variable which
I<doesn't> already exists then a hash will be created automatically
and deleted again at the end of the block.

    [% BLOCK new_stuff %]
       [% y.z = 'zulu' %]
    [% END %]

However, if the hash I<does> 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.

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.

    [% global.version = 123 %]

=head2 Special Variables

A number of special variables are automatically defined by the Template 
Toolkit.

=over 4

=item template

The 'template' variable contains a reference to the main template
being processed, in the form of a Template::Document object.  This
variable is correctly defined within PRE_PROCESS, PROCESS and
POST_PROCESS templates, allowing standard headers, footers, etc., to
access metadata items from the main template.  The 'name' and
'modtime' metadata items are automatically provided, giving the
template name and modification time in seconds since the epoch.  

Note that the 'template' variable always references the top-level
template, even when processing other template components via INCLUDE,
PROCESS, etc.

=item component

The 'component' variable is like 'template' but always contains a
reference to the current, innermost template component being processed.
In the main template, the 'template' and 'component' variable will 
reference the same Template::Document object.  In any other template
component called from the main template, the 'template' variable 
will remain unchanged, but 'component' will contain a new reference
to the current component.

This example should demonstrate the difference:

    $template->process('foo')
	|| die $template->error(), "\n";

'foo':

    [% template.name %]		    # foo
    [% component.name %]	    # foo
    [% PROCESS footer %]

'footer':

    [% template.name %]		    # foo
    [% component.name %]            # footer

=item loop

Within a FOREACH loop, the 'loop' variable references the Template::Iterator
object responsible for controlling the loop.

    [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
       [% "Items:\n" IF loop.first -%]
       [% loop.count %]/[% loop.size %]: [% item %]
    [% END %]

=item error

Within a CATCH block, the 'error' variable contains a reference to the 
Template::Exception object thrown from within the TRY block.  The 
'type' and 'info' methods can be called or the variable itself can 
be printed for automatic stringification into a message of the form
"$type error - $info".  See L<Template::Exception> for further details.

    [% TRY %]
       ...
    [% CATCH %]
       [% error %]
    [% END %]

=item content

The WRAPPER method captures the output from a template block and then 
includes a named template, passing the captured output as the 'content'
variable.

    [% WRAPPER box %]
    Be not afeard; the isle is full of noises,
    Sounds and sweet airs, that give delight and hurt not.
    [% END %]

    [% BLOCK box %]
    <table border=1>
    <tr>
      <td>
      [% content %]
      </td>
    </tr>
    </table>
    [% END %]

=back

=head1 TEMPLATE DIRECTIVES

=head2 Accessing and Updating Template Variables

=over 4

=item GET

The GET directive retrieves and outputs the value of the named variable.

    [% GET foo %]

The GET keyword is optional.  A variable can be specified in a directive
tag by itself.

    [% foo %]

The variable may take any of the forms described above:

    [% foo %]
    [% bar.baz %]
    [% biz.baz(10) %]
    ...etc...

You can also specify expressions using the logical (and, or, not, ?:) and
mathematic operators (+ - * / % mod div).

    [% template.title or default.title %]

    [% score * 100 %]

    [% order.nitems ? checkout(order.total) : 'no items' %]

The 'div' operator returns the integer result of division.  Both '%' and 
'mod' return the modulus (i.e. remainder) of division.  'mod' is provided
as an alias for '%' for backwards compatability with version 1.

    [% 15 / 6 %]	    # 2.5
    [% 15 div 6 %]	    # 2
    [% 15 mod 6 %]	    # 3

=item CALL

The CALL directive is similar to GET in evaluating the variable named,
but doesn't print the result returned.  This can be useful when a
variable is bound to a sub-routine or object method which you want to
call but aren't interested in the value returned.

    [% CALL dbi.disconnect %]

    [% CALL inc_page_counter(page_count) %]

=item SET

The SET directive allows you to assign new values to existing variables
or create new temporary variables.

    [% SET title = 'Hello World' %]

The SET keyword is also optional.
   
    [% title = 'Hello World' %]

Variables may be assigned the values of other variables, unquoted
numbers (digits), literal text ('single quotes') or quoted text
("double quotes").  In the latter case, any variable references within
the text will be interpolated when the string is evaluated.  Variables
should be prefixed by '$', using curly braces to explicitly scope
the variable name where necessary.

    [% foo  = 'Foo'  %]               # literal value 'Foo'
    [% bar  =  foo   %]               # value of variable 'foo'
    [% cost = '$100' %]               # literal value '$100'
    [% item = "$bar: ${cost}.00" %]   # value "Foo: $100.00"

Multiple variables may be assigned in the same directive and are 
evaluated in the order specified.  Thus, the above could have been 
written:

    [% foo  = 'Foo'
       bar  = foo
       cost = '$100'
       item = "$bar: ${cost}.00"
    %]

Simple expressions can also be used, as per GET.

    [% ten    = 10 
       twenty = 20
       thirty = twenty + ten
       forty  = 2 * twenty 
       fifty  = 100 div 2
       six    = twenty mod 7
    %]

=item DEFAULT

The DEFAULT directive is similar to SET but only updates variables 
that are currently undefined or have no "true" value (in the Perl
sense).

    [% DEFAULT
       name = 'John Doe'
       id   = 'jdoe'
    %]

This can be particularly useful in common template components to
ensure that some sensible default are provided for otherwise 
undefined variables.

    [% DEFAULT 
       title = 'Hello World'
       bgcol = '#ffffff'
    %]
    <html>
    <head>
    <title>[% title %]</title>
    </head>

    <body bgcolor="[% bgcol %]">

=back

=head2 Processing Other Template Files and Blocks

=over 4

=item INSERT

The INSERT directive is used to insert the contents of an external file
at the current position.

    [% INSERT myfile %]

No attempt to parse or process the file is made.  The contents,
possibly including any embedded template directives, are inserted
intact.

The filename specified should be relative to one of the INCLUDE_PATH
directories.  Absolute (i.e. starting with C</>) and relative
(i.e. starting with C<.>) filenames may be used if the ABSOLUTE and
RELATIVE options are set, respectively.  Both these options are
disabled by default.

    my $template = Template->new({
	INCLUDE_PATH => '/here:/there',
    });

    $template->process('myfile');

'myfile':

    [% INSERT foo %]		# looks for /here/foo then /there/foo
    [% INSERT /etc/passwd %]	# file error: ABSOLUTE not set
    [% INSERT ../secret %]	# file error: RELATIVE not set

For convenience, the filename does not need to be quoted as long as it
contains only alphanumeric characters, underscores, dots or forward
slashes.  Names containing any other characters should be quoted.

    [% INSERT misc/legalese.txt            %]
    [% INSERT 'dos98/Program Files/stupid' %]

To evaluate a variable to specify a filename, you should explicitly
prefix it with a '$' or use double-quoted string interpolation.

    [% language = 'en'
       legalese = 'misc/legalese.txt' 
    %]

    [% INSERT $legalese %]		# 'misc/legalese.txt'
    [% INSERT "$language/$legalese" %]  # 'en/misc/legalese.txt'

=item INCLUDE

The INCLUDE directive is used to process and include the output of
another template file or block.

    [% INCLUDE header %]

If a BLOCK of the specified name is defined in the same file, or in a file 
from which the current template has been called (i.e. a parent template) 
then it will be used in preference to any file of the same name.

    [% INCLUDE table %]		    # uses BLOCK defined below

    [% BLOCK table %]
       <table>
       ...
       </table>
    [% END %]

If a BLOCK definition is not currently visible then the template name
should be a file relative to one of the INCLUDE_PATH directories, or
an absolute or relative file name if the ABSOLUTE/RELATIVE options are
appropriately enabled.  The INCLUDE directive automatically quotes the
filename specified, as per INSERT described above.  When a variable
contains the name of the template for the INCLUDE directive, it should
be explicitly prefixed by '$'.

    [% myheader = 'my/misc/header' %]
    [% INCLUDE  myheader %]              # 'myheader'
    [% INCLUDE $myheader %]		 # 'my/misc/header'

Any template directives embedded within the file will be processed
accordingly.  All variables currently defined will be visible and 
accessible from within the included template.  

    [% title = 'Hello World' %]
    [% INCLUDE header %]
    <body>
    ...

'header':
    <html>
    <title>[% title %]</title>

output:
    <html>
    <title>Hello World</title>
    <body>
    ...

Local variable definitions may be specified after the template name,
temporarily masking any existing variables.  Insignificant whitespace
is ignore within directives so you can add variable definitions on the
same line, the next line or split across several line with comments
interspersed, if you prefer.

    [% INCLUDE table %]

    [% INCLUDE table title="Active Projects" %]

    [% INCLUDE table 
	 title   = "Active Projects" 
         bgcolor = "#80ff00"	# chartreuse
	 border  = 2
    %]

The INCLUDE directive localises (i.e. copies) all variables before
processing the template.  Any changes made within the included
template will not affect variables in the including template.

    [% foo = 10 %]

    foo is originally [% foo %]
    [% INCLUDE bar %]
    foo is still [% foo %]

    [% BLOCK bar %]
       foo was [% foo %]
       [% foo = 20 %]
       foo is now [% foo %]
    [% END %]

output:
    foo is originally 10
       foo was 10
       foo is now 20
    foo is still 10

Technical Note: the localisation of the stash (that is, the process by
which variables are copied before an INCLUDE to prevent being
overwritten) is only skin deep.  The top-level variable namespace
(hash) is copied, but no attempt is made to perform a deep-copy of
other structures (hashes, arrays, objects, etc.)  Therefore, a 'foo'
variable referencing a hash will be copied to create a new 'foo'
variable but which points to the same hash array.  Thus, if you update
compound variables (e.g. foo.bar) then you will change the original
copy, regardless of any stash localisation.  If you're not worried
about preserving variable values, or you trust the templates you're
including then you might prefer to use the PROCESS directive which is
faster by virtue of not performing any localisation.

=item PROCESS

The PROCESS directive is similar to INCLUDE but does not perform any 
localisation of variables before processing the template.  Any changes
made to variables within the included template will be visible in the
including template.

    [% foo = 10 %]

    foo is [% foo %]
    [% PROCESS bar %]
    foo is [% foo %]

    [% BLOCK bar %]
       [% foo = 20 %]
       changed foo to [% foo %]
    [% END %]

output:

    foo is 10
       changed foo to 20
    foo is 20

Parameters may be specified in the PROCESS directive, but these too will 
become visible changes to current variable values.

    [% foo = 10 %]
    foo is [% foo %]
    [% PROCESS bar
       foo = 20 
    %]
    foo is [% foo %]

    [% BLOCK bar %]
       this is bar, foo is [% foo %]
    [% END %]

output:

    foo is 10
       this is bar, foo is 20
    foo is 20

The PROCESS directive is slightly faster than INCLUDE because it
avoids the need to localise (i.e. copy) the variable stash before
processing the template.  As with INSERT and INCLUDE, the first
parameter does not need to be quoted as long as it contains only
alphanumeric characters, underscores, periods or forward slashes.
A '$' prefix can be used to explicitly indicate a variable which 
should be interpolated to provide the template name:

    [% myheader = 'my/misc/header' %]
    [% PROCESS  myheader %]              # 'myheader'
    [% PROCESS $myheader %]		 # 'my/misc/header'

=item WRAPPER

It's not unusual to find yourself adding common headers and footers to 
pages or sub-sections within a page.  Something like this:

    [% INCLUDE section/header
       title = 'Quantum Mechanics'
    %]
       Quantum mechanics is a very interesting subject wish 
       should prove easy for the layman to fully comprehend.
    [% INCLUDE section/footer %]

    [% INCLUDE section/header
       title = 'Desktop Nuclear Fusion for under $50'
    %]
       This describes a simple device which generates significant 
       sustainable electrical power from common tap water by process 
       of nuclear fusion.
    [% INCLUDE section/footer %]

The individual template components being included might look like these:

section/header:
    <p>
    <h2>[% title %]</h2>

section/footer:
    </p>

The WRAPPER directive provides a way of simplifying this a little.  It
encloses a block up to a matching END directive, which is first
processed to generate some output.  This is then passed to the named
template file or BLOCK as the 'content' variable.

    [% WRAPPER section
       title = 'Quantum Mechanics'
    %]
       Quantum mechanics is a very interesting subject wish 
       should prove easy for the layman to fully comprehend.
    [% END %]

    [% WRAPPER section
       title = 'Desktop Nuclear Fusion for under $50'
    %]
       This describes a simple device which generates significant 
       sustainable electrical power from common tap water by process 
       of nuclear fusion.
    [% END %]

The single 'section' template can then be defined as:

    <p>
    <h2>[% title %]</h2>
    [% content %]
    </p>

Like other block directives, it can be used in side-effect notation:

    [% INSERT legalese.txt WRAPPER big_bold_table %]

=item BLOCK

The BLOCK ... END construct can be used to define template component
blocks which can be processed with the INCLUDE, PROCESS and WRAPPER
directives.

    [% BLOCK tabrow %]
    <tr><td>[% name %]<td><td>[% email %]</td></tr>
    [% END %]
  
    <table>
    [% PROCESS tabrow  name='Fred'  email='fred@nowhere.com' %]
    [% PROCESS tabrow  name='Alan'  email='alan@nowhere.com' %]
    </table>

A BLOCK definition can be used before it is defined, as long as the
definition resides in the same file.  The block definition itself does
not generate any output.

    [% PROCESS tmpblk %]

    [% BLOCK tmpblk %] This is OK [% END %]

You can use an anonymous BLOCK to capture the output of a template
fragment.  

    [% julius = BLOCK %]
       And Caesar's spirit, ranging for revenge,
       With Ate by his side come hot from hell,
       Shall in these confines with a monarch's voice
       Cry  'Havoc', and let slip the dogs of war;
       That this foul deed shall smell above the earth
       With carrion men, groaning for burial.
    [% END %]

Like a named block, it can contain any other template directives which 
are processed when the block is defined.  The output generated by the 
block is then assigned to the variable 'julius'.

Anonymous BLOCKs can also be used to define block macros.  The
enclosing block is processed each time the macro is called.

    [% MACRO whereabouts BLOCK %]
       The [% animal %] sat on the [% place %].
    [% END %]

    [% foo(animal='cat', place='mat') %]    # The cat sat on the mat
    [% foo(animal='dog', place='log') %]    # The dog sat on the log

=back

=head2 Conditional Processing

=over 4

=item IF / UNLESS / ELSIF / ELSE

The IF and UNLESS directives can be used to process or ignore a
block based on some run-time condition.  

    [% IF frames %]
       [% INCLUDE frameset %]
    [% END %]

    [% UNLESS text_mode %]
       [% INCLUDE biglogo %]
    [% END %]

Multiple conditions may be joined with ELSIF and/or ELSE blocks.

    [% IF age < 10 %]
       Hello [% name %], does your mother know you're 
       using her AOL account?
    [% ELSIF age < 18 %]
       Sorry, you're not old enough to enter 
       (and too dumb to lie about your age)
    [% ELSE %]
       Welcome [% name %].
    [% END %]

The following conditional and boolean operators may be used:

    == != < <= > >= ! && || and or not

Conditions may be arbitrarily complex and are evaluated with the same
precedence as in Perl.  Parenthesis may be used to explicitly
determine evaluation order.

    # ridiculously contrived complex example
    [% IF (name == 'admin' || uid <= 0) && mode == 'debug' %]
       I'm confused.
    [% ELSIF more > less %]
       That's more or less correct.
    [% END %]

=item SWITCH / CASE

The SWITCH / CASE construct can be used to perform a multi-way
conditional test.  The SWITCH directive expects an expression which is
first evaluated and then compared against each CASE statement in turn.
Each CASE directive should contain a single value or a list of values
which should match.  CASE may also be left blank or written as [% CASE
DEFAULT %] to specify a default match.  Only one CASE matches, there
is no drop-through between CASE statements.
  
    [% SWITCH myvar %]
    [% CASE value1 %]
       ...
    [% CASE [ value2 value3 ] %]   # multiple values
       ...
    [% CASE myhash.keys %]         # ditto
       ...
    [% CASE %]                     # default
       ...
    [% END %]

=back

=head2 Loop Processing

=over 4

=item FOREACH

The FOREACH directive will iterate through the items in a list, processing
the enclosed block for each one.

    my $vars = {
	foo   => 'Foo',
  	items => [ 'one', 'two', 'three' ],
    };
  
template:

    Things:
    [% FOREACH thing = [ foo 'Bar' "$foo Baz" ] %]
       * [% thing %]
    [% END %]
  
    Items:
    [% FOREACH i = items %]
       * [% i %]
    [% END %]
  
    Stuff:
    [% stuff = [ foo "$foo Bar" ] %]
    [% FOREACH s = stuff %]
       * [% s %]
    [% END %]

output:

    Things:
      * Foo
      * Bar
      * Foo Baz
  
    Items:
      * one
      * two
      * three
  
    Stuff:
      * Foo
      * Foo Bar

When the FOREACH directive is used without specifying a target variable, 
any iterated values which are hash references will be automatically 
imported.

    [% userlist = [
	  { id => 'tom',   name => 'Thomas'  },
	  { id => 'dick',  name => 'Richard'  },
	  { id => 'larry', name => 'Lawrence' },
       ]
    %]

    [% FOREACH user = userlist %]
       [% user.id %] [% user.name %]
    [% END %]

short form:

    [% FOREACH userlist %]
       [% id %] [% name %]
    [% END %]

Note that this particular usage creates a localised variable context
to prevent the imported hash keys from overwriting any existing
variables.  The imported definitions and any other variables defined
in such a FOREACH loop will be lost at the end of the loop, when the 
previous context and variable values are restored.

The FOREACH directive can also be used to iterate through the entries
in a hash array.  Each entry in the hash is returned in sorted order
(based on the key) as a hash array containing 'key' and 'value' items.

    [% users = {
	 tom   => 'Thomas',
	 dick  => 'Richard',
         larry => 'Lawrence',
       }
    %]

    [% FOREACH u = users %]
       * [% u.key %] : [% u.value %]
    [% END %]

Output:

       * dick : Richard
       * larry : Lawrence
       * tom : Thomas      

The NEXT directive starts the next iteration in the FOREACH loop.

    [% FOREACH user = userlist %]
       [% NEXT IF user.isguest %]
       Name: [% user.name %]    Email: [% user.email %]
    [% END %]

The LAST directive can be used to prematurely exit the loop.  BREAK is
also provided as an alias for LAST.

    [% FOREACH match = results.nsort('score').reverse %]
       [% LAST IF match.score < 50 %]
       [% match.score %] : [% match.url %]
    [% END %]

The FOREACH directive is implemented using the Template::Iterator
module.  A reference to the iterator object for a FOREACH directive is
implicitly available in the 'loop' variable.  The following methods 
can be called on the 'loop' iterator.

    size()	number of elements in the list
    max()       index number of last element (size - 1)
    index()     index of current iteration from 0 to max()
    count()     iteration counter from 1 to size() (i.e. index() + 1)
    first()     true if the current iteration is the first
    last()      true if the current iteration is the last
    prev()      return the previous item in the list
    next()      return the next item in the list

See L<Template::Iterator> for further details.

Example:

    [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%]
       [%- "<ul>\n" IF loop.first %]
       <li>[% loop.count %]/[% loop.size %]: [% item %]
       [%- "</ul>\n" IF loop.last %]
    [% END %]

Output:

    <ul>
    <li>1/3: foo
    <li>2/3: bar
    <li>3/3: baz
    </ul>

Note that the number() method is supported as an alias for count() for
backwards compatability but may be deprecated in some future version.

Nested loops will work as expected, with the 'loop' variable correctly 
referencing the innermost loop and being restored to any previous 
value (i.e. an outer loop) at the end of the loop.

    [% FOREACH group = grouplist %]
       [% "Groups:\n" IF loop.first %]	      # loop => group iterator
       [% FOREACH user = group.userlist %]
	  [% loop.count %]: [% user.name %]   # loop => user iterator
       [% END %]
       [% "End of Groups\n" IF loop.last %]   # loop => group iterator
    [% END %]

The 'iterator' plugin can also be used to explicitly create an
iterator object.  This can be useful within nested loops where you
need to keep a reference to the outer iterator within the inner loop.
The iterator plugin effectively allows you to create an iterator by a
name other than 'loop'.  See Template::Plugin::Iterator for further
details.

    [% USE giter = iterator(grouplist) %]

    [% FOREACH group = giter %]
       [% FOREACH user = group.userlist %]
       user [% loop.count %] in group [% giter.count %]: [% user.name %]
       [% END %]
    [% END %]

=item WHILE

The WHILE directive can be used to repeatedly process a template block
while a conditional expression evaluates true.  The expression may 
be arbitrarily complex as per IF / UNLESS.

    [% WHILE total < 100 %]
       ...
       [% total = calculate_new_total %]
    [% END %]

An assignment can be enclosed in parenthesis to evaluate the assigned
value.

    [% WHILE (user = get_next_user_record) %]
       [% user.name %]
    [% END %]

The NEXT directive can be used to start the next iteration of a 
WHILE loop and BREAK can be used to exit the loop, both as per FOREACH.

The Template Toolkit uses a failsafe counter to prevent runaway WHILE
loops which would otherwise never terminate.  If the loop exceeds 1000
iterations then an 'undef' exception will be thrown, reporting the
error:

    WHILE loop terminated (> 1000 iterations)

The $Template::Directive::WHILE_MAX variable controls this behaviour
and can be set to a higher value if necessary.

=back

=head2 Filters, Plugins, Macros and Perl

=over 4

=item FILTER

The FILTER directive can be used to post-process the output of a
block.  A number of standard filters are provided with the Template
Toolkit.  The 'html' filter, for example, escapes the 'E<lt>', 'E<gt>'
and '&' characters to prevent them from being interpreted as HTML tags
or entity reference markers.

    [% FILTER html %]
       HTML text may have < and > characters embedded
       which you want converted to the correct HTML entities.
    [% END %]

output:

       HTML text may have &lt; and &gt; characters embedded
       which you want converted to the correct HTML entities.

The FILTER directive can also follow various other non-block directives.
For example:

    [% INCLUDE mytext FILTER html %]

The '|' character can also be used as an alias for 'FILTER'.

    [% INCLUDE mytext | html %]

Multiple filters can be chained together and will be called in sequence.

    [% INCLUDE mytext FILTER html FILTER html_para %]

or

    [% INCLUDE mytext | html | html_para %]

Filters come in two flavours, known as 'static' or 'dynamic'.  A
static filter is a simple subroutine which accepts a text string as
the only argument and returns the modified text.  The 'html' filter is
an example of a static filter, implemented as:

    sub html_filter {
	my $text = shift;
    	for ($text) {
	    s/&/&amp;/g;
	    s/</&lt;/g;
	    s/>/&gt;/g;
    	}
	return $text;
    }

Dynamic filters can accept arguments which are specified when the filter
is called from a template.  The 'repeat' filter is such an example, 
accepting a numerical argument which specifies the number of times
that the input text should be repeated.

    [% FILTER repeat(3) %]blah [% END %]

output:

    blah blah blah

These are implemented as filter 'factories'.  The factory subroutine
is passed a reference to the current Template::Context object along
with any additional arguments specified.  It should then return a
subroutine reference (e.g. a closure) which implements the filter.
The 'repeat' filter factory is implemented like this:

    sub repeat_filter_factory {
	my ($context, $iter) = @_;
	$iter = 1 unless defined $iter;

	return sub {
	    my $text = shift;
	    $text = '' unless defined $text;
	    return join('\n', $text) x $iter;
	}
    }

The FILTERS option, described in L<CONFIGURATION OPTIONS>, allows 
custom filters to be defined when a Template object is instantiated.  
The Template::Context define_filter() method allows further filters
to be defined at any time.

When using a filter, it is possible to assign an alias to it for 
further use.  This is most useful for dynamic filters that you want 
to re-use with the same configuration.

    [% FILTER echo = repeat(2) %]
    Is there anybody out there?
    [% END %]

    [% FILTER echo %]
    Mother, should I build a wall?
    [% END %]

Output:

    Is there anybody out there?
    Is there anybody out there?

    Mother, should I build a wall?
    Mother, should I build a wall?

The FILTER directive automatically quotes the name of the filter.  As
with INCLUDE et al, you can use a variable to provide the name of the 
filter, prefixed by '$'.

    [% myfilter = 'html' %]
    [% FILTER $myfilter %]	# same as [% FILTER html %]
       ...
    [% END %]

A template variable can also be used to define a static filter
subroutine.  However, the Template Toolkit will automatically call any
subroutine bound to a variable and use the value returned.  Thus, the
above example could be implemented as:

    my $vars = {
	myfilter => sub { return 'html' },
    };

template:

    [% FILTER $myfilter %]	# same as [% FILTER html %]
       ...
    [% END %]

To define a template variable that evaluates to a subroutine reference
that can be used by the FILTER directive, you should create a
subroutine that, when called automatically by the Template Toolkit,
returns another subroutine reference which can then be used to perform
the filter operation.  Note that only static filters can be
implemented in this way.

    my $vars = {
	myfilter => sub { \&my_filter_sub },
    };

    sub my_filter_sub {
	my $text = shift;
	# do something
        return $text;
    }

template:

    [% FILTER $myfilter %]
       ...
    [% END %]

Alternately, you can bless a subroutine reference into a class (any
class will do) to fool the Template Toolkit into thinking it's an
object rather than a subroutine.  This will then bypass the automatic
"call-a-subroutine-to-return-a-value" magic.

    my $vars = {
	myfilter => bless(\&my_filter_sub, 'anything_you_like'),
    };

template:

    [% FILTER $myfilter %]	    
       ...
    [% END %]

Filters bound to template variables remain local to the variable
context in which they are defined.  That is, if you define a filter in
a PERL block within a template that is loaded via INCLUDE, then the
filter definition will only exist until the end of that template when
the stash is delocalised, restoring the previous variable state.  If
you want to define a filter which persists for the lifetime of the
processor, or define additional dynamic filter factories, then you can
call the define_filter() method on the current Template::Context
object.

See L<TEMPLATE TOOLKIT FILTERS> for a complete list of available filters,
their descriptions and examples of use.

=item USE

The USE directive can be used to load and initialise "plugin"
extension modules.

    [% USE myplugin %]

A plugin is a regular Perl module that conforms to a particular
object-oriented interface, allowing it to be loaded into and used
automatically by the Template Toolkit.  For details of this interface
and information on writing plugins, consult L<Template::Plugin>. 

The plugin name is case-sensitive and will be appended to the
PLUGIN_BASE value (default: 'Template::Plugin') to construct a full
module name.  Any periods, '.', in the name will be converted to '::'.

    [% USE MyPlugin %]     #  => Template::Plugin::MyPlugin
    [% USE Foo.Bar  %]     #  => Template::Plugin::Foo::Bar

Various standard plugins are included with the Template Toolkit (see 
below and L<TEMPLATE TOOLKIT PLUGINS>).  These can be specified in lower
case and are mapped to the appropriate name.

    [% USE cgi   %]        # => Template::Plugin::CGI
    [% USE table %]        # => Template::Plugin::Table

Any additional parameters supplied in parenthesis after the plugin
name will be also be passed to the new() constructor.  A reference to
the current Template::Context object is always passed as the first
parameter.

    [% USE MyPlugin('foo', 123) %]

equivalent to:

    Template::Plugin::MyPlugin->new($context, 'foo', 123);

Named parameters may also be specified.  These are collated into a
hash which is passed by reference as the last parameter to the
constructor, as per the general code calling interface.

    [% USE url('/cgi-bin/foo', mode='submit', debug=1) %]

equivalent to:

    Template::Plugin::URL->new($context, '/cgi-bin/foo'
			       { mode => 'submit', debug => 1 });

The plugin may represent any data type; a simple variable, hash, list or
code reference, but in the general case it will be an object reference.
Methods can be called on the object (or the relevant members of the
specific data type) in the usual way:

    [% USE table(mydata, rows=3) %]

    [% FOREACH row = table.rows %]
       <tr>    
       [% FOREACH item = row %]
	  <td>[% item %]</td>
       [% END %]
       </tr>
    [% END %]

An alternative name may be provided for the plugin by which it can be 
referenced:

    [% USE scores = table(myscores, cols=5) %]

    [% FOREACH row = scores.rows %]
       ...
    [% END %]

You can use this approach to create multiple plugin objects with
different configurations.  This example shows how the 'format' plugin
is used to create sub-routines bound to variables for formatting text
as per printf().

    [% USE bold = format('<b>%s</b>') %]
    [% USE ital = format('<i>%s</i>') %]

    [% bold('This is bold')   %]
    [% ital('This is italic') %]

Output:

    <b>This is bold</b>
    <i>This is italic</i>

This next example shows how the URL plugin can be used to build
dynamic URLs from a base part and optional query parameters.

    [% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %]
    <a href="[% mycgi %]">...
    <a href="[% mycgi(mode='submit') %]"...

Output:

    <a href="/cgi-bin/foo.pl?debug=1">...
    <a href="/cgi-bin/foo.pl?mode=submit&debug=1">...

The CGI plugin is an example of one which delegates to another Perl
module.  In this this case, it is to Lincoln Stein's CGI.pm module.
All of the methods provided by CGI.pm are available via the plugin.

    [% USE CGI %]

    [% CGI.start_form %]

    [% CGI.checkbox_group(name   =>   'colours', 
                          values => [ 'red' 'green' 'blue' ])
    %]

    [% CGI.popup_menu(name   =>   'items', 
                      values => [ 'foo' 'bar' 'baz' ])
    %]

    [% CGI.end_form %]

Simon Matthews has written the DBI plugin which provides an interface
to Tim Bunce's DBI module (available from CPAN).  Here's a short
example:

    [% USE DBI('DBI:mSQL:mydbname') %]

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% user.id %] [% user.name %] [% user.etc.etc %]
    [% END %]

See L<TEMPLATE TOOLKIT PLUGINS> for more information on the plugins
distributed with the toolkit or available from CPAN.

The LOAD_PERL option (disabled by default) provides a further way by
which external Perl modules may be loaded.  If a regular Perl module
(i.e. not a Template::Plugin::* or other module relative to some
PLUGIN_BASE) supports an object-oriented interface and a new()
constructor then it can be loaded and instantiated automatically.  The
following trivial example shows how the IO::File module might be used.

    [% USE file = IO.File('/tmp/mydata') %]

    [% WHILE (line = file.getline) %]
       <!-- [% line %] -->
    [% END %]

=item MACRO

The MACRO directive allows you to define a directive or directive block
which is then evaluated each time the macro is called. 

    [% MACRO header INCLUDE header %]

Calling the macro as:

    [% header %]

is then equivalent to:

    [% INCLUDE header %]

Macros can be passed named parameters when called.  These values remain 
local to the macro.

    [% header(title='Hello World') %]  

equivlant to:

    [% INCLUDE header title='Hello World' %]

A MACRO definition may include parameter names.  Values passed to the 
macros are then mapped to these local variables.  Other named parameters
may follow these.

    [% MACRO header(title) INCLUDE header %]

    [% header('Hello World') %]
    [% header('Hello World', bgcol='#123456') %]

equivalent to:

    [% INCLUDE header title='Hello World' %]
    [% INCLUDE header title='Hello World' bgcol='#123456# %]

A MACRO may preceed any directive and must conform to the structure 
of the directive.

    [% MACRO header IF frames %]
       [% INCLUDE frames/header %]
    [% ELSE %]
       [% INCLUDE header %]
    [% END %]

    [% header %]

A MACRO may also be defined as an anonymous BLOCK.  The block will be
evaluated each time the macro is called. 

    [% MACRO header BLOCK %]
       ...content...
    [% END %]

    [% header %]

=item PERL

The PERL directive is used to mark the start of a block which contains
Perl code for evaluation.  The EVAL_PERL option must be enabled for Perl
code to be evaluated or a 'perl' exception will be thrown with the 
message 'EVAL_PERL not set'.

Perl code is evaluated in the Template::Perl package.  The $context
package variable contains a reference to the current Template::Context
object.  This can be used to access the functionality of the Template
Toolkit to process other templates, load plugins, filters, etc.
See L<Template::Context> for further details.

    [% PERL %]
       print $context->include('myfile');
    [% END %]

The $stash variable contains a reference to the top-level stash object
which manages template variables.  Through this, variable values can
be retrieved and updated.  See L<Template::Stash> for further details.

    [% PERL %]
       $stash->set(foo => 'bar');
       print "foo value: ", $stash->get('foo');
    [% END %]

Output
    foo value: bar

Output is generated from the PERL block by calling print().  Note that
the Template::Perl::PERLOUT handle is selected (tied to an output
buffer) instead of STDOUT.

    [% PERL %]
       print "foo\n";	                        # OK
       print PERLOUT "bar\n";                   # OK, same as above
       print Template::Perl::PERLOUT "baz\n";   # OK, same as above
       print STDOUT "qux\n";			# WRONG!
    [% END %]

The PERL block may contain other template directives.  These are
processed before the Perl code is evaluated.

    [% name = 'Fred Smith' %]

    [% PERL %]
       print "[% name %]\n";
    [% END %]

Thus, the Perl code in the above example is evaluated as:

    print "Fred Smith\n";

Exceptions may be thrown from within PERL blocks via die() and will be
correctly caught by enclosing TRY blocks.

    [% TRY %]
       [% PERL %]
          die "nothing to live for\n";
       [% END %]
    [% CATCH %]
       error: [% error.info %]
    [% END %]

output:
       error: nothing to live for

=item RAWPERL

The Template Toolkit parser reads a source template and generates the
text of a Perl subroutine as output.  It then uses eval() to evaluate
it into a subroutine reference.  This subroutine is then called to
process the template, passing a reference to the current
Template::Context object through which the functionality of the
Template Toolkit can be accessed.  The subroutine reference can be
cached, allowing the template to be processed repeatedly without
requiring any further parsing.

For example, a template such as:

    [% PROCESS header %]
    The [% animal %] sat on the [% location %]
    [% PROCESS footer %]

is converted into the following Perl subroutine definition:

    sub {
    	my $context = shift;
    	my $stash   = $context->stash;
    	my $output  = '';
    	my $error;
    	
    	eval { BLOCK: {
    	    $output .=  $context->process('header');
    	    $output .=  "The ";
    	    $output .=  $stash->get('animal');
    	    $output .=  " sat on the ";
    	    $output .=  $stash->get('location');
    	    $output .=  $context->process('footer');
    	    $output .=  "\n";
    	} };
    	if ($@) {
    	    $error = $context->catch($@, \$output);
    	    die $error unless $error->type eq 'return';
    	}
    
    	return $output;
    }

To examine the Perl code generated, such as in the above example, set
the $Template::Parser::DEBUG package variable to any true value.  You
can also set the $Template::Directive::PRETTY variable true to have
the code formatted in a readable manner for human consumption.  The
source code for each generated template subroutine will be printed to
STDERR on compilation (i.e. the first time a template is used).

    $Template::Parser::DEBUG = 1;
    $Template::Directive::PRETTY = 1;

    ...

    $template->process($file, $vars)
	|| die $template->error(), "\n";

The PERL ... END construct allows Perl code to be embedded into a
template (when the EVAL_PERL option is set), but it is evaluated at
"runtime" using eval() each time the template subroutine is called.
This is inherently flexible, but not as efficient as it could be,
especially in a persistant server environment where a template may be
processed many times.  

The RAWPERL directive allows you to write Perl code that is integrated
directly into the generated Perl subroutine text.  It is evaluated
once at compile time and is stored in cached form as part of the
compiled template subroutine.  This makes RAWPERL blocks more
efficient than PERL blocks.

The downside is that you must code much closer to the metal.  Within
PERL blocks, you can call print() to generate some output.  RAWPERL
blocks don't afford such luxury.  The code is inserted directly into
the generated subroutine text and should conform to the convention of
appending to the '$output' variable.

    [% PROCESS  header %]

    [% RAWPERL %]
       $output .= "Some output\n";
       ...
       $output .= "Some more output\n";
    [% END %]

The critical section of the generated subroutine for this example would 
then look something like:

    ...
    eval { BLOCK: {
	$output .=  $context->process('header');
        $output .=  "\n";
        $output .= "Some output\n";
	...
        $output .= "Some more output\n";
        $output .=  "\n";
    } };
    ...

As with PERL blocks, the $context and $stash references are pre-defined
and available for use within RAWPERL code.

=back 

=head2 Exception Handling and Flow Control

=over 4

=item TRY / THROW / CATCH / FINAL

The Template Toolkit supports fully functional, nested exception
handling.  The TRY directive introduces an exception handling scope 
which continues until the matching END directive.  Any errors that 
occur within that block will be caught and can be handled by one
of the CATCH blocks defined.

    [% TRY %]
       ...blah...blah...
       [% CALL somecode %]
       ...etc...
       [% INCLUDE someblock %]
       ...and so on...
    [% CATCH %]
       An error occurred!
    [% END %]

Errors are raised as exceptions (objects of the Template::Exception 
class) and contain two fields, 'type' and 'info'.  The exception 
'type' can be any string containing letters, numbers, '_' or '.', and
is used to indicate the kind of error that occurred.  The 'info' field
contains an error message indicating what actually went wrong.  Within
a catch block, the exception object is aliased to the 'error' variable.
You can access the 'type' and 'info' fields directly.

    [% mydsn = 'dbi:MySQL:foobar' %]
    ...

    [% TRY %]
       [% USE DBI(mydsn) %]
    [% CATCH %]
       ERROR! Type: [% error.type %]
              Info: [% error.info %]
    [% END %]

output (assuming a non-existant database called 'foobar'):

    ERROR!  Type: DBI
            Info: Unknown database "foobar"

The 'error' variable can also be specified by itself and will return a 
string of the form "$type error - $info".

    ...
    [% CATCH %]
    ERROR: [% error %]
    [% END %]

output:

    ERROR: DBI error - Unknown database "foobar"

Each CATCH block may be specified with a particular exception type
denoting the kind of error that it should catch.  Multiple CATCH
blocks can be provided to handle different types of exception that may
be thrown in the TRY block.  A CATCH block specified without any type,
as in the previous example, is a default handler which will catch any
otherwise uncaught exceptions.  This can also be specified as 
[% CATCH DEFAULT %].

    [% TRY %]
       [% INCLUDE myfile %]
       [% USE DBI(mydsn) %]
       [% CALL somecode %]
       ...
    [% CATCH file %]
       File Error! [% error.info %]
    [% CATCH DBI %]
       [% INCLUDE database/error.html %]
    [% CATCH %]
       [% error %]
    [% END %]

Remember that you can specify multiple directives within a single tag,
each delimited by ';'.  Thus, you might prefer to write your simple
CATCH blocks more succinctly as:

    [% TRY %]
       ...
    [% CATCH file; "File Error! $error.info" %]
    [% CATCH DBI;  INCLUDE database/error.html %]
    [% CATCH; error %]
    [% END %]

or even:

    [% TRY %]
       ...
    [% CATCH file ;
           "File Error! $error.info" ;
       CATCH DBI ;
	   INCLUDE database/error.html ;
       CATCH ;
	   error ;
       END
    %]

The DBI plugin throws exceptions of the 'DBI' type (in case that
wasn't already obvious).  The other specific exception caught here is
of the 'file' type.

A 'file' error is automatically thrown by the Template Toolkit when it
can't find a file, or fails to load, parse or process a file that has
been requested by an INCLUDE, PROCESS, INSERT or WRAPPER directive.
If 'myfile' can't be found in the example above, the [% INCLUDE myfile
%] directive will raise a 'file' exception which is then caught by the
[% CATCH file %] block, generating the output:

    File Error! myfile: not found

Note that the DEFAULT option (disabled by default) allows you to
specify a default file to be used any time a template file can't be
found.  This will prevent file exceptions from ever being raised when
a non-existant file is requested (unless, of course, the DEFAULT file
doesn't exist).  Errors encountered once the file has been found
(i.e. read error, parse error) will be raised as file exceptions as per
usual.

Uncaught exceptions (i.e. the TRY block doesn't have a type specific
or default CATCH handler) may be caught by enclosing TRY blocks which
can be nested indefinately across multiple templates.  If the error
isn't caught at any level then processing will stop and the Template
process() method will return a false value to the caller.  The
relevant Template::Exception object can be retrieved by calling the
error() method.

    [% TRY %]
       ...
       [% TRY %]
          [% INCLUDE $user.header %]
       [% CATCH file %]
	  [% INCLUDE header %]
       [% END %]
       ...
    [% CATCH DBI %]
       [% INCLUDE database/error.html %]
    [% END %]

In this example, the inner TRY block is used to ensure that the first
INCLUDE directive works as expected.  We're using a variable to
provide the name of the template we want to include, user.header, and
it's possible this contains the name of a non-existant template, or
perhaps one containing invalid template directives.  If the INCLUDE fails
 with a 'file' error then we CATCH it in the inner block and INCLUDE
the default 'header' file instead.  Any DBI errors that occur within
the scope of the outer TRY block will be caught in the relevant CATCH
block, causing the 'database/error.html' template to be processed.
Note that included templates inherit all currently defined template
variable so these error files can quite happily access the 'error'
variable to retrieve information about the currently caught exception.
e.g.

'database/error.html':

    <h2>Database Error</h2>
    A database error has occurred: [% error.info %]

You can also specify a FINAL block.  This is always processed
regardless of the outcome of the TRY and/or CATCH block.  If an
exception is uncaught then the FINAL block is processed before jumping
to the enclosing block or returning to the caller.

    [% TRY %]
       ...
    [% CATCH this %] 
       ...
    [% CATCH that %] 
       ...
    [% FINAL %]
       All done!
    [% END %]

The output from the TRY block is left intact up to the point where an
exception occurs.  For example, this template:

    [% TRY %]
       This gets printed 
       [% THROW food 'carrots' %]
       This doesn't
    [% CATCH food %]
       culinary delights: [% error.info %]
    [% END %]    

generates the following output:

    This gets printed
    culinary delights: carrots

The CLEAR directive can be used in a CATCH or FINAL block to clear
any output created in the TRY block.

    [% TRY %]
       This gets printed 
       [% THROW food 'carrots' %]
       This doesn't
    [% CATCH food %]
       [% CLEAR %]
       culinary delights: [% error.info %]
    [% END %]    

output:

    culinary delights: carrots
      
Exception types are hierarchical, with each level being separated by
the familiar dot operator.  A 'DBI.connect' exception is a more
specific kind of 'DBI' error.  Similarly, a 'myown.error.barf' is a
more specific kind of 'myown.error' type which itself is also a
'myown' error.  A CATCH handler that specifies a general exception
type (such as 'DBI' or 'myown.error') will also catch more specific
types that have the same prefix as long as a more specific handler
isn't defined.  Note that the order in which CATCH handlers are
defined is irrelevant; a more specific handler will always catch an
exception in preference to a more generic or default one.

    [% TRY %]
       ...
    [% CATCH DBI ;
         INCLUDE database/error.html ;
       CATCH DBI.connect ;
         INCLUDE database/connect.html ;
       CATCH ; 
         INCLUDE error.html ;
       END
    %]

In this example, a 'DBI.connect' error has it's own handler, a more
general 'DBI' block is used for all other DBI or DBI.* errors and a 
default handler catches everything else.

Exceptions can be raised in a template using the THROW directive.  The
first parameter is the exception type which doesn't need to be quoted
(but can be, it's the same as INCLUDE) followed by the relevant error
message which can be any regular value such as a quoted string,
variable, etc.

    [% THROW food "Missing ingredients: $recipe.error" %]

    [% THROW user.login 'no user id: please login' %]

    [% THROW $myerror.type "My Error: $myerror.info" %]

It's also possible to specify additional positional or named 
parameters to the THROW directive if you want to pass more than 
just a simple message back as the error info field.  

    [% THROW food 'eggs' 'flour' msg='Missing Ingredients' %]

In this case, the error 'info' field will be a hash array containing
the named arguments, in this case 'msg' => 'Missing Ingredients',
and an 'args' item which contains a list of the positional arguments, 
in this case 'eggs' and 'flour'.  The error 'type' field remains 
unchanged, here set to 'food'.

    [% CATCH food %]
       [% error.info.msg %]
       [% FOREACH item = error.info.args %]
          * [% item %]
       [% END %]
    [% END %]

This produces the output:

       Missing Ingredients
         * eggs
         * flour

In addition to specifying individual positional arguments as
[% error.info.args.n %], the 'info' hash contains keys directly 
pointing to the positional arguments, as a convenient shortcut.

    [% error.info.0 %]   # same as [% error.info.args.0 %]

Exceptions can also be thrown from Perl code which you've bound to
template variables, or defined as a plugin or other extension.  To
raise an exception, call die() passing a reference to a
Template::Exception object as the argument.  This will then be caught
by any enclosing TRY blocks from where the code was called.

    use Template::Exception;
    ...

    my $vars = {
	foo => sub {
	    # ... do something ...
	    die Template::Exception->new('myerr.naughty',
					 'Bad, bad error');
    	},
    };

template:

    [% TRY %]
       ...
       [% foo %]
       ...   
    [% CATCH myerr ;
         "Error: $error" ;
       END
    %]

output:

    Error: myerr.naughty error - Bad, bad error

The 'info' field can also be a reference to another object or data
structure, if required.

    die Template::Exception->new('myerror', { 
	module => 'foo.pl', 
	errors => [ 'bad permissions', 'naughty boy' ],
    });

Later, in a template:

    [% TRY %]
       ...
    [% CATCH myerror %]
       [% error.info.errors.size or 'no';
          error.info.errors.size == 1 ? ' error' : ' errors' %]
       in [% error.info.module %]: 
          [% error.info.errors.join(', ') %].
    [% END %]

Generating the output:

       2 errors in foo.pl:
          bad permissions, naughty boy.

You can also call die() with a single string, as is common in much 
existing Perl code.  This will automatically be converted to an 
exception of the 'undef' type (that's the literal string 'undef', 
not the undefined value).  If the string isn't terminated with a 
newline then Perl will append the familiar " at $file line $line"
message.

    sub foo {
	# ... do something ...
	die "I'm sorry, Dave, I can't do that\n";
    }

If you're writing a plugin, or some extension code that has the
current Template::Context in scope (you can safely skip this section
if this means nothing to you) then you can also raise an exception by
calling the context throw() method.  You can pass it an
Template::Exception object reference, a pair of ($type, $info) parameters
or just an $info string to create an exception of 'undef' type.

    $context->throw($e);	    # exception object
    $context->throw('Denied');	    # 'undef' type
    $context->throw('user.passwd', 'Bad Password');

=item NEXT

The NEXT directive can be used to start the next iteration of a FOREACH 
or WHILE loop.

    [% FOREACH user = userlist %]
       [% NEXT IF user.isguest %]
       Name: [% user.name %]    Email: [% user.email %]
    [% END %]

=item LAST

The LAST directive can be used to prematurely exit a FOREACH or WHILE
loop.

    [% FOREACH user = userlist %]
       Name: [% user.name %]    Email: [% user.email %]
       [% LAST IF some.condition %]
    [% END %]

BREAK can also be used as an alias for LAST.

=item RETURN

The RETURN directive can be used to stop processing the current
template and return to the template from which it was called, resuming
processing at the point immediately after the INCLUDE, PROCESS or
WRAPPER directive.  If there is no enclosing template then the
Template process() method will return to the calling code with a 
true value.

    Before
    [% INCLUDE half_wit %]
    After
  
    [% BLOCK half_wit %]
    This is just half...
    [% RETURN %]
    ...a complete block
    [% END %]

output:

    Before
    This is just half...
    After

=item STOP

The STOP directive can be used to indicate that the processor should
stop gracefully without processing any more of the template document.
This is a planned stop and the Template process() method will return a
B<true> value to the caller.  This indicates that the template was
processed successfully according to the directives within it.

    [% IF something.terrible.happened %]
       [% INCLUDE fatal/error.html %]
       [% STOP %]
    [% END %]

    [% TRY %]
       [% USE DBI(mydsn) %]
       ...
    [% CATCH DBI.connect %]
       <p>Cannot connect to the database: [% error.info %]</p>
       <br>
       We apologise for the inconvenience.  The cleaning lady 
       has removed the server power to plug in her vacuum cleaner.
       Please try again later.
       </p>
       [% INCLUDE footer %]
       [% STOP %]
    [% END %]

=item CLEAR

The CLEAR directive can be used to clear the output buffer for the current
enclosing block.   It is most commonly used to clear the output generated
from a TRY block up to the point where the error occurred.

    [% TRY %]
       blah blah blah            # this is normally left intact
       [% THROW some 'error' %]  # up to the point of error
       ...
    [% CATCH %]
       [% CLEAR %]               # clear the TRY output
       [% error %]               # print error string
    [% END %]

=back

=head2 Miscellaneous

=over 4

=item META

The META directive allows simple metadata items to be defined within a 
template.  These are evaluated when the template is parsed and as such
may only contain simple values (e.g. it's not possible to interpolate 
other variables values into META variables).

    [% META
       title   = 'The Cat in the Hat'
       author  = 'Dr. Seuss'
       version = 1.23 
    %]

The 'template' variable contains a reference to the main template 
being processed.  These metadata items may be retrieved as attributes
of the template.  

    <h1>[% template.title %]</h1>
    <h2>[% template.author %]</h2>

The 'name' and 'modtime' metadata items are automatically defined for
each template to contain its name and modification time in seconds
since the epoch.

    [% USE date %]		# use Date plugin to format time
    ...
    [% template.name %] last modified
    at [% date.format(template.modtime) %]

The PRE_PROCESS and POST_PROCESS options allow common headers and 
footers to be added to all templates.  The 'template' reference is
correctly defined when these templates are processed, allowing headers
and footers to reference metadata items from the main template.

    $template = Template->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    });

    $template->process('cat_in_hat');

header:
    <html>
    <head>
    <title>[% template.title %]</title>
    </head>
    <body>

cat_in_hat:
    [% META
       title   = 'The Cat in the Hat'
       author  = 'Dr. Seuss'
       version = 1.23 
       year    = 2000
    %]

    The cat in the hat sat on the mat.

footer:
    <hr>
    &copy; [% template.year %] [% template.author %]
    </body>
    </html>

The output generated from the above example is:
    
    <html>
    <head>
    <title>The Cat in the Hat</title>
    </head>
    <body>

    The cat in the hat sat on the mat.

    <hr>
    &copy; 2000 Dr. Seuss
    </body>
    </html>

=item TAGS

The TAGS directive can be used to set the START_TAG and END_TAG values
on a per-template file basis.

    [% TAGS <+ +> %]

    <+ INCLUDE header +>

The TAGS directive may also be used to set a named TAG_STYLE

    [% TAGS html %]
    <!-- INCLUDE header -->

See the TAGS and TAG_STYLE configuration options for further details.

=back

=head1 CONFIGURATION OPTIONS

The Template module accepts configuration items destined for any other 
Template::* module that it may create and will forward them appropriately.
The following list summarises the various options under several broad 
categories.

=head2 Template Style and Parsing Options

=over 4

=item START_TAG, END_TAG

The START_TAG and END_TAG options are used to specify character
sequences or regular expressions that mark the start and end of a
template directive.  The default values for START_TAG and END_TAG are
'[%' and '%]' respectively, giving us the familiar directive style:

    [% example %]

Any Perl regex characters can be used and therefore should be escaped
(or use the Perl C<quotemeta> function) if they are intended to
represent literal characters.

    my $template = Template->new({ 
  	START_TAG => quotemeta('<+'),
  	END_TAG   => quotemeta('+>'),
    });

example:

    <+ INCLUDE foobar +>

The TAGS directive can also be used to set the START_TAG and END_TAG values
on a per-template file basis.

    [% TAGS <+ +> %]

=item TAG_STYLE

The TAG_STYLE option can be used to set both START_TAG and END_TAG
according to pre-defined tag styles.  

    my $template = Template->new({ 
  	TAG_STYLE => 'php',
    });

Available styles are:

    template    [% ... %]               (default)
    template1   [% ... %] or %% ... %%  (Template version 1)
    metatext    %% ... %%               (Text::MetaText)
    php         <? ... ?>               (PHP)
    asp         <% ... %>               (ASP)
    mason       <% ...  >               (HTML::Mason)
    html        <!-- ... -->            (HTML comments)

Any values specified for START_TAG and/or END_TAG will over-ride
those defined by a TAG_STYLE.  

The TAGS directive may also be used to set a TAG_STYLE

    [% TAGS html %]
    <!-- INCLUDE header -->

=item PRE_CHOMP, POST_CHOMP

Anything outside a directive tag is considered plain text and is
generally passed through unaltered (but see the INTERPOLATE option).
This includes all whitespace and newlines characters surrounding
directive tags.  Directives that don't generate any output will leave
gaps in the output document.

Example:

    Foo
    [% a = 10 %]
    Bar

Output:

    Foo

    Bar

The PRE_CHOMP and POST_CHOMP options can help to clean up some of this
extraneous whitespace.  Both are disabled by default.

    my $template = Template->new({
	PRE_CHOMP  => 1,
	POST_CHOMP => 1,
    });

With PRE_CHOMP set true, the newline and whitespace preceeding a directive
at the start of a line will be deleted.  This has the effect of 
concatenating a line that starts with a directive onto the end of the 
previous line.

 	Foo <----------.
 		       |
    ,---(PRE_CHOMP)----'
    |
    `-- [% a = 10 %] --.
 		       |
    ,---(POST_CHOMP)---'
    |
    `-> Bar

With POST_CHOMP set true, any whitespace after a directive up to and
including the newline will be deleted.  This has the effect of joining
a line that ends with a directive onto the start of the next line.

PRE_CHOMP and POST_CHOMP can be activated for individual directives by
placing a '-' immediately at the start and/or end of the directive.

    [% FOREACH user = userlist %]
       [%- user -%]
    [% END %]

The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one
directive '[%- name -%]'.  Thus, the template will be processed as if
written:

    [% FOREACH user = userlist %][% user %][% END %]

Similarly, '+' characters can be used to disable PRE_CHOMP or
POST_CHOMP (i.e.  leave the whitespace/newline intact) options on a
per-directive basis.

    [% FOREACH user = userlist %]
    User: [% user +%]
    [% END %]

With POST_CHOMP enabled, the above example would be parsed as if written:

    [% FOREACH user = userlist %]User: [% user %]
    [% END %]

=item TRIM

The TRIM option can be set to have any leading and trailing whitespace 
automatically removed from the output of all template files and BLOCKs.

By example, the following BLOCK definition

    [% BLOCK foo %]
    Line 1 of foo
    [% END %]

will be processed is as "\nLine 1 of foo\n".  When INCLUDEd, the surrounding
newlines will also be introduced.

    before 
    [% INCLUDE foo %]
    after

output:
    before

    Line 1 of foo

    after

With the TRIM option set to any true value, the leading and trailing
newlines (which count as whitespace) will be removed from the output 
of the BLOCK.

    before
    Line 1 of foo
    after

The TRIM option is disabled (0) by default.

=item INTERPOLATE

The INTERPOLATE flag, when set to any true value will cause variable 
references in plain text (i.e. not surrounded by START_TAG and END_TAG)
to be recognised and interpolated accordingly.  

    my $template = Template->new({ 
  	INTERPOLATE => 1,
    });

Variables should be prefixed by a '$' to identify them.  Curly braces
can be used in the familiar Perl/shell style to explicitly scope the
variable name where required.

    # INTERPOLATE => 0
    <a href="http://[% server %]/[% help %]">
    <img src="[% images %]/help.gif"></a>
    [% myorg.name %]
  
    # INTERPOLATE => 1
    <a href="http://$server/$help">
    <img src="$images/help.gif"></a>
    $myorg.name
  
    # explicit scoping with {  }
    <img src="$images/${icon.next}.gif">

Note that a limitation in Perl's regex engine restricts the maximum length
of an interpolated template to around 32 kilobytes or possibly less.  Files
that exceed this limit in size will typically cause Perl to dump core with
a segmentation fault.  If you routinely process templates of this size 
then you should disable INTERPOLATE or split the templates in several 
smaller files or blocks which can then be joined backed together via 
PROCESS or INCLUDE.

=item ANYCASE

By default, directive keywords should be expressed in UPPER CASE.  The 
ANYCASE option can be set to allow directive keywords to be specified
in any case.

    # ANYCASE => 0 (default)
    [% INCLUDE foobar %]	# OK
    [% include foobar %]        # ERROR
    [% include = 10   %]        # OK, 'include' is a variable

    # ANYCASE => 1
    [% INCLUDE foobar %]	# OK
    [% include foobar %]	# OK
    [% include = 10   %]        # ERROR, 'include' is reserved word

One side-effect of enabling ANYCASE is that you cannot use a variable
of the same name as a reserved word, regardless of case.  The reserved
words are currently:

    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

The only lower case reserved words that cannot be used for variables,
regardless of the ANYCASE option, are the operators:

    and or not mod div

=back

=head2 Template Files and Blocks

=over 4

=item INCLUDE_PATH

The INCLUDE_PATH is used to specify one or more directories in which
template files are located.  When a template is requested that isn't
defined locally as a BLOCK, each of the INCLUDE_PATH directories is
searched in turn to locate the template file.  Multiple directories
can be specified as a reference to a list or as a single string where
each directory is delimited by ':'. The DELIMITER option can be set
to redefine the delimiter value.

    my $template = Template->new({
        INCLUDE_PATH => '/usr/local/templates',
    });
  
    my $template = Template->new({
        INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
    });
  
    my $template = Template->new({
        INCLUDE_PATH => [ '/usr/local/templates', 
                          '/tmp/my/templates' ],
    });

=item DELIMITER

Used to provide an alternative delimiter character sequence for 
separating paths specified in the INCLUDE_PATH.  May be useful for 
operating systems that permit the use of ':' in file names.

    # tolerate Silly Billy's file system conventions
    my $template = Template->new({
	DELIMITER    => ' ',
        INCLUDE_PATH => 'C:/HERE/NOW D:/THERE/THEN',
    });

    # better solution: install Linux!  :-)

=item ABSOLUTE

The ABSOLUTE flag is used to indicate if templates specified with
absolute filenames (e.g. '/foo/bar') should be processed.  It is
disabled by default and any attempt to load a template by such a
name will cause a 'file' exception to be raised.

    my $template = Template->new({
	ABSOLUTE => 1,
    });

    # this is why it's disabled by default
    [% INSERT /etc/passwd %]

=item RELATIVE

The RELATIVE flag is used to indicate if templates specified with
filenames relative to the current directory (e.g. './foo/bar' or
'../../some/where/else') should be loaded.  It is also disabled by
default, and will raise a 'file' error if such template names are
encountered.  

    my $template = Template->new({
	RELATIVE => 1,
    });

    [% INCLUDE ../logs/error.log %]

=item DEFAULT

The DEFAULT option can be used to specify a default template which should 
be used whenever a specified template can't be found in the INCLUDE_PATH.

    my $template = Template->new({
	DEFAULT => 'notfound.html',
    });

If a non-existant template is requested through the Template process()
method, or by an INCLUDE, PROCESS or WRAPPER directive, then the
DEFAULT template will instead be processed, if defined.  Note that the
DEFAULT template is not used when templates are specified with
absolute or relative filenames, or as a reference to a input file
handle or text string.

=item BLOCKS

The BLOCKS option can be used to pre-define a default set of template 
blocks.  These should be specified as a reference to a hash array 
mapping template names to template text, subroutines or Template::Document
objects.

    my $template = Template->new({
	BLOCKS => {
	    header  => 'The Header.  [% title %]',
	    footer  => sub { return $some_output_text },
	    another => Template::Document->new({ ... }),
	},
    });

=item AUTO_RESET

The AUTO_RESET option is set by default and causes the local BLOCKS
cache for the Template::Context object to be reset on each call to the
Template process() method.  This ensures that any BLOCKs defined
within a template will only persist until that template is finished
processing.  This prevents BLOCKs defined in one processing request
from interfering with other independant requests subsequently
processed by the same context object.

The BLOCKS item may be used to specify a default set of block definitions
for the Template::Context object.  Subsequent BLOCK definitions in templates
will over-ride these but they will be reinstated on each reset if AUTO_RESET
is enabled (default), or if the Template::Context reset() method is called.

=item RECURSION

The template processor will raise a file exception if it detects
direct or indirect recursion into a template.  Setting this option to 
any true value will allow templates to include each other recursively.

=back

=head2 Template Variables

=over 4

=item VARIABLES, PRE_DEFINE

The VARIABLES option (or PRE_DEFINE - they're equivalent) can be used
to specify a hash array of template variables that should be used to
pre-initialise the stash when it is created.  These items are ignored
if the STASH item is defined.

    my $template = Template->new({
	VARIABLES => {
	    title   => 'A Demo Page',
	    author  => 'Joe Random Hacker',
	    version => 3.14,
	},
    };

or

    my $template = Template->new({
	PRE_DEFINE => {
	    title   => 'A Demo Page',
	    author  => 'Joe Random Hacker',
	    version => 3.14,
	},
    };

=back

=head2 Runtime Processing Options

=over 4

=item EVAL_PERL

This flag is used to indicate if PERL and/or RAWPERL blocks should be
evaluated.  By default, it is disabled and any PERL or RAWPERL blocks
encountered will raise exceptions of type 'perl' with the message
'EVAL_PERL not set'.  Note however that any RAWPERL blocks should
always contain valid Perl code, regardless of the EVAL_PERL flag.  The
parser will fail to compile templates that contain invalid Perl code
in RAWPERL blocks and will throw a 'file' exception.

When using compiled templates (see L<COMPILE_EXT> and L<COMPILE_DIR>),
the EVAL_PERL has an affect when the template is compiled, and again
when the templates is subsequently processed, possibly in a different
context to the one that compiled it.

If the EVAL_PERL is set when a template is compiled, then all PERL and
RAWPERL blocks will be included in the compiled template.  If the 
EVAL_PERL option isn't set, then Perl code will be generated which 
B<always> throws a 'perl' exception with the message 'EVAL_PERL not
set' B<whenever> the compiled template code is run.

Thus, you must have EVAL_PERL set if you want your compiled templates
to include PERL and RAWPERL blocks.

At some point in the future, using a different invocation of the
Template Toolkit, you may come to process such a pre-compiled
template.  Assuming the EVAL_PERL option was set at the time the
template was compiled, then the output of any RAWPERL blocks will be
included in the compiled template and will get executed when the
template is processed.  This will happen regardless of the runtime
EVAL_PERL status.

Regular PERL blocks are a little more cautious, however.  If the 
EVAL_PERL flag isn't set for the I<current> context, that is, the 
one which is trying to process it, then it will throw the familiar 'perl'
exception with the message, 'EVAL_PERL not set'.

Thus you can compile templates to include PERL blocks, but optionally
disable them when you process them later.  Note however that it is 
possible for a PERL block to contain a Perl "BEGIN { # some code }"
block which will always get run regardless of the runtime EVAL_PERL
status.  Thus, if you set EVAL_PERL when compiling templates, it is
assumed that you trust the templates to Do The Right Thing.  Otherwise
you must accept the fact that there's no bulletproof way to prevent 
any included code from trampling around in the living room of the 
runtime environment, making a real nuisance of itself if it really
wants to.  If you don't like the idea of such uninvited guests causing
a bother, then you can accept the default and keep EVAL_PERL disabled.

=item PRE_PROCESS, POST_PROCESS

These values may be set to contain the name(s) of template files
(relative to INCLUDE_PATH) which should be processed immediately
before and/or after each template.  These do not get added to 
templates processed into a document via directives such as INCLUDE, 
PROCESS, WRAPPER etc.

    my $template = Template->new({
	PRE_PROCESS  => 'header',
	POST_PROCESS => 'footer',
    };

Multiple templates may be specified as a reference to a list.  Each is 
processed in the order defined.

    my $template = Template->new({
	PRE_PROCESS  => [ 'config', 'header' ],
	POST_PROCESS => 'footer',
    };

Alternately, multiple template may be specified as a single string, 
delimited by ':'.  This delimiter string can be changed via the 
DELIMITER option.

    my $template = Template->new({
	PRE_PROCESS  => 'config:header',
	POST_PROCESS => 'footer',
    };

The PRE_PROCESS and POST_PROCESS templates are evaluated in the same
variable context as the main document and may define or update
variables for subseqent use.

config:
    [% # set some site-wide variables
       bgcolor = '#ffffff'
       version = 2.718
    %]

header:
    [% DEFAULT title = 'My Funky Web Site' %]
    <html>
    <head>
    <title>[% title %]</title>
    </head>
    <body bgcolor="[% bgcolor %]">

footer:
    <hr>
    Version [% version %]
    </body>
    </html>

The Template::Document object representing the main template being processed
is available within PRE_PROCESS and POST_PROCESS templates as the 'template'
variable.  Metadata items defined via the META directive may be accessed 
accordingly.

    $template->process('mydoc.html', $vars);

mydoc.html:
    [% META title = 'My Document Title' %]
    blah blah blah
    ...

header:
    <html>
    <head>
    <title>[% template.title %]</title></head>
    <body bgcolor="[% bgcolor %]">

=item PROCESS

The PROCESS option may be set to contain the name(s) of template files
(relative to INCLUDE_PATH) which should be processed instead of the 
main template passed to the Template process() method.  This can 
be used to apply consistent wrappers around all templates, similar to 
the use of PRE_PROCESS and POST_PROCESS templates.

    my $template = Template->new({
	PROCESS  => 'content',
    };

    # processes 'content' instead of 'foo.html'
    $template->process('foo.html');

A reference to the original template is available in the 'template'
variable.  Metadata items can be inspected and the template can be
processed by specifying it as a variable reference (i.e. prefixed by
'$') to an INCLUDE, PROCESS or WRAPPER directive.

content:

    <html>
    <head>
    <title>[% template.title %]</title>
    </head>
    
    <body>
    [% PROCESS $template %]
    <hr>
    &copy; Copyright [% template.copyright %]
    </body>
    </html>

foo.html:

    [% META 
       title     = 'The Foo Page'
       author    = 'Fred Foo'
       copyright = '2000 Fred Foo'
    %]
    <h1>[% template.title %]</h1>
    Welcome to the Foo Page, blah blah blah

output:    

    <html>
    <head>
    <title>The Foo Page</title>
    </head>

    <body>
    <h1>The Foo Page</h1>
    Welcome to the Foo Page, blah blah blah
    <hr>
    &copy; Copyright 2000 Fred Foo
    </body>
    </html>

=item ERROR

The ERROR (or ERRORS if you prefer) configuration item can be used to
name a single template or specify a hash array mapping exception types
to templates which should be used for error handling.  If an uncaught
exception is raised from within a template then the appropriate error
template will instead be processed.

If specified as a single value then that template will be processed 
for all uncaught exceptions. 

    my $template = Template->new({
	ERROR => 'error.html'
    });

If the ERROR item is a hash reference the keys are assumed to be
exception types and the relevant template for a given exception will
be selected.  A 'default' template may be provided for the general
case.  Note that 'ERROR' can be pluralised to 'ERRORS' if you find
it more appropriate in this case.

    my $template = Template->new({
	ERRORS => {
	    user     => 'user/index.html',
	    dbi      => 'error/database',
	    default  => 'error/default',
	},
    });

In this example, any 'user' exceptions thrown will cause the
'user/index.html' template to be processed, 'dbi' errors are handled
by 'error/database' and all others by the 'error/default' template.
Any PRE_PROCESS and/or POST_PROCESS templates will also be applied
to these error templates.

Note that exception types are hierarchical and a 'foo' handler will
catch all 'foo.*' errors (e.g. foo.bar, foo.bar.baz) if a more
specific handler isn't defined.  Be sure to quote any exception types
that contain periods to prevent Perl concatenating them into a single
string (i.e. C<user.passwd> is parsed as 'user'.'passwd').

    my $template = Template->new({
	ERROR => {
	    'user.login'  => 'user/login.html',
	    'user.passwd' => 'user/badpasswd.html',
	    'user'        => 'user/index.html',
	    'default'     => 'error/default',
	},
    });

In this example, any template processed by the $template object, or
other templates or code called from within, can raise a 'user.login'
exception and have the service redirect to the 'user/login.html'
template.  Similarly, a 'user.passwd' exception has a specific 
handling template, 'user/badpasswd.html', while all other 'user' or
'user.*' exceptions cause a redirection to the 'user/index.html' page.
All other exception types are handled by 'error/default'.

Exceptions can be raised in a template using the THROW directive,

    [% THROW user.login 'no user id: please login' %]

or by calling the throw() method on the current Template::Context object,

    $context->throw('user.passwd', 'Incorrect Password');
    $context->throw('Incorrect Password');    # type 'undef'

or from Perl code by calling die() with a Template::Exception object,

    die Template::Exception->new('user.denied', 'Invalid User ID');

or by simply calling die() with an error string.  This is
automagically caught and converted to an  exception of 'undef'
type which can then be handled in the usual way.

    die "I'm sorry Dave, I can't do that";

=item  OUTPUT

Default output location or handler.  This may be specified as one of:
a file name (relative to OUTPUT_PATH, if defined, or the current
working directory if not specified absolutely); a file handle
(e.g. GLOB or IO::Handle) opened for writing; a reference to a text
string to which the output is appended (the string isn't cleared); a
reference to a subroutine which is called, passing the output text as
an argument; or as a reference to any object that supports the print()
method.  This latter option includes the Apache::Request object which
is passed as the argument to Apache/mod_perl handlers.

example 1 (file name):

    my $template = Template->new({
	OUTPUT => "/tmp/foo",
    });

example 2 (text string):

    my $output = '';

    my $template = Template->new({
	OUTPUT => \$output,
    });

example 3 (file handle):

    open (TOUT, "> $file") || die "$file: $!\n";

    my $template = Template->new({
	OUTPUT => \*TOUT,
    });

example 4 (subroutine):

    sub output { my $out = shift; print "OUTPUT: $out" }

    my $template = Template->new({
	OUTPUT => \&output,
    });

example 5 (Apache/mod_perl handler):

    sub handler {
	my $r = shift;

	my $t = Template->new({
	    OUTPUT => $r,
	});
	...
    }

The default OUTPUT location be overridden by passing a third parameter
to the Template process() method.  This can be specified as any of the 
above argument types.

    $t->process($file, $vars, "/tmp/foo");
    $t->process($file, $vars, "bar");
    $t->process($file, $vars, \*MYGLOB);
    $t->process($file, $vars, $r);  # Apache::Request
    ...

=item  OUTPUT_PATH

The OUTPUT_PATH allows a directory to be specified into which output
files should be written.  An output file can be specified by the 
OUTPUT option, or passed by name as the third paramater to the 
Template process() method.

    my $template = Template->new({
	INPUT_PATH  => "/tmp/src",
	OUTPUT_PATH => "/tmp/dest",
    });

    my $vars = {
	...
    };

    foreach my $file ('foo.html', 'bar.html') {
	$template->process($file, $vars, $file)
	    || die $template->error();	
    }

This example will read the input files '/tmp/src/foo.html' and 
'/tmp/src/bar.html' and write the processed output to '/tmp/dest/foo.html'
and '/tmp/dest/bar.html', respectively.

=item DEBUG

The DEBUG option causing any access to an undefined variable to be 
raised as an 'undef' error.


=back

=head2 Caching and Compiling Options

=over 4

=item CACHE_SIZE

The Template::Provider module caches compiled templates to avoid the need
to re-parse template files or blocks each time they are used.  The CACHE_SIZE
option is used to limit the number of compiled templates that the module
should cache.

By default, the CACHE_SIZE is undefined and all compiled templates are
cached.  When set to any positive value, the cache will be limited to
storing no more than that number of compiled templates.  When a new
template is loaded and compiled and the cache is full (i.e. the number
of entries == CACHE_SIZE), the least recently used compiled template
is discarded to make room for the new one.

The CACHE_SIZE can be set to 0 to disable caching altogether.

    my $template = Template->new({
	CACHE_SIZE => 64,   # only cache 64 compiled templates
    });

    my $template = Template->new({
	CACHE_SIZE => 0,   # don't cache any compiled templates
    });

=item COMPILE_EXT

From version 2 onwards, the Template Toolkit has the ability to
compile templates to Perl code and save them to disk for subsequent
use (i.e. cache persistance).  The COMPILE_EXT option may be
provided to specify a filename extension for compiled template files.
It is undefined by default and no attempt will be made to read or write 
any compiled template files.

    my $template = Template->new({
	COMPILE_EXT => '.ttc',
    });

If COMPILE_EXT is defined (and COMPILE_DIR isn't, see below) then compiled
template files with the COMPILE_EXT extension will be written to the same
directory from which the source template files were loaded.

Compiling and subsequent reuse of templates happens automatically
whenever the COMPILE_EXT or COMPILE_DIR options are set.  The Template
Toolkit will automatically reload and reuse compiled files when it 
finds them on disk.  If the corresponding source file has been modified
since the compiled version as written, then it will load and re-compile
the source and write a new compiled version to disk.  

This form of cache persistance offers significant benefits in terms of 
time and resources required to reload templates.  Compiled templates can
be reloaded by a simple call to Perl's require(), leaving Perl to handle
all the parsing and compilation.  This is a Good Thing.

=item COMPILE_DIR

The COMPILE_DIR option is used to specify an alternate directory root
under which compiled template files should be saved.  

    my $template = Template->new({
	COMPILE_DIR => '/tmp/ttc',
    });

The COMPILE_EXT option may also be specified to have a consistent file
extension added to these files.  

    my $template1 = Template->new({
	COMPILE_DIR => '/tmp/ttc',
	COMPILE_EXT => '.ttc1',
    });

    my $template2 = Template->new({
	COMPILE_DIR => '/tmp/ttc',
	COMPILE_EXT => '.ttc2',
    });


When COMPILE_EXT is undefined, the compiled template files have the
same name as the original template files, but reside in a different
directory tree.

Each directory in the INCLUDE_PATH is replicated in full beneath the 
COMPILE_DIR directory.  This example:

    my $template = Template->new({
	COMPILE_DIR  => '/tmp/ttc',
	INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
    });

would create the following directory structure:

    /tmp/ttc/home/abw/templates/
    /tmp/ttc/usr/share/templates/

Files loaded from different INCLUDE_PATH directories will have their
compiled forms save in the relevant COMPILE_DIR directory.

=back

=head2 Plugins and Filters

=over 4

=item PLUGINS

The PLUGINS options can be used to provide a reference to a hash array
that maps plugin names to Perl module names.  A number of standard
plugins are defined (e.g. 'table', 'cgi', 'dbi', etc.) which map to
their corresponding Template::Plugin::* counterparts.  These can be
redefined by values in the PLUGINS hash.

    my $template = Template->new({
	PLUGINS => [
	    cgi => 'MyOrg::Template::Plugin::CGI',
    	    foo => 'MyOrg::Template::Plugin::Foo',
	    bar => 'MyOrg::Template::Plugin::Bar',
	],
    });

The USE directive is used to create plugin objects and does so by
calling the plugin() method on the current Template::Context object.
If the plugin name is defined in the PLUGINS hash then the
corresponding Perl module is loaded via require().  The context then
calls the load() class method which should return the class name 
(default and general case) or a prototype object against which the 
new() method can be called to instantiate individual plugin objects.

If the plugin name is not defined in the PLUGINS hash then the PLUGIN_BASE
and/or LOAD_PERL options come into effect.

=item PLUGIN_BASE

If a plugin is not defined in the PLUGINS hash then the PLUGIN_BASE is used
to attempt to construct a correct Perl module name which can be successfully 
loaded.  

The PLUGIN_BASE can be specified as a single value or as a reference
to an array of multiple values.  The default PLUGIN_BASE value,
'Template::Plugin', is always added the the end of the PLUGIN_BASE
list (a single value is first converted to a list).  Each value should
contain a Perl package name to which the requested plugin name is
appended.

example 1:

    my $template = Template->new({
	PLUGIN_BASE => 'MyOrg::Template::Plugin',
    });

    [% USE Foo %]    # => MyOrg::Template::Plugin::Foo
                       or        Template::Plugin::Foo 

example 2:

    my $template = Template->new({
	PLUGIN_BASE => [   'MyOrg::Template::Plugin',
			 'YourOrg::Template::Plugin'  ],
    });

    [% USE Foo %]    # =>   MyOrg::Template::Plugin::Foo
                       or YourOrg::Template::Plugin::Foo 
                       or          Template::Plugin::Foo

=item LOAD_PERL

If a plugin cannot be loaded using the PLUGINS or PLUGIN_BASE
approaches then the provider can make a final attempt to load the
module without prepending any prefix to the module path.  This allows
regular Perl modules (i.e. those that don't reside in the
Template::Plugin or some other such namespace) to be loaded and used
as plugins.

By default, the LOAD_PERL option is set to 0 and no attempt will be made
to load any Perl modules that aren't named explicitly in the PLUGINS
hash or reside in a package as named by one of the PLUGIN_BASE
components.  

Plugins loaded using the PLUGINS or PLUGIN_BASE receive a reference to
the current context object as the first argument to the new()
constructor.  Modules loaded using LOAD_PERL are assumed to not
conform to the plugin interface.  They must provide a new() class
method for instantiating objects but it will not receive a reference
to the context as the first argument.  Plugin modules should provide a
load() class method (or inherit the default one from the
Template::Plugin base class) which is called the first time the plugin
is loaded.  Regular Perl modules need not.  In all other respects,
regular Perl objects and Template Toolkit plugins are identical.

If a particular Perl module does not conform to the common, but not
unilateral, new() constructor convention then a simple plugin wrapper
can be written to interface to it.

=item FILTERS

The FILTERS option can be used to specify custom filters which can
then be used with the FILTER directive like any other.  These are
added to the standard filters which are available by default.  Filters
specified via this option will mask any standard filters of the same
name.

The FILTERS option should be specified as a reference to a hash array
in which each key represents the name of a filter.  The corresponding
value should contain a reference to an array containing a subroutine
reference and a flag which indicates if the filter is static (0) or
dynamic (1).  A filter may also be specified as a solitary subroutine
reference and is assumed to be static.

    $template = Template->new({
  	FILTERS => {
  	    'sfilt1' =>   \&static_filter,      # static
            'sfilt2' => [ \&static_filter, 0 ], # same as above
  	    'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
  	},
    });

Additional filters can be specified at any time by calling the 
define_filter() method on the current Template::Context object.
The method accepts a filter name, a reference to a filter 
subroutine and an optional flag to indicate if the filter is 
dynamic.

    my $context = $template->context();
    $context->define_filter('new_html', \&new_html);
    $context->define_filter('new_repeat', \&new_repeat, 1);

Static filters are those where a single subroutine reference is used
for all invocations of a particular filter.  Filters that don't accept
any configuration parameters (e.g. 'html') can be implemented
statically.  The subroutine reference is simply returned when that
particular filter is requested.  The subroutine is called to filter
the output of a template block which is passed as the only argument.
The subroutine should return the modified text.

    sub static_filter {
  	my $text = shift;
	# do something to modify $text...
  	return $text;
    }

The following template fragment:

    [% FILTER sfilt1 %]
    Blah blah blah.
    [% END %]

is approximately equivalent to:

    &static_filter("\nBlah blah blah.\n");

Filters that can accept parameters (e.g. 'truncate') should be
implemented dynamically.  In this case, the subroutine is taken to be
a filter 'factory' that is called to create a unique filter subroutine
each time one is requested.  A reference to the current
Template::Context object is passed as the first parameter, followed by
any additional parameters specified.  The subroutine should return
another subroutine reference (usually a closure) which implements the
filter.

    sub dynamic_filter_factory {
	my ($context, @args) = @_;

  	return sub {
  	    my $text = shift;
	    # do something to modify $text...
	    return $text;	    
  	}
    }

The following template fragment:

    [% FILTER dfilt1(123, 456) %] 
    Blah blah blah
    [% END %]              

is approximately equivalent to:

    my $filter = &dynamic_filter_factory($context, 123, 456);
    &$filter("\nBlah blah blah.\n");

See the FILTER directive for further examples.

=back

=head2 Compatibility, Customisation and Extension

=over 4

=item V1DOLLAR

In version 1 of the Template Toolkit, an optional leading '$' could be placed
on any template variable and would be silently ignored.

    # VERSION 1
    [% $foo %]       ===  [% foo %]
    [% $hash.$key %] ===  [% hash.key %]

To interpolate a variable value the '${' ... '}' construct was used.
Typically, one would do this to index into a hash array when the key
value was stored in a variable.

example:

    my $vars = {
	users => {
	    aba => { name => 'Alan Aardvark', ... },
	    abw => { name => 'Andy Wardley', ... },
            ...
	},
	uid => 'aba',
        ...
    };

    $template->process('user/home.html', $vars)
	|| die $template->error(), "\n";

'user/home.html':

    [% user = users.${uid} %]     # users.aba
    Name: [% user.name %]         # Alan Aardvark

This was inconsistent with double quoted strings and also the
INTERPOLATE mode, where a leading '$' in text was enough to indicate a
variable for interpolation, and the additional curly braces were used
to delimit variable names where necessary.  Note that this use is
consistent with UNIX and Perl conventions, among others.

    # double quoted string interpolation
    [% name = "$title ${user.name}" %]

    # INTERPOLATE = 1
    <img src="$images/help.gif"></a>
    <img src="$images/${icon.next}.gif">

For version 2, these inconsistencies have been removed and the syntax
clarified.  A leading '$' on a variable is now used exclusively to
indicate that the variable name should be interpolated
(e.g. subsituted for its value) before being used.  The earlier example
from version 1:

    # VERSION 1
    [% user = users.${uid} %]
    Name: [% user.name %]

can now be simplified in version 2 as:

    # VERSION 2
    [% user = users.$uid %]
    Name: [% user.name %]

The leading dollar is no longer ignored and has the same effect of
interpolation as '${' ... '}' in version 1.  The curly braces may
still be used to explicitly scope the interpolated variable name
where necessary.

e.g.

    [% user = users.${me.id} %]
    Name: [% user.name %]

The rule applies for all variables, both within directives and in
plain text if processed with the INTERPOLATE option.  This means that
you should no longer (if you ever did) add a leading '$' to a variable
inside a directive, unless you explicitly want it to be interpolated.

One obvious side-effect is that any version 1 templates with variables
using a leading '$' will no longer be processed as expected.  Given
the following variable definitions,

    [% foo = 'bar'
       bar = 'baz'
    %]

version 1 would interpret the following as:

    # VERSION 1
    [% $foo %] => [% GET foo %] => bar

whereas version 2 interprets it as:

    # VERSION 2
    [% $foo %] => [% GET $foo %] => [% GET bar %] => baz

In version 1, the '$' is ignored and the value for the variable 'foo' is 
retrieved and printed.  In version 2, the variable '$foo' is first interpolated
to give the variable name 'bar' whose value is then retrieved and printed.

The use of the optional '$' has never been strongly recommended, but
to assist in backwards compatibility with any version 1 templates that
may rely on this "feature", the V1DOLLAR option can be set to 1
(default: 0) to revert the behaviour and have leading '$' characters
ignored.

    my $template = Template->new({
	V1DOLLAR => 1,
    });

=item LOAD_TEMPLATES

The LOAD_TEMPLATE option can be used to provide a reference to a list
of Template::Provider objects or sub-classes thereof which will take
responsibility for loading and compiling templates.

    my $template = Template->new({
	LOAD_TEMPLATES => [
    	    MyOrg::Template::Provider->new({ ... }),
    	    Template::Provider->new({ ... }),
	],
    });

When a PROCESS, INCLUDE or WRAPPER directive is encountered, the named
template may refer to a locally defined BLOCK or a file relative to
the INCLUDE_PATH (or an absolute or relative path if the appropriate
ABSOLUTE or RELATIVE options are set).  If a BLOCK definition can't be
found (see the Template::Context template() method for a discussion of
BLOCK locality) then each of the LOAD_TEMPLATES provider objects is
queried in turn via the fetch() method to see if it can supply the
required template.  Each provider can return a compiled template, an
error, or decline to service the request in which case the
responsiblity is passed to the next provider.  If none of the
providers can service the request then a 'not found' error is
returned.  The same basic provider mechanism is also used for the 
INSERT directive but it bypasses any BLOCK definitions and doesn't
attempt is to parse or process the contents of the template file.

This is an implementation of the 'Chain of Responsiblity'
design pattern as described in 
"Design Patterns", Erich Gamma, Richard Helm, Ralph Johnson, John 
Vlissides), Addision-Wesley, ISBN 0-201-63361-2, page 223.

If LOAD_TEMPLATES is undefined, a single default provider will be
instantiated using the current configuration parameters.  For example,
the Template::Provider INCLUDE_PATH option can be specified in the Template configuration and will be correctly passed to the provider's
constructor method.

    my $template = Template->new({
	INCLUDE_PATH => '/here:/there',
    });

=item LOAD_PLUGINS

The LOAD_PLUGINS options can be used to specify a list of provider
objects (i.e. they implement the fetch() method) which are responsible
for loading and instantiating template plugin objects.  The
Template::Content plugin() method queries each provider in turn in a
"Chain of Responsibility" as per the template() and filter() methods.

    my $template = Template->new({
	LOAD_PLUGINS => [
    	    MyOrg::Template::Plugins->new({ ... }),
    	    Template::Plugins->new({ ... }),
	],
    });

By default, a single Template::Plugins object is created using the 
current configuration hash.  Configuration items destined for the 
Template::Plugins constructor may be added to the Template 
constructor.

    my $template = Template->new({
	PLUGIN_BASE => 'MyOrg::Template::Plugins',
	LOAD_PERL   => 1,
    });

=item LOAD_FILTERS

The LOAD_FILTERS option can be used to specify a list of provider
objects (i.e. they implement the fetch() method) which are responsible
for returning and/or creating filter subroutines.  The
Template::Context filter() method queries each provider in turn in a
"Chain of Responsibility" as per the template() and plugin() methods.

    my $template = Template->new({
	LOAD_FILTERS => [
    	    MyTemplate::Filters->new(),
    	    Template::Filters->new(),
	],
    });

By default, a single Template::Filters object is created for the
LOAD_FILTERS list.

=item TOLERANT

The TOLERANT flag is used by the various Template Toolkit provider
modules (Template::Provider, Template::Plugins, Template::Filters) to
control their behaviour when errors are encountered.  By default, any
errors are reported as such, with the request for the particular
resource (template, plugin, filter) being denied and an exception
raised.  When the TOLERANT flag is set to any true values, errors will
be silently ignored and the provider will instead return
STATUS_DECLINED.  This allows a subsequent provider to take
responsibility for providing the resource, rather than failing the
request outright.  If all providers decline to service the request,
either through tolerated failure or a genuine disinclination to
comply, then a '<resource> not found' exception is raised.

=item SERVICE

A reference to a Template::Service object, or sub-class thereof, to which
the Template module should delegate.  If unspecified, a Template::Service
object is automatically created using the current configuration hash.

    my $template = Template->new({
	SERVICE => MyOrg::Template::Service->new({ ... }),
    });

=item CONTEXT

A reference to a Template::Context object which is used to define a 
specific environment in which template are processed.  A Template::Context
object is passed as the only parameter to the Perl subroutines that 
represent "compiled" template documents.  Template subroutines make 
callbacks into the context object to access Template Toolkit functionality,
for example, to to INCLUDE or PROCESS another template (include() and 
process() methods, respectively), to USE a plugin (plugin()) or 
instantiate a filter (filter()) or to access the stash (stash()) which 
manages variable definitions via the get() and set() methods.

    my $template = Template->new({
	CONTEXT => MyOrg::Template::Context->new({ ... }),
    });

=item STASH

A reference to a Template::Stash object or sub-class which will take
responsibility for managing template variables.  

    my $stash = MyOrg::Template::Stash->new({ ... });
    my $template = Template->new({
	STASH => $stash,
    });

If unspecified, a default stash object is created using the VARIABLES
configuration item to initialise the stash variables.  These may also
be specified as the PRE_DEFINE option for backwards compatibility with 
version 1.

    my $template = Template->new({
	VARIABLES => {
	    id    => 'abw',
	    name  => 'Andy Wardley',
	},
    };

=item PARSER

The Template::Parser module implements a parser object for compiling
templates into Perl code which can then be executed.  A default object
of this class is created automatically and then used by the
Template::Provider whenever a template is loaded and requires 
compilation.  The PARSER option can be used to provide a reference to 
an alternate parser object.

    my $template = Template->new({
	PARSER => MyOrg::Template::Parser->new({ ... }),
    });

=item GRAMMAR

The GRAMMAR configuration item can be used to specify an alternate
grammar for the parser.  This allows a modified or entirely new
template langauge to be constructed and used by the Template Toolkit.

Source templates are compiled to Perl code by the Template::Parser
using the Template::Grammar (by default) to define the language
structure and semantics.  Compiled templates are thus inherently
"compatible" with each other and there is nothing to prevent any
number of different template languages being compiled and used within
the same Template Toolkit processing environment (other than the usual
time and memory constraints).

The Template::Grammar file is constructed from a YACC like grammar
(using Parse::YAPP) and a skeleton module template.  These files are
provided, along with a small script to rebuild the grammar, in the
'parser' sub-directory of the distribution.  You don't have to know or
worry about these unless you want to hack on the template language or
define your own variant.  There is a README file in the same directory
which provides some small guidance but it is assumed that you know
what you're doing if you venture herein.  If you grok LALR parsers,
then you should find it comfortably familiar.

By default, an instance of the default Template::Grammar will be
created and used automatically if a GRAMMAR item isn't specified.

    use MyOrg::Template::Grammar;

    my $template = Template->new({ 
       	GRAMMAR = MyOrg::Template::Grammar->new();
    });

=back

=head1 TEMPLATE TOOLKIT FILTERS

The following standard filters are distributed with the Template Toolkit.

=over 4

=item html

Converts the characters '<', '>' and '&' to '&lt;', '&gt;' and '&amp',
respectively, protecting them from being interpreted as representing
HTML tags or entities. 

    [% FILTER html %]
    Binary "<=>" returns -1, 0, or 1 depending on...
    [% END %]

output:

    Binary "&lt;=&gt;" returns -1, 0, or 1 depending on...

=item html_para

This filter formats a block of text into HTML paragraphs.  A sequence of 
two or more newlines is used as the delimiter for paragraphs which are 
then wrapped in HTML E<lt>pE<gt>...E<lt>/pE<gt> tags.

    [% FILTER html_para %]
    The cat sat on the mat.

    Mary had a little lamb.
    [% END %]

output:

    <p>
    The cat sat on the mat.
    </p>

    <p>
    Mary had a little lamb.
    </p>

=item html_break

Similar to the html_para filter described above, but uses the HTML tag
sequence E<lt>brE<gt>E<lt>brE<gt> to join paragraphs.

    [% FILTER html_break %]
    The cat sat on the mat.

    Mary had a little lamb.
    [% END %]

output:

    The cat sat on the mat.
    <br>
    <br>
    Mary had a little lamb.

=item format(format)

The 'format' filter takes a format string as a parameter (as per
printf()) and formats each line of text accordingly.

    [% FILTER format('<!-- %-40s -->') %]
    This is a block of text filtered 
    through the above format.
    [% END %]

output:

    <!-- This is a block of text filtered        -->
    <!-- through the above format.               -->

=item truncate(length)

Truncates the text block to the length specified, or a default length of
32.  Truncated text will be terminated with '...' (i.e. the '...' falls
inside the required length, rather than appending to it).

    [% FILTER truncate(21) %]
    I have much to say on this matter that has previously 
    been said on more than one occassion.
    [% END %]

output:

    I have much to say...

=item repeat(iterations)

Repeats the text block for as many iterations as are specified (default: 1).

    [% FILTER repeat(3) %]
    We want more beer and we want more beer,
    [% END %]
    We are the more beer wanters!

output:

    We want more beer and we want more beer,
    We want more beer and we want more beer,
    We want more beer and we want more beer,
    We are the more beer wanters!

=item remove(string) 

Searches the input text for any occurences of the specified string and 
removes them.  A Perl regular expression may be specified as the search 
string.

    [% "The  cat  sat  on  the  mat" FILTER remove('\s+') %]

output: 

    Thecatsatonthemat

=item replace(search, replace) 

Similar to the remove filter described above, but taking a second parameter
which is used as a replacement string for instances of the search string.

    [% "The  cat  sat  on  the  mat" | replace('\s+', '_') %]

output: 

    The_cat_sat_on_the_mat

=item redirect(file)

The 'redirect' filter redirects the output of the block into a separate
file, specified relative to the OUTPUT_PATH configuration item.

    [% FOREACH user = myorg.userlist %]
       [% FILTER redirect("users/${user.id}.html") %]
          [% INCLUDE userinfo %]
       [% END %]
    [% END %]

or more succinctly, using side-effect notation:

    [% INCLUDE userinfo 
         FILTER redirect("users/${user.id}.html")
	   FOREACH user = myorg.userlist 
    %]

A 'file' exception will be thrown if the OUTPUT_PATH option is undefined.

=item eval(template_text)

The 'eval' filter evaluates the block as template text, processing
any directives embedded within it.  This allows template variables to
contain template fragments, or for some method to be provided for
returning template fragments from an external source such as a
database, which can then be processed in the template as required.

    my $vars  = {
	fragment => "The cat sat on the [% place %]",
    };
    $template->process($file, $vars);

The following example:

    [% fragment | eval %]

is therefore equivalent to 

    The cat sat on the [% place %]

The 'evaltt' filter is provided as an alias for 'eval'.

=item perl(perlcode)

The 'perl' filter evaluates the block as Perl code.  The EVAL_PERL
option must be set to a true value or a 'perl' exception will be
thrown.

    [% my_perl_code | perl %]

In most cases, the [% PERL %] ... [% END %] block should suffice for 
evaluating Perl code, given that template directives are processed 
before being evaluate as Perl.  Thus, the previous example could have
been written in the more verbose form:

    [% PERL %]
    [% my_perl_code %]
    [% END %]

as well as

    [% FILTER perl %]
    [% my_perl_code %]
    [% END %]

The 'evalperl' filter is provided as an alias for 'perl' for backwards
compatability.

=item stderr

The stderr filter prints the output generating by the enclosing block to
STDERR 

=back

=head1 TEMPLATE TOOLKIT PLUGINS

The following plugin modules are distributed with the Template
Toolkit.  Some of the plugins interface to external modules (detailed
below) which should be downloaded from any CPAN site and installed
before using the plugin.

=over 4

=item Autoformat

The Autoformat plugin is an interface to Damian Conway's Text::Autoformat 
Perl module which provides advanced text wrapping and formatting.  See
L<Template::Plugin::Autoformat> and L<Text::Autoformat> for further 
details.

    [% USE autoformat(left=10, right=20) %]
    [% autoformat(mytext) %]	    # call autoformat sub
    [% mytext FILTER autoformat %]  # or use autoformat filter

The Text::Autoformat module is available from CPAN:

    http://www.cpan.org/modules/by-module/Text/

=item CGI

The CGI plugin is a wrapper around Lincoln Stein's 
E<lt>lstein@genome.wi.mit.eduE<gt> CGI.pm module.  The plugin is 
distributed with the Template Toolkit (see L<Template::Plugin::CGI>)
and the CGI module itself is distributed with recent versions Perl,
or is available from CPAN.

    [% USE CGI %]
    [% CGI.param('param_name') %]
    [% CGI.start_form %]
    [% CGI.popup_menu( Name   => 'color', 
                       Values => [ 'Green', 'Brown' ] ) %]
    [% CGI.end_form %]

=item Datafile

Provides an interface to data stored in a plain text file in a simple
delimited format.  The first line in the file specifies field names
which should be delimiter by any non-word character sequence.
Subsequent lines define data using the same delimiter as int he first
line.  Blank lines and comments (lines starting '#') are ignored.  See
L<Template::Plugin::Datafile> for further details.

/tmp/mydata:

    # define names for each field
    id : email : name : tel
    # here's the data
    fred : fred@here.com : Fred Smith : 555-1234
    bill : bill@here.com : Bill White : 555-5678

example:

    [% USE userlist = datafile('/tmp/mydata') %]

    [% FOREACH user = userlist %]
       [% user.name %] ([% user.id %])
    [% END %]

=item Date

The Date plugin provides an easy way to generate formatted time and date
strings by delegating to the POSIX strftime() routine.   See
L<Template::Plugin::Date> and L<POSIX> for further details.

    [% USE date %]
    [% date.format %]		# current time/date

    File last modified: [% date.format(template.modtime) %]

=item DBI

The DBI plugin, developed by Simon Matthews
E<lt>sam@knowledgepool.comE<gt>, brings the full power of Tim Bunce's
E<lt>Tim.Bunce@ig.co.ukE<gt> database interface module (DBI) to your
templates.  See L<Template::Plugin::DBI> and L<DBI> for further details.

    [% USE DBI('dbi:driver:database', 'user', 'pass') %]

    [% FOREACH user = DBI.query( 'SELECT * FROM users' ) %]
       [% user.id %] [% user.name %]
    [% END %]

The DBI and relevant DBD modules are available from CPAN:

  http://www.cpan.org/modules/by-module/DBI/

=item Dumper

The Dumper plugin provides an interface to the Data::Dumper module.  See
L<Template::Plugin::Dumper> and L<Data::Dumper> for futher details.

    [% USE dumper(indent=0, pad="<br>") %]
    [% dumper.dump(myvar, yourvar) %]

=item Format

The Format plugin provides a simple way to format text according to a
printf()-like format.   See L<Template::Plugin::Format> for further 
details.

    [% USE bold = format('<b>%s</b>') %]
    [% bold('Hello') %]

=item Iterator

The Iterator plugin provides a way to create a Template::Iterator
object to iterate over a data set.  An iterator is created
automatically by the FOREACH directive and is aliased to the 'loop'
variable.  This plugin allows an iterator to be explicitly created
with a given name, or the default plugin name, 'iterator'.  See
L<Template::Plugin::Iterator> for further details.

    [% USE iterator(list, args) %]

    [% FOREACH item = iterator %]
       [% '<ul>' IF iterator.first %]
       <li>[% item %]
       [% '</ul>' IF iterator.last %]
    [% END %]

=item Table

The Table plugin allows you to format a list of data items into a 
virtual table by specifying a fixed number of rows or columns, with 
an optional overlap.  See L<Template::Plugin::Table> for further 
details.

    [% USE table(list, rows=10, overlap=1) %]

    [% FOREACH item = table.col(3) %]
       [% item %]
    [% END %]

=item URL

The URL plugin provides a simple way of contructing URLs from a base
part and a variable set of parameters.  See L<Template::Plugin::URL>
for further details.

    [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %]

    [% mycgi %]
       # ==> /cgi/bin/bar.pl?debug=1

    [% mycgi(mode='submit') %]
       # ==> /cgi/bin/bar.pl?mode=submit&debug=1

=item Wrap

The Wrap plugin uses the Text::Wrap module by David Muir Sharnoff 
E<lt>muir@idiom.comE<gt> (with help from Tim Pierce and many many others)
to provide simple paragraph formatting.  See L<Template::Plugin::Wrap>
and L<Text::Wrap> for further details.

    [% USE wrap %]
    [% wrap(mytext, 40, '* ', '  ') %]	# use wrap sub
    [% mytext FILTER wrap(40) -%]	# or wrap FILTER

The Text::Wrap module is available from CPAN:

    http://www.cpan.org/modules/by-module/Text/

=item XML::DOM

The XML::DOM plugin gives access to the XML Document Object Module via
Clark Cooper E<lt>cooper@sch.ge.comE<gt> and Enno Derksen's 
E<lt>enno@att.comE<gt> XML::DOM module.  See L<Template::Plugin::XML::DOM> 
and L<XML::DOM> for further details.

    [% USE dom = XML.DOM %]
    [% doc = dom.parse(filename) %]

    [% FOREACH node = doc.getElementsByTagName('CODEBASE') %]
       * [% node.getAttribute('href') %]
    [% END %]

The plugin requires the XML::DOM module, available from CPAN:

    http://www.cpan.org/modules/by-module/XML/

=item XML::XPath

The XML::XPath plugin provides an interface to Matt Sergeant's
E<lt>matt@sergeant.orgE<gt> XML::XPath module.  See 
L<Template::Plugin::XML::XPath> and L<XML::XPath> for further details.

    [% USE xpath = XML.XPath(xmlfile) %]
    [% FOREACH page = xpath.findnodes('/html/body/page') %]
       [% page.getAttribute('title') %]
    [% END %]

The plugin requires the XML::XPath module, available from CPAN:

    http://www.cpan.org/modules/by-module/XML/

=item XML::RSS

The XML::RSS plugin is a simple interface to Jonathan Eisenzopf's
E<lt>eisen@pobox.comE<gt> XML::RSS module.  A RSS (Rich Site Summary)
file is typically used to store short news 'headlines' describing
different links within a site.  This plugin allows you to parse RSS
files and format the contents accordingly using templates.  
See L<Template::Plugin::XML::RSS> and L<XML::RSS> for further details.

    [% USE news = XML.RSS(filename) %]
   
    [% FOREACH item = news.items %]
       <a href="[% item.link %]">[% item.title %]</a>
    [% END %]

The XML::RSS module is available from CPAN:

    http://www.cpan.org/modules/by-module/XML/

=back

=head1 SEE ALSO

The Template Toolkit web site contains the latest information, news and 
other resources.

    http://www.template-toolkit.org/

A mailing list exists for up-to-date information on the Template Toolkit
and for following and contributing to the development process.  To 
subscribe, send an email to

    templates-request@template-toolkit.org

with the message 'subscribe' in the body.  You can also use the web 
interface to subscribe or browse the archives:

    http://www.template-toolkit.org/mailman/listinfo/templates

The F<tpage> and F<ttree> scripts are distributed and installed along
with the Template Toolkit.  The F<tpage> script simply processes named 
files or STDIN if unspecified, using a default Template object.  The 
F<ttree> script can be used to process entire directory trees of templates,
allowing large content systems such as web sites to be rebuilt from a 
single command or configuration file.

    perldoc tpage
    perldoc ttree

The F<Template::Tutorial> document provides an introduction to the Template
Toolkit and shows some typical examples of usage.

    perldoc Template::Tutorial

You may also like to consult the paper 'Building and Managing Web Systems
with the Template Toolkit' and accompanying slides from the presentation
at the 4th Perl Conference.  These are available from the Template
Toolkit web site:

    http://www.template-toolkit.org/docs.html

The following modules comprise the Template Toolkit.  Consult the
individual documentation for further details.

=over 4

=item L<Template::Service|Template::Service>

The Template::Service module handles the template processing
lifecycle, adding PRE_PROCESS and POST_PROCESS templates, handling
redirection through any defined PROCESS template, and dispatching any
ERROR templates to handle uncaught exceptions.  The actual processing
of these templates is handled by an underlying L<Template::Context|Template::Context>
object.

=item L<Template::Context|Template::Context>

The Template::Context module defines a class of objects which each
represent a unique run-time environment in which templates are
processed.  The context maintains references to the stash of variables
currently defined (L<Template::Stash|Template::Stash>) and to provider
objects for templates (L<Template::Provider|Template::Provider>), filters 
(L<Template::Filters|Template::Filters>) and plugins 
(L<Template::Plugins|Template::Plugins>).

=item L<Template::Stash|Template::Stash>

The Template::Stash module defines an object class which is used for 
storing, retrieving and evaluating variables and their values.

=item L<Template::Provider|Template::Provider>

The Template::Provider module defines an object class which is used to
find, load, parse, compile and then cache template documents.  The
cache implements a simple fetch($template) method which will accept a
wide range of inputs (filename, text ref, GLOB, IO::Handle, etc) and
attempt to read the template and call on a L<Template::Parser|Template::Parser> to parse and compile it to a L<Template::Document|Template::Document>
which is then cached.

=item L<Template::Document|Template::Document>

Template::Document objects are thin wrappers around the Perl
subroutines which have been compiled from source templates by the L<Template::Parser|Template::Parser>.  These objects also maintain any metadata
values for the template and have references to any BLOCKs
defined within the the template.

=item L<Template::Parser|Template::Parser>

The Template::Parser module defines an object class which implements
the template parser and compiler.  The template text is first scanned
by a Perl regex which extracts the embedded directives and lexes the
tokens contained within.  A DFA (Deterministic Finite-state Automaton)
then iterates through the tokens using the rules and states defined in
L<Template::Grammar|Template::Grammar> and generates a compiled template
document as a Perl subroutine.

=item L<Template::Grammar|Template::Grammar>

The Template::Grammar module defines the rules and state tables for 
the L<Template::Parser|Template::Parser> DFA.  These are generated 
by the Parse::Yapp module.  The Template-Toolkit distribution 
contains a B<parser> directory which contains further files and 
information concerning the grammar and compilation thereof.

=item L<Template::Directive|Template::Directive>

This module implements a number of factory methods which are used by
the L<Template::Parser|Template::Parser> to generate Perl code from source
templates.

=item L<Template::Filters|Template::Filters>

This module implements the various FILTER subroutines and provides a 
simple interface through which filter subs can be retrieved.

=item L<Template::Plugins|Template::Plugins>

This module provides access to the standard Template Toolkit or user
defined plugin modules.

=item L<Template::Plugin|Template::Plugin>

Base class for Template::Plugin::* modules.

=item L<Template::Exception|Template::Exception>

The Template::Exception module defines an exception type 
for representing error conditions within the Template Toolkit.

=item L<Template::Iterator|Template::Iterator>

The Template::Iterator module defines a data iterator which is used 
by the FOREACH directive.  This may be sub-classed to create more 
specialised iterators for traversing data sets.

=item L<Template::Constants|Template::Constants>

Defines various constants used in the Template Toolkit.

=item L<Template::Config|Template::Config>

Implements a number of factory methods through which other Template::*
modules can be automatically loaded and instantiated.

=item L<Template::Base|Template::Base>

A common base class for many Template::* modules.

=item L<Template::Test|Template::Test>

Module for testing the Template Toolkit, primarily used by the test
scripts in the 't' distribution sub-directory.

=back





=head1 AUTHOR

Andy Wardley E<lt>abw@kfs.orgE<gt>

    http://www.template-toolkit.org/
    http://www.kfs.org/~abw/

=head1 COPYRIGHT

    Copyright (C) 1996-2000 Andy Wardley.  All Rights Reserved.
    Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 ACKNOWLEDGEMENTS

The Template Toolkit was derived in part from ideas and techniques
developed in the Text::MetaText module.  This itself was the public
manifestation of an earlier template processing system I developed
while working at Peritas Ltd. (http://www.knowledgepool.com/).

In later years, the Template Toolkit was developed at Canon Research
Centre Europe Ltd. (http://www.cre.canon.co.uk) as part of a general
research theme into Web-related publishing and dynamic content
generation.

Many people have contributed ideas, inspiration, fixes and features to
the Template Toolkit.  Their efforts continue to be very much appreciated.  
Please let me know if you think anyone is missing from this list.

  Chuck Adams               <scrytch@uswest.net>
  Thierry-Michel Barral     <kktos@electron-libre.com>
  Stas Beckman		    <stas@stason.org>
  Neil Bowers               <neilb@cre.canon.co.uk>
  Leon Brocard              <acme@astray.com>  
  Piers Cawley              <pdcawley@bofh.org.uk>
  Chris Dean                <ctdean@babycenter.com>  
  Francois Desarmenien      <desar@club-internet.fr>
  Horst Dumcke              <hdumcke@cisco.com> 
  Michael Fowler            <michael@shoebox.net>    
  Perrin Harkins            <pharkins@etoys.com>
  Rafael Kitover            <caelum@debian.org>
  Hans von Lengerke         <hans@lengerke.org>
  Jonas Liljegren           <jonas@paranormal.se>
  Simon Matthews            <sam@knowledgepool.com>
  Craig McLane              <mclanec@oxy.edu>     
  Leslie Michael Orchard    <deus_x@ninjacode.com>
  Eugene Miretskiy          <eugene@invision.net>
  Chris Nandor              <pudge@pobox.com>
  Martin Portman            <mrp@cre.canon.co.uk>
  Randal L. Schwartz        <merlyn@stonehenge.com>
  Paul Sharpe               <paul@miraclefish.com>
  Doug Steinwand            <dsteinwand@etoys.com>
  Michael Stevens           <michael@etla.org>
  Drew Taylor               <dtaylor@vialogix.com>   
  Swen Thuemmler            <Swen.Thuemmler@paderlinx.de>   
  Jim Vaughan               <jim@mrjim.com> 
  Chris Winters             <cwinters@intes.net>