# Template::Manual::Config - phpMan

## NAME
    [Template::Manual::Config] - Configuration options

Template Style and Parsing Options
  ENCODING
    The "ENCODING" option specifies the template files' character encoding:

        my $template = Template->new({
            ENCODING => 'utf8',
        });

    A template which starts with a Unicode byte order mark (BOM) will have
    its encoding detected automatically.

  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 inline
    template directives. 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 "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 <+ +> %]

  OUTLINE_TAG
    The "OUTLINE_TAG" option can be used to enable single-line "outline"
    directives.

        my $template = Template->new({
            OUTLINE_TAG => '%%',
        });

    This allows you to use both inline and outline tags like so:

        %% IF user
        Hello [% user.name %]
        %% END

    The "OUTLINE_TAG" string (or regex) must appear at the start of a line.
    The directive continues until the end of the line. The newline character
    at the end of the line is considered to be the invisible
    end-of-directive marker and is removed.

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

    Available styles are:

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

    The "outline" style uses the default markers for "START_TAG" and
    "END_TAG" ("[%" and "%]" respectively) and additionally defines
    "OUTLINE_TAG" to be "%%".

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

    This allows you to use both inline and outline tags like so:

        %% IF user
        Hello [% user.name %]
        %% END

    Any values specified for "START_TAG", "END_TAG" and/or "OUTLINE_TAG"
    will override those defined by a "TAG_STYLE".

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

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

  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-E<gt>new({
            PRE_CHOMP  => 1,
            POST_CHOMP => 1,
        });

    With "PRE_CHOMP" set to 1, the newline and whitespace preceding 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 to 1, 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.

    If "PRE_CHOMP" or "POST_CHOMP" is set to 2, all whitespace including any
    number of newline will be removed and replaced with a single space. This
    is useful for HTML, where (usually) a contiguous block of whitespace is
    rendered the same as a single space.

    With "PRE_CHOMP" or "POST_CHOMP" set to 3, all adjacent whitespace
    (including newlines) will be removed entirely.

    These values are defined as "CHOMP_NONE", "CHOMP_ONE", "CHOMP_COLLAPSE"
    and "CHOMP_GREEDY" constants in the [Template::Constants] module.
    "CHOMP_ALL" is also defined as an alias for "CHOMP_ONE" to provide
    backwards compatibility with earlier version of the Template Toolkit.

    Additionally the chomp tag modifiers listed below may also be used for
    the "PRE_CHOMP" and "POST_CHOMP" configuration.

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

    "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 IN userlist %]
           [%- user -%]
        [% END %]

    This has the same effect as "CHOMP_ONE" in removing all whitespace
    before or after the directive up to and including the newline. The
    template will be processed as if written:

        [% FOREACH user IN userlist %][% user %][% END %]

    To remove all whitespace including any number of newlines, use the '"~"'
    character instead.

        [% FOREACH user IN userlist %]

           [%~ user ~%]

        [% END %]

    To collapse all whitespace to a single space, use the '"="' character.

        [% FOREACH user IN userlist %]

           [%= user =%]

        [% END %]

    Here the template is processed as if written:

        [% FOREACH user IN userlist %] [% user %] [% END %]

    If you have "PRE_CHOMP" or "POST_CHOMP" set as configuration options
    then you can use '"+"' to disable any chomping options (i.e. leave the
    whitespace intact) on a per-directive basis.

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

    With "POST_CHOMP" set to "CHOMP_ONE", the above example would be parsed
    as if written:

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

    For reference, the "PRE_CHOMP" and "POST_CHOMP" configuration options
    may be set to any of the following:

         Constant      Value   Tag Modifier
         ----------------------------------
         CHOMP_NONE      0          +
         CHOMP_ONE       1          -
         CHOMP_COLLAPSE  2          =
         CHOMP_GREEDY    3          ~

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

    By example, the following "BLOCK" definition

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

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

        before
        [% INCLUDE foo %]
        after

    Generated 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.

  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".

  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

