Provided by: libtemplate-perl_2.24-1.1_amd64 bug

NAME

       Template::Manual::Config - Configuration options

Template Style and Parsing Options

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

   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)

       Any values specified for "START_TAG" and/or "END_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 compatability 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-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.

   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 occurances 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 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();
           });