Template Files and Blocks
  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 '":"'.

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

    On Win32 systems, a little extra magic is invoked, ignoring delimiters
    that have '":"' followed by a '"/"' or '"\"'. This avoids confusion when
    using directory names like '"C:\Blah Blah"'.

    When specified as a list, the "INCLUDE_PATH" path can contain elements
    which dynamically generate a list of "INCLUDE_PATH" directories. These
    generator elements can be specified as a reference to a subroutine or an
    object which implements a "paths()" method.

        my $template = Template->new({
            INCLUDE_PATH => [ '/usr/local/templates',
                              \&incpath_generator,
                              [My::IncPath::Generator]->new( ... ) ],
        });

    Each time a template is requested and the "INCLUDE_PATH" examined, the
    subroutine or object method will be called. A reference to a list of
    directories should be returned. Generator subroutines should report
    errors using "die()". Generator objects should return undef and make an
    error available via its "error()" method.

    For example:

        sub incpath_generator {
            # ...some code...

            if ($all_is_well) {
                return \@list_of_directories;
            }
            else {
                die "cannot generate INCLUDE_PATH...\n";
            }
        }

    or:

        package [My::IncPath::Generator];

        # [Template::Base] (or [Class::Base]) provides error() method
        use [Template::Base];
        use base qw( [Template::Base] );

        sub paths {
            my $self = shift;

            # ...some code...

            if ($all_is_well) {
                return \@list_of_directories;
            }
            else {
                return $self->error("cannot generate INCLUDE_PATH...\n");
            }
        }

        1;

  DELIMITER
    Used to provide an alternative delimiter character sequence for
    separating paths specified in the "INCLUDE_PATH". The default value for
    "DELIMITER" is '":"'.

        my $template = Template->new({
            DELIMITER    => '; ',
            INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
        });

    On Win32 systems, the default delimiter is a little more intelligent,
    splitting paths only on '":"' characters that aren't followed by a
    '"/"'. This means that the following should work as planned, splitting
    the "INCLUDE_PATH" into 2 separate directories, "C:/foo" and "C:/bar".

        # on Win32 only
        my $template = Template->new({
            INCLUDE_PATH => 'C:/Foo:C:/Bar'
        });

    However, if you're using Win32 then it's recommended that you explicitly
    set the "DELIMITER" character to something else (e.g. '";"') rather than
    rely on this subtle magic.

  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 %]

    On Win32 systems, the regular expression for matching absolute pathnames
    is tweaked slightly to also detect filenames that start with a driver
    letter and colon, such as:

        C:/Foo/Bar

  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 %]

  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-existent 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.

  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({ ... }),
            },
        });

  VIEWS
    The VIEWS option can be used to define one or more [Template::View]
    objects. They can be specified as a reference to a hash array or list
    reference.

        my $template = Template->new({
            VIEWS => {
                my_view => { prefix => 'my_templates/' },
            },
        });

    Be aware of the fact that Perl's hash array are unordered, so if you
    want to specify multiple views of which one or more are based on other
    views, then you should use a list reference to preserve the order of
    definition.

        my $template = Template->new({
            VIEWS => [
                bottom => { prefix => 'bottom/' },
                middle => { prefix => 'middle/', base => 'bottom' },
                top    => { prefix => 'top/',    base => 'middle' },
            ],
        });

  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 "BLOCK"s defined within
    a template will only persist until that template is finished processing.
    This prevents "BLOCK"s defined in one processing request from
    interfering with other independent 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.

  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.

Template Variables
  VARIABLES
    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,
            },
        };

  CONSTANTS
    The "CONSTANTS" option can be used to specify a hash array of template
    variables that are compile-time constants. These variables are resolved
    once when the template is compiled, and thus don't require further
    resolution at runtime. This results in significantly faster processing
    of the compiled templates and can be used for variables that don't
    change from one request to the next.

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

  CONSTANT_NAMESPACE
    Constant variables are accessed via the "constants" namespace by
    default.

        [% constants.title %]

    The "CONSTANTS_NAMESPACE" option can be set to specify an alternate
    namespace.

        my $template = Template->new({
            CONSTANTS => {
                title   => 'A Demo Page',
                # ...etc...
            },
            CONSTANTS_NAMESPACE => 'const',
        };

    In this case the constants would then be accessed as:

        [% const.title %]

  NAMESPACE
    The constant folding mechanism described above is an example of a
    namespace handler. Namespace handlers can be defined to provide
    alternate parsing mechanisms for variables in different namespaces.

    Under the hood, the Template module converts a constructor configuration
    such as:

        my $template = Template->new({
            CONSTANTS => {
                title   => 'A Demo Page',
                # ...etc...
            },
            CONSTANTS_NAMESPACE => 'const',
        };

    into one like:

        my $template = Template->new({
            NAMESPACE => {
                const => Template:::[Namespace::Constants]->new({
                    title   => 'A Demo Page',
                    # ...etc...
                }),
            },
        };

    You can use this mechanism to define multiple constant namespaces, or to
    install custom handlers of your own.

        my $template = Template->new({
            NAMESPACE => {
                site => Template:::[Namespace::Constants]->new({
                    title   => "Wardley's Widgets",
                    version => 2.718,
                }),
                author => Template:::[Namespace::Constants]->new({
                    name  => 'Andy Wardley',
                    email => '<abw@andywardley.com>',
                }),
                voodoo => [My::Namespace::Handler]->new( ... ),
            },
        };

    Now you have two constant namespaces, for example:

        [% site.title %]
        [% author.name %]

    as well as your own custom namespace handler installed for the 'voodoo'
    namespace.

        [% voodoo.magic %]

    See [Template::Namespace::Constants] for an example of what a namespace
    handler looks like on the inside.

Template Processing Options
    The following options are used to specify any additional templates that
    should be processed before, after, around or instead of the template
    passed as the first argument to the Template process() method. These
    options can be perform various useful tasks such as adding standard
    headers or footers to all pages, wrapping page output in other
    templates, pre-defining variables or performing initialisation or
    cleanup tasks, automatically generating page summary information,
    navigation elements, and so on.

    The task of processing the template is delegated internally to the
    [Template::Service] module which, unsurprisingly, also has a process()
    method. Any templates defined by the "PRE_PROCESS" option are processed
    first and any output generated is added to the output buffer. Then the
    main template is processed, or if one or more "PROCESS" templates are
    defined then they are instead processed in turn. In this case, one of
    the "PROCESS" templates is responsible for processing the main template,
    by a directive such as:

        [% PROCESS $template %]

    The output of processing the main template or the "PROCESS" template(s)
    is then wrapped in any "WRAPPER" templates, if defined. "WRAPPER"
    templates don't need to worry about explicitly processing the template
    because it will have been done for them already. Instead "WRAPPER"
    templates access the content they are wrapping via the "content"
    variable.

        wrapper before
        [% content %]
        wrapper after

    This output generated from processing the main template, and/or any
    "PROCESS" or "WRAPPER" templates is added to the output buffer. Finally,
    any "POST_PROCESS" templates are processed and their output is also
    added to the output buffer which is then returned.

    If the main template throws an exception during processing then any
    relevant template(s) defined via the "ERROR" option will be processed
    instead. If defined and successfully processed, the output from the
    error template will be added to the output buffer in place of the
    template that generated the error and processing will continue, applying
    any "WRAPPER" and "POST_PROCESS" templates. If no relevant "ERROR"
    option is defined, or if the error occurs in one of the "PRE_PROCESS",
    "WRAPPER" or "POST_PROCESS" templates, then the process will terminate
    immediately and the error will be returned.

  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 subsequent 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 %]">

  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>
        <!-- begin content -->
        [% PROCESS $template %]
        <!-- end content -->
            <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>
        <!-- begin content -->
        <h1>The Foo Page</h1>
        Welcome to the Foo Page, blah blah blah
        <!-- end content -->
            <hr>
            &copy; Copyright 2000 Fred Foo
          </body>
        </html>

  WRAPPER
    The "WRAPPER" option can be used to specify one or more templates which
    should be used to wrap around the output of the main page template. The
    main template is processed first (or any "PROCESS" template(s)) and the
    output generated is then passed as the "content" variable to the
    "WRAPPER" template(s) as they are processed.

        my $template = Template->new({
            WRAPPER => 'wrapper',
        };

        # process 'foo' then wrap in 'wrapper'
        $template->process('foo', { message => 'Hello World!' });

    wrapper:

        <wrapper>
        [% content %]
        </wrapper>

    foo:

        This is the foo file!
        Message: [% message %]

    The output generated from this example is:

        <wrapper>
        This is the foo file!
        Message: Hello World!
        </wrapper>

    You can specify more than one "WRAPPER" template by setting the value to
    be a reference to a list of templates. The "WRAPPER" templates will be
    processed in reverse order with the output of each being passed to the
    next (or previous, depending on how you look at it) as the 'content'
    variable. It sounds complicated, but the end result is that it just
    "Does The Right Thing" to make wrapper templates nest in the order you
    specify.

        my $template = Template->new({
            WRAPPER => [ 'outer', 'inner' ],
        };

        # process 'foo' then wrap in 'inner', then in 'outer'
        $template->process('foo', { message => 'Hello World!' });

    outer:

        <outer>
        [% content %]
        </outer>

    inner:

        <inner>
        [% content %]
        </inner>

    The output generated is then:

        <outer>
        <inner>
        This is the foo file!
        Message: Hello World!
        </inner>
        </outer>

    One side-effect of the "inside-out" processing of the "WRAPPER"
    configuration item (and also the "WRAPPER" directive) is that any
    variables set in the template being wrapped will be visible to the
    template doing the wrapping, but not the other way around.

    You can use this to good effect in allowing page templates to set
    pre-defined values which are then used in the wrapper templates. For
    example, our main page template 'foo' might look like this:

    foo:

        [% page = {
               title    = 'Foo Page'
               subtitle = 'Everything There is to Know About Foo'
               author   = 'Frank Oliver Octagon'
           }
        %]

        <p>
        Welcome to the page that tells you everything about foo
        blah blah blah...
        </p>

    The "foo" template is processed before the wrapper template meaning that
    the "page" data structure will be defined for use in the wrapper
    template.

    wrapper:

        <html>
          <head>
            <title>[% page.title %]</title>
          </head>
          <body>
            <h1>[% page.title %]</h1>
            <h2>[% page.subtitle %]</h1>
            <h3>by [% page.author %]</h3>
            [% content %]
          </body>
        </html>

    It achieves the same effect as defining "META" items which are then
    accessed via the "template" variable (which you are still free to use
    within "WRAPPER" templates), but gives you more flexibility in the type
    and complexity of data that you can define.

  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. "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";

    Note that the '"undef"' we're talking about here is a literal string
    rather than Perl's "undef" used to represent undefined values.

Template Runtime Options
  EVAL_PERL
    This flag is used to indicate if "PERL" and/or "RAWPERL" blocks should
    be evaluated. It is disabled by default 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 "Caching and Compiling Options"), 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
    always throws a '"perl"' exception with the message '"EVAL_PERL not
    set"' 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 *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.

  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; as a
    reference to an array, onto which the content will be "push()"ed; 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 (array reference):

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

    example 6 (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, \$output);
        $t->process($file, $vars, \*MYGLOB);
        $t->process($file, $vars, \@output);
        $t->process($file, $vars, $r);  # [Apache::Request]
        ...

  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 parameter to the Template
    process() method.

        my $template = Template->new({
            INCLUDE_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.

  STRICT
    By default the Template Toolkit will silently ignore the use of
    undefined variables (a bad design decision that I regret).

    When the "STRICT" option is set, the use of any undefined variables or
    values will cause an exception to be throw. The exception will have a
    "type" of "var.undefined" and a message of the form "undefined variable:
    xxx".

        my $template = Template->new(
            STRICT => 1
        );

  DEBUG
    The "DEBUG" option can be used to enable debugging within the various
    different modules that comprise the Template Toolkit. The
    [Template::Constants] module defines a set of "DEBUG_XXXX" constants which
    can be combined using the logical OR operator, '"|"'.

        use [Template::Constants] qw( :debug );

        my $template = Template->new({
            DEBUG => DEBUG_PARSER | DEBUG_PROVIDER,
        });

    For convenience, you can also provide a string containing a list of
    lower case debug options, separated by any non-word characters.

        my $template = Template->new({
            DEBUG => 'parser, provider',
        });

    The following "DEBUG_XXXX" flags can be used:

    DEBUG_SERVICE
        Enables general debugging messages for the [Template::Service] module.

    DEBUG_CONTEXT
        Enables general debugging messages for the [Template::Context] module.

    DEBUG_PROVIDER
        Enables general debugging messages for the [Template::Provider]
        module.

    DEBUG_PLUGINS
        Enables general debugging messages for the [Template::Plugins] module.

    DEBUG_FILTERS
        Enables general debugging messages for the [Template::Filters] module.

    DEBUG_PARSER
        This flag causes the [Template::Parser] to generate debugging messages
        that show the Perl code generated by parsing and compiling each
        template.

    DEBUG_UNDEF
        This option causes the Template Toolkit to throw an '"undef"' error
        whenever it encounters an undefined variable value.

    DEBUG_DIRS
        This option causes the Template Toolkit to generate comments
        indicating the source file, line and original text of each directive
        in the template. These comments are embedded in the template output
        using the format defined in the "DEBUG_FORMAT" configuration item,
        or a simple default format if unspecified.

        For example, the following template fragment:

            Hello World

        would generate this output:

            ## input text line 1 :  ##
            Hello
            ## input text line 2 : World ##
            World

    DEBUG_ALL
        Enables all debugging messages.

    DEBUG_CALLER
        This option causes all debug messages that aren't newline terminated
        to have the file name and line number of the caller appended to
        them.

  DEBUG_FORMAT
    The "DEBUG_FORMAT" option can be used to specify a format string for the
    debugging messages generated via the "DEBUG_DIRS" option described
    above. Any occurrences of $file, $line or $text will be replaced with
    the current file name, line or directive text, respectively. Notice how
    the format is single quoted to prevent Perl from interpolating those
    tokens as variables.

        my $template = Template->new({
            DEBUG => 'dirs',
            DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->',
        });

    The following template fragment:

        [% foo = 'World' %]
        Hello [% foo %]

    would then generate this output:

        <!-- input text line 2 : [% foo = 'World' %] -->
        Hello <!-- input text line 3 : [% foo %] -->World

    The DEBUG directive can also be used to set a debug format within a
    template.

        [% DEBUG format '<!-- $file line $line : [% $text %] -->' %]

Caching and Compiling Options
  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
        });

    As well as caching templates as they are found, the [Template::Provider]
    also implements negative caching to keep track of templates that are
    *not* found. This allows the provider to quickly decline a request for a
    template that it has previously failed to locate, saving the effort of
    going to look for it again. This is useful when an "INCLUDE_PATH"
    includes multiple providers, ensuring that the request is passed down
    through the providers as quickly as possible.

  STAT_TTL
    This value can be set to control how long the [Template::Provider] will
    keep a template cached in memory before checking to see if the source
    template has changed.

        my $provider = [Template::Provider]->new({
            STAT_TTL => 60,  # one minute
        });

    The default value is 1 (second). You'll probably want to set this to a
    higher value if you're running the Template Toolkit inside a persistent
    web server application (e.g. mod_perl). For example, set it to 60 and
    the provider will only look for changes to templates once a minute at
    most. However, during development (or any time you're making frequent
    changes to templates) you'll probably want to keep it set to a low value
    so that you don't have to wait for the provider to notice that your
    templates have changed.

  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 persistence). 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 persistence 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.

  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.

    On Win32 platforms a filename may by prefixed by a drive letter and
    colon. e.g.

        C:/My Templates/header

    The colon will be silently stripped from the filename when it is added
    to the "COMPILE_DIR" value(s) to prevent illegal filename being
    generated. Any colon in "COMPILE_DIR" elements will be left intact. For
    example:

        # Win32 only
        my $template = Template->new({
            DELIMITER    => ';',
            COMPILE_DIR  => 'C:/TT2/Cache',
            INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
        });

    This would create the following cache directories:

        C:/TT2/Cache/C/TT2/Templates
        C:/TT2/Cache/D/My Templates

Plugins and Filters
  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", "format", "cgi", 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 recommended convention is to specify these plugin names in lower
    case. The Template Toolkit first looks for an exact case-sensitive match
    and then tries the lower case conversion of the name specified.

        [% USE Foo %]      # look for 'Foo' then 'foo'

    If you define all your "PLUGINS" with lower case names then they will be
    located regardless of how the user specifies the name in the USE
    directive. If, on the other hand, you define your "PLUGINS" with upper
    or mixed case names then the name specified in the "USE" directive must
    match the case exactly.

    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.

  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 reference to an array of module
    namespaces, or as a single value which is automatically converted to a
    list. The default "PLUGIN_BASE" value ("[Template::Plugin]") is then added
    to the end of this list.

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

    template:

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

    If you don't want the default "[Template::Plugin]" namespace added to the
    end of the "PLUGIN_BASE", then set the $[Template::Plugins::PLUGIN_BASE]
    variable to a false value before calling the new() Template#new()
    constructor method. This is shown in the example below where the "Foo"
    plugin is located as "[My::Plugin::Foo]" or "[Your::Plugin::Foo]" but not as
    "[Template::Plugin::Foo]".

    example 3:

        use [Template::Plugins];
        $[Template::Plugins::PLUGIN_BASE] = '';

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

    template:

        [% USE Foo %]    # =>   [My::Plugin::Foo]
                           or [Your::Plugin::Foo]

  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.

  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.

Customisation and Extension
  LOAD_TEMPLATES
    The "LOAD_TEMPLATES" 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 responsibility 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.

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

  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::Context] 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,
        });

  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.

  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.

  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({ ... }),
        });

  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 "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({ ... }),
        });

  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.

        my $template = Template->new({
            VARIABLES => {
                id    => 'abw',
                name  => 'Andy Wardley',
            },
        };

  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({ ... }),
        });

  GRAMMAR
    The "GRAMMAR" configuration item can be used to specify an alternate
    grammar for the parser. This allows a modified or entirely new template
    language 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();
        });