CGI::Ex 2.13

[chaz/p5-CGI-Ex] / lib / CGI / Ex / Template.pod

=head1 NAME

CGI::Ex::Template - Fast and lightweight TT2/3 template engine

=head1 SYNOPSIS

    ### Template::Toolkit style usage

    my $t = CGI::Ex::Template->new(
        INCLUDE_PATH => ['/path/to/templates'],
    );

    my $swap = {
        key1 => 'val1',
        key2 => 'val2',
        code => sub { 42 },
        hash => {a => 'b'},
    };

    # print to STDOUT
    $t->process('my/template.tt', $swap)
        || die $t->error;

    # process into a variable
    my $out = '';
    $t->process('my/template.tt', $swap, \$out);

    ### CET uses the same syntax and configuration as Template::Toolkit


    ### HTML::Template style usage

    my $t = CGI::Ex::Template->new(
        filename => 'my/template.ht',
        path     => ['/path/to/templates'],
    );

    my $swap = {
        key1 => 'val1',
        key2 => 'val2',
        code => sub { 42 },
        hash => {a => 'b'},
    };

    $t->param($swap);

    # print to STDOUT (errors die)
    $t->output(print_to => \*STDOUT);

    # process into a variable
    my $out = $t->output;

    ### CET can also use the same syntax and configuration as HTML::Template

=head1 DESCRIPTION

CGI::Ex::Template happened by accident (accidentally on purpose).  The
CGI::Ex::Template (CET hereafter) was originally a part of the CGI::Ex
suite that performed simple variable interpolation.  It used TT2 style
variables in TT2 style tags "[% foo.bar %]".  That was all the
original CGI::Ex::Template did.  This was fine and dandy for a couple
of years.  In winter of 2005-2006 CET was revamped to add a few
features.  One thing led to another and soon CET provided for most of
the features of TT2 as well as some from TT3.  CGI::Ex::Template is a
full-featured implementation of the Template::Toolkit language.

As of version 2.13, CGI::Ex::Template also provides near full
compatibility with HTML::Template (HT), HTML::Template::JIT (HTJ), and
HTML::Template::Expr (HTE).  Version 2.13 introduced the SYNTAX
configuration allowing for inclusion of TT style templates in HT and
vice versa.  It also provided the HTML::Template output and param
methods which allow CET to provide the HTML::Template interface.  It
was possible to add this extra functionality because CGI::Ex::Template
employs an open architecture.

CGI::Ex::Template uses a recursive regex based grammar (early versions
before the 2.10 release did not).  This allows for the embedding of
opening and closing tags inside other tags (as in [% a = "[% 1 + 2 %]"
; a|eval %]).  The individual methods such as parse_expr and play_expr
may be used by external applications to add TT style variable parsing
to other applications.

CGI::Ex::Template is fast but CGI::Ex::Template::XS is even faster.
If CGI::Ex::Template isn't fast enough for you, the XS version has key
methods coded in C and provides a noticable improvement over the
non-XS version.  CET by itself is generally faster than TT, HT, and HTE.
The XS version is nearly always faster - even than HTJ.  CET also uses less
memory than TT and HTE, and only a little more than HT.  (This is all
as of version 2.13 in May 2007 - those other modules will undoubtedly
receive updates that will improve their performance).

Most of the standard Template::Toolkit documentation covering
directives, variables, configuration, plugins, filters, syntax, and
vmethods should apply to CET just fine (This pod tries to explain
everything - but there is too much).  The section on differences
between CET and TT will explain what too look out for.

Additionally, most of the standard HTML::Template and
HTML::Template::Expr documentation covering methods, variables,
expressions, and syntax will apply to CET just fine as well.

So should you use CGI::Ex::Template ?  Well, try it out.  It may
give you no visible improvement.  Or it could.

=head1 PUBLIC METHODS

The following section lists most of the publicly available methods.  Some less
commonly used public methods are listed later in this document.

=over 4

=item C<new>

    my $obj = CGI::Ex::Template->new({
        INCLUDE_PATH => ['/my/path/to/content', '/my/path/to/content2'],
    });

Arguments may be passed as a hash or as a hashref.  Returns a CGI::Ex::Template object.

There are currently no errors during CGI::Ex::Template object creation.  If you are
using the HTML::Template interface, this is different behavior.  The document is
not parsed until the output or process methods are called.

=item C<process>

This is the main method call for starting processing.  Any errors that result in the
template processing being stopped will be stored and available via the ->error method.
This is the TT compatible method - see the output method for HT compatibility.

    my $t = CGI::Ex::Template->new;
    $t->process($in, $swap, $out)
        || die $t->error;

Process takes three arguments.

The $in argument can be any one of:

    String containing the filename of the template to be processed.  The filename should
    be relative to INCLUDE_PATH.  (See INCLUDE_PATH, ABSOLUTE, and RELATIVE configuration items).
    In memory caching and file side caching are available for this type.

    A reference to a scalar containing the contents of the template to be processed.

    A coderef that will be called to return the contents of the template.

    An open filehandle that will return the contents of the template when read.

The $swap argument should be hashref containing key value pairs that will be
available to variables swapped into the template.  Values can be hashrefs, hashrefs
of hashrefs and so on, arrayrefs, arrayrefs of arrayrefs and so on, coderefs, objects,
and simple scalar values such as numbers and strings.  See the section on variables.

The $out argument can be any one of:

    undef - meaning to print the completed template to STDOUT.

    String containing a filename.  The completed template will be placed in the file.

    A reference to a string.  The contents will be appended to the scalar reference.

    A coderef.  The coderef will be called with the contents as a single argument.

    An object that can run the method "print".  The contents will be passed as
    a single argument to print.

    An arrayref.  The contents will be pushed onto the array.

    An open filehandle.  The contents will be printed to the open handle.

Additionally - the $out argument can be configured using the OUTPUT configuration
item.

The process method defaults to using the "cet" syntax which will parse TT3 and most
TT2 documents.  To parse HT or HTE documents, you must pass the SYNTAX configuration
item to the "new" method.  All calls to process would then default to HTE syntax.

    my $obj = CGI::Ex::Template->new(SYNTAX => 'hte');

=item C<process_simple>

Similar to the process method but with the following restrictions:

The $in parameter is limited to a filename or a reference a string containing the contents.

The $out parameter may only be a reference to a scalar string that output will be appended to.

Additionally, the following configuration variables will be ignored:  VARIABLES,
PRE_DEFINE, BLOCKS, PRE_PROCESS, PROCESS, POST_PROCESS, AUTO_RESET, OUTPUT.

=item C<error>

Should something go wrong during a "process" command, the error that occurred can
be retrieved via the error method.

    $obj->process('somefile.html', {a => 'b'}, \$string_ref)
        || die $obj->error;

=item C<output>

HTML::Template way to process a template.  The output method requires that a filename,
filehandle, scalarref, or arrayref argument was passed to the new method.  All of
the HT calling conventions for new are supported.  The key difference is that CET will
not actually process the template until the output method is called.

    my $obj = CGI::Ex::Template->new(filename => 'myfile.html');
    $obj->param(\%swap);
    print $obj->output;

See the HTML::Template documentation for more information.

The output method defaults to using the "hte" syntax which will parse HTE and HT documents.
To parse TT3 or TT2 documents, you must pass the SYNTAX configuration
item to the "new" method.  All calls to process would then default to TT3 syntax.

    my $obj = CGI::Ex::Template->new(SYNTAX => 'tt3');

Any errors that occur during the output method will die with the error as the die value.

=item C<param>

HTML::Template way to get or set variable values that will be used by the output method.

    my $val = $obj->param('key'); # get one value

    $obj->param(key => $val);     # set one value

    $obj->param(key => $val, key2 => $val2);   # set multiple

    $obj->param({key => $val, key2 => $val2}); # set multiple

See the HTML::Template documentation for more information.

Note: CET does not support the die_on_bad_params configuration.  This is because CET
does not resolve variable names until the output method is called.

=item C<define_vmethod>

This method is available for defining extra Virtual methods or filters.  This method is similar
to Template::Stash::define_vmethod.

    CGI::Ex::Template->define_vmethod(
        'text',
        reverse => sub { my $item = shift; return scalar reverse $item },
    );

=item C<register_function>

This is the HTML::Template way of defining text vmethods.  It is the same as
calling define_vmethod with "text" as the first argument.

    CGI::Ex::Template->register_function(
        reverse => sub { my $item = shift; return scalar reverse $item },
    );

=item C<define_directive>

This method can be used for adding new directives or overridding existing
ones.

   CGI::Ex::Template->define_directive(
       MYDIR => {
           parse_sub => sub {}, # parse additional items in the tag
           play_sub  => sub {
               my ($self, $ref, $node, $out_ref) = @_;
               $$out_ref .= "I always say the same thing!";
               return;
           },
           is_block  => 1,  # is this block like
           is_postop => 0,  # not a post operative directive
           no_interp => 1,  # no interpolation in this block
           continues => undef, # it doesn't "continue" any other directives
       },
   );

Now with a template like:

   my $str = "([% MYDIR %]This is something[% END %])";
   CGI::Ex::Template->new->process(\$str);

You will get:

   (I always say the same thing!)

We'll add more details in later revisions of this document.

=item C<define_syntax>

This method can be used for adding other syntaxes to or overridding
existing ones in the list of choices available in CET.  The syntax can
be chosen by the SYNTAX configuration item.

    CGI::Ex::Template->define_syntax(
        my_uber_syntax => sub {
            my $self = shift;
            local $self->{'V2PIPE'}      = 0;
            local $self->{'V2EQUALS'}    = 0;
            local $self->{'PRE_CHOMP'}   = 0;
            local $self->{'POST_CHOMP'}  = 0;
            local $self->{'NO_INCLUDES'} = 0;
            return $self->parse_tree_tt3(@_);
        },
    );

The subroutine that is used must return an opcode tree (AST) that
can be played by the execute_tree method.

=item C<define_operator>

This method allows for adding new operators or overriding existing ones.

    CGI::Ex::Template->define_operator({
        type       => 'right', # can be one of prefix, postfix, right, left, none, ternary, assign
        precedence => 84,      # relative precedence for resolving multiple operators without parens
        symbols    => ['foo', 'FOO'], # any mix of chars can be used for the operators
        play_sub   => sub {
            my ($one, $two) = @_;
            return "You've been foo'ed ($one, $two)";
        },
    });

You can then use it in a template as in the following:

   my $str = "[% 'ralph' foo 1 + 2 * 3 %]";
   CGI::Ex::Template->new->process(\$str);

You will get:

   You've been foo'ed (ralph, 7)

Future revisions of this document will include more samples.

=back

=head1 TODO

Move module to its own namespace.

Cleanup operator API to allow for easier full customization of
operators.

Give better examples of overriding directives, syntax, and operators.

Add more functions to the XS version.

Find other syntaxes to include.

=head1 HOW IS CGI::Ex::Template DIFFERENT from Template::Toolkit

CET uses the same base template syntax and configuration items as TT2,
but the internals of CET were written from scratch.  Additionally much
of the planned TT3 syntax is supported as well as most of that of
HTML::Template::Expr.  The following is a list of some of the ways
that the configuration and syntax of CET are different from that of
TT2.  Note: items that are planned to work in TT3 are marked with
(TT3).

=over 4

=item

Numerical hash keys work

    [% a = {1 => 2} %]

=item

Quoted hash key interpolation is fine

    [% a = {"$foo" => 1} %]

=item

Multiple ranges in same constructor

    [% a = [1..10, 21..30] %]

=item

Constructor types can call virtual methods. (TT3)

    [% a = [1..10].reverse %]

    [% "$foo".length %]

    [% 123.length %]   # = 3

    [% 123.4.length %]  # = 5

    [% -123.4.length %] # = -5 ("." binds more tightly than "-")

    [% (a ~ b).length %]

    [% "hi".repeat(3) %] # = hihihi

    [% {a => b}.size %] # = 1

=item

The "${" and "}" variable interpolators can contain expressions,
not just variables.

    [% [0..10].${ 1 + 2 } %] # = 4

    [% {ab => 'AB'}.${ 'a' ~ 'b' } %] # = AB

    [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
      # = RedBlueRedBlue

=item

You can use regular expression quoting.

    [% "foo".match( /(F\w+)/i ).0 %] # = foo

=item

Tags can be nested.

    [% f = "[% (1 + 2) %]" %][% f|eval %] # = 3

=item

Arrays can be accessed with non-integer numbers.

    [% [0..10].${ 2.3 } %] # = 3

=item

Reserved names are less reserved. (TT3)

    [% GET GET %] # gets the variable named "GET"

    [% GET $GET %] # gets the variable who's name is stored in "GET"

=item

Filters and SCALAR_OPS are interchangeable. (TT3)

    [% a | length %]

    [% b . lower %]

=item

Pipe "|" can be used anywhere dot "." can be and means to call
the virtual method. (TT3)

    [% a = {size => "foo"} %][% a.size %] # = foo

    [% a = {size => "foo"} %][% a|size %] # = 1 (size of hash)

=item

Pipe "|" and "." can be mixed. (TT3)

    [% "aa" | repeat(2) . length %] # = 4

=item

Added V2PIPE configuration item

Restores the behavior of the pipe operator to be
compatible with TT2.

With V2PIPE = 1

    [% PROCESS a | repeat(2) %] # = value of block or file a repeated twice

With V2PIPE = 0 (default)

    [% PROCESS a | repeat(2) %] # = process block or file named a ~ a

=item

Added V2EQUALS configuration item

Allows for turning off TT2 "==" behavior.  Defaults to 1
in TT syntaxes and to 0 in HT syntaxes.

    [% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
    [% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]

Prints

    0
    1

=item

Added Virtual Object Namespaces. (TT3)

The Text, List, and Hash types give direct access
to virtual methods.

    [% a = "foobar" %][% Text.length(a) %] # = 6

    [% a = [1 .. 10] %][% List.size(a) %] # = 10

    [% a = {a=>"A", b=>"B"} ; Hash.size(a) %] = 2

    [% foo = {a => 1, b => 2}
       | Hash.keys
       | List.join(", ") %] # = a, b

=item

Added "fmt" scalar, list, and hash virtual methods.

    [% list.fmt("%s", ", ") %]

    [% hash.fmt("%s => %s", "\n") %]

=item

Added missing HTML::Template::Expr vmethods

The following vmethods were added - they correspond to the
perl functions of the same name.

    abs
    atan2
    cos
    exp
    hex
    lc
    log
    oct
    sin
    sprintf
    sqrt
    srand
    uc

=item

Allow all Scalar vmethods to behave as top level functions.

    [% sprintf("%d %d", 7, 8) %] # = "7 8"

The following are equivalent in CET:

    [% "abc".length %]
    [% length("abc") %]

This feature may be disabling by setting the
VMETHOD_FUNCTIONS configuration item to 0.

This is similar to how HTML::Template::Expr operates, but
now you can use this functionality in TT templates as well.

=item

Whitespace is less meaningful. (TT3)

    [% 2-1 %] # = 1 (fails in TT2)

=item

Added pow operator.

    [% 2 ** 3 %] [% 2 pow 3 %] # = 8 8

=item

Added string comparison operators (gt ge lt le cmp)

    [% IF "a" lt "b" %]a is less[% END %]

=item

Added numeric comparison operator (<=>)

This can be used to make up for the fact that TT2 made == the
same as eq (which will hopefully change - use eq when you mean eq).

    [% IF ! (a <=> b) %]a == b[% END %]

    [% IF (a <=> b) %]a != b[% END %]

=item

Added self modifiers (+=, -=, *=, /=, %=, **=, ~=). (TT3)

    [% a = 2;  a *= 3  ; a %] # = 6
    [% a = 2; (a *= 3) ; a %] # = 66

=item

Added pre and post increment and decrement (++ --). (TT3)

    [% ++a ; ++a %] # = 12
    [% a-- ; a-- %] # = 0-1

=item

Added qw// contructor. (TT3)

    [% a = qw(a b c); a.1 %] # = b

    [% qw/a b c/.2 %] # = c

=item

Added regex contructor. (TT3)

    [% "FOO".match(/(foo)/i).0 %] # = FOO

    [% a = /(foo)/i; "FOO".match(a).0 %] # = FOO

=item

Allow for scientific notation. (TT3)

    [% a = 1.2e-20 %]

    [% 123.fmt('%.3e') %] # = 1.230e+02

=item

Allow for hexidecimal input. (TT3)

    [% a = 0xff0000 %][% a %] # = 16711680

    [% a = 0xff2 / 0xd; a.fmt('%x') %] # = 13a

=item

FOREACH variables can be nested.

    [% FOREACH f.b = [1..10] ; f.b ; END %]

Note that nested variables are subject to scoping issues.
f.b will not be reset to its value before the FOREACH.

=item

Post operative directives can be nested. (TT3)

Andy Wardley calls this side-by-side effect notation.

    [% one IF two IF three %]

    same as

    [% IF three %][% IF two %][% one %][% END %][% END %]


    [% a = [[1..3], [5..7]] %][% i FOREACH i = j FOREACH j = a %] # = 123567

=item

Semi-colons on directives in the same tag are optional. (TT3)

    [% SET a = 1
       GET a
     %]

    [% FOREACH i = [1 .. 10]
         i
       END %]

Note: a semi-colon is still required in front of any block directive
that can be used as a post-operative directive.

    [% 1 IF 0
       2 %]   # prints 2

    [% 1; IF 0
       2
       END %] # prints 1

Note2: This behavior can be disabled by setting the SEMICOLONS
configuration item to a true value.  If SEMICOLONS is true, then
a SEMICOLON must be set after any directive that isn't followed
by a post-operative directive.

=item

CATCH blocks can be empty.

TT2 requires them to contain something.

=item

Added a DUMP directive.

Used for Data::Dumpering the passed variable or expression.

   [% DUMP a.a %]

=item

Added CONFIG directive.

   [% CONFIG
        ANYCASE   => 1
        PRE_CHOMP => '-'
   %]

=item

Configuration options can use lowercase names instead
of the all uppercase names that TT2 uses.

    my $t = CGI::Ex::Template->new({
        anycase     => 1,
        interpolate => 1,
    });

=item

Added LOOP directive (works the same as LOOP in HTML::Template.

   [%- var = [{key => 'a'}, {key => 'b'}] %]
   [%- LOOP var %]
     ([% key %])
   [%- END %]

   Prints

     (a)
     (b)

=item

CET can parse HTML::Template and HTML::Template::Expr documents
as well as TT2 and TT3 documents.

=item

Added SYNTAX configuration.  The SYNTAX configuration can be
used to change what template syntax will be used for parsing
included templates or eval'ed strings.

   [% CONFIG SYNTAX => 'hte' %]
   [% var = '<TMPL_VAR EXPR="sprintf('%s', 'hello world')">' %]
   [% var | eval %]

=item

CET does not generate Perl code.

It generates an "opcode" tree.  The opcode tree is an arrayref
of scalars and array refs nested as deeply as possible.  This "simple"
structure could be shared TT implementations in other languages
via JSON or YAML.

=item

CET uses storable for its compiled templates.

If EVAL_PERL is off, CET will not eval_string on ANY piece of information.

=item

There is eval_filter and MACRO recursion protection

You can control the nested nature of eval_filter and MACRO
recursion using the MAX_EVAL_RECURSE and MAX_MACRO_RECURSE
configuration items.

=item

There is no context.

CET provides a context object that mimics the Template::Context
interface for use by some TT filters, eval perl blocks, views,
and plugins.

=item

There is no stash.

Well there is but it isn't an object.

CET only supports the variables passed in VARIABLES, PRE_DEFINE, and
those passed to the process method.  CET provides a stash object that
mimics the Template::Stash interface for use by some TT filters, eval
perl blocks, and plugins.

=item

There is no provider.

CET uses the load_parsed_tree method to get and cache templates.

=item

There is no parser/grammar.

CET has its own built-in recursive regex based parser and grammar system.

CET can actually be substituted in place of the native Template::Parser and
Template::Grammar in TT by using the Template::Parser::CET module.  This
module uses the output of parse_tree to generate a TT style compiled perl
document.

=item

The DEBUG directive is more limited.

It only understands DEBUG_DIRS (8) and DEBUG_UNDEF (2).

=item

CET has better line information

When debug dirs is on, directives on different lines separated
by colons show the line they are on rather than a general line range.

Parse errors actually know what line and character they occured at.

=back

=head1 HOW IS CGI::Ex::Template DIFFERENT from HTML::Template

CET can use the same base template syntax and configuration items as HTE
and HT.  The internals of CET were written to support TT3, but were
general enough to be extended to support HTML::Template as well.  The result
is HTML::Template::Expr compatible syntax, with CET speed and a wide range
of additional features.

The TMPL_VAR, TMPL_IF, TMPL_ELSE, TMPL_UNLESS, TMPL_LOOP, and TMPL_INCLUDE
all work identically to HTML::Template.

=over 4

=item

Added support for other TT3 directives and for TT style "dot notation."

    <TMPL_SET a = "bar">
    <TMPL_SET b = [1 .. 25]>
    <TMPL_SET foo = PROCESS 'filename.tt'>

    <TMPL_GET foo>  # similar to <TMPL_VAR NAME="foo">
    <TMPL_GET b.3>
    <TMPL_GET my.nested.chained.variable.1>
    <TMPL_GET my_var | html>

    <TMPL_USE foo = DBI(db => ...)>
    <TMPL_CALL foo.connect>

Any of the TT directives can be used in HTML::Template documents.

For many die-hard HTML::Template fans, it is probably quite scary to
be providing all of the TT functionality.  All of the extended
TT functionality can be disabled by setting the NO_TT configuration
item.  The NO_TT configuration is automatically set if the SYNTAX is
set to "ht" and the output method is called.

=item

There is an ELSIF!!!

    <TMPL_IF foo>
      FOO
    <TMPL_ELSIF bar>
      BAR
    <TMPL_ELSE>
      Done then
    </TMPL_IF>

=item

Added CHOMP capabilities (PRE_CHOMP and POST_CHOMP)

    Foo
    <~TMPL_VAR EXPR="1+2"~>
    Bar

    Prints Foo3Bar

=item

Added INTERPOLATE capability

    <TMPL_SET foo = 'FOO'>
    <TMPL_CONFIG INTERPOLATE => 1>
    $foo <TMPL_GET foo> ${ 1 + 2 }

    Prints

    FOO FOO 3

=item

Allow for HTML::Template templates to include TT style templates.

    <TMPL_CONFIG SYNTAX => 'tt3'>
    <TMPL_INCLUDE "filename.tt">

=item

Allow for Expr parsing to follow proper precedence rules.

   <TMPL_VAR EXPR="1 + 2 * 3">

   Properly prints 7.

=item

Uses all of the caching and opcode tree optimations provided by
CGI::Ex::Template and CGI::Ex::Template::XS.

=item

CET does not provide the query method from HTML::Template.  This
is because parsing of the document is delayed until the output
method is called, and because CET supports TT style chained
variables which often are not resolvable until run time.

=back

=head1 VARIABLES

This section discusses how to use variables and expressions in the TT
mini-language.

A variable is the most simple construct to insert into the TT mini
language.  A variable name will look for the matching value inside
CGI::Ex::Templates internal stash of variables which is essentially a
hash reference.  This stash is initially populated by either passing a
hashref as the second argument to the process method, or by setting
the "VARIABLES" or "PRE_DEFINE" configuration variables.

If you are using the HT and HTE syntaxes, the VAR, IF, UNLESS,
LOOP, and INCLUDE directives will accept a NAME attribute which may
only be a single level (non-chained) HTML::Template variable name, or
they may accept an EXPR attribute which may be any valid TT3 variable or expression.

The following are some sample ways to access variables.

    ### some sample variables
    my %vars = (
        one       => '1.0',
        foo       => 'bar',
        vname     => 'one',
        some_code => sub { "You passed me (".join(', ', @_).")" },
        some_data => {
            a     => 'A',
            bar   => 3234,
            c     => [3, 1, 4, 1, 5, 9],
            vname => 'one',
        },
        my_list   => [20 .. 50],
        cet       => CGI::Ex::Template->new,
    );

    ### pass the variables into the CET process
    $cet->process($template_name, \%vars)
         || die $cet->error;

    ### pass the variables during object creation (will be available to every process call)
    my $cet = CGI::Ex::Template->new(VARIABLES => \%vars);

=head2 GETTING VARIABLES

Once you have variables defined, they can be used directly in the
template by using their name in the stash.  Or by using the GET
directive.

    [% foo %]
    [% one %]
    [% GET foo %]

Would print when processed:

    bar
    1.0
    bar

To access members of a hashref or an arrayref, you can chain together
the names using a ".".

    [% some_data.a %]
    [% my_list.0] [% my_list.1 %] [% my_list.-1 %]
    [% some_data.c.2 %]

Would print:

    A
    20 21 50
    4

If the value of a variable is a code reference, it will be called.
You can add a set of parenthesis and arguments to pass arguments.
Arguments are variables and can be as complex as necessary.

    [% some_code %]
    [% some_code() %]
    [% some_code(foo) %]
    [% some_code(one, 2, 3) %]

Would print:

    You passed me ().
    You passed me ().
    You passed me (bar).
    You passed me (1.0, 2, 3).

If the value of a variable is an object, methods can be called using
the "." operator.

    [% cet %]

    [% cet.dump_parse_expr('1 + 2').replace('\s+', ' ') %]

Would print something like:

    CGI::Ex::Template=HASH(0x814dc28)

    $VAR1 = [ [ undef, '+', '1', '2' ], 0 ];

Each type of data (string, array and hash) have virtual methods
associated with them.  Virtual methods allow for access to functions
that are commonly used on those types of data.  For the full list of
built in virtual methods, please see the section titled VIRTUAL
METHODS

    [% foo.length %]
    [% my_list.size %]
    [% some_data.c.join(" | ") %]

Would print:

    3
    31
    3 | 1 | 4 | 5 | 9

It is also possible to "interpolate" variable names using a "$".  This
allows for storing the name of a variable inside another variable.  If
a variable name is a little more complex it can be embedded inside of
"${" and "}".

    [% $vname %]
    [% ${vname} %]
    [% ${some_data.vname} %]
    [% some_data.$foo %]
    [% some_data.${foo} %]

Would print:

    1.0
    1.0
    1.0
    3234
    3234

In CET it is also possible to embed any expression (non-directive) in
"${" and "}" and it is possible to use non-integers for array access.
(This is not available in TT2)

    [% ['a'..'z'].${ 2.3 } %]
    [% {ab => 'AB'}.${ 'a' ~ 'b' } %]
    [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]

Would print:

    c
    AB
    RedBlueRedBlue

=head2 SETTING VARIABLES.

To define variables during processing, you can use the = operator.  In
most cases this is the same as using the SET directive.

    [% a = 234 %][% a %]
    [% SET b = "Hello" %][% b %]

Would print:

    234
    Hello

It is also possible to create arrayrefs and hashrefs.

    [% a = [1, 2, 3] %]
    [% b = {key1 => 'val1', 'key2' => 'val2'} %]

    [% a.1 %]
    [% b.key1 %] [% b.key2 %]

Would print:

    2
    val1 val2

It is possible to set multiple values in the same SET directive.

    [% SET a = 'A'
           b = 'B'
           c = 'C' %]
    [% a %]    [% b %]    [% c %]

Would print:

    A    B    C

It is also possible to unset variables, or to set members of
nested data structures.

    [% a = 1 %]
    [% SET a %]

    [% b.0.c = 37 %]

    ([% a %])
    [% b.0.c %]

Would print

    ()
    37

=head1 LITERALS AND CONSTRUCTORS

The following are the types of literals (numbers and strings) and
constructors (hash and array constructs) allowed in CET.  They can be
used as arguments to functions, in place of variables in directives,
and in place of variables in expressions.  In CET it is also possible
to call virtual methods on literal values.

=over 4

=item Integers and Numbers.

    [% 23423   %]        Prints an integer.
    [% 3.14159 %]        Prints a number.
    [% pi = 3.14159 %]   Sets the value of the variable.
    [% 3.13159.length %] Prints 7 (the string length of the number)

Scientific notation is supported.

    [% 314159e-5 + 0 %]      Prints 3.14159.

    [% .0000001.fmt('%.1e') %]  Prints 1.0e-07

Hexidecimal input is also supported.

    [% 0xff + 0 %]    Prints 255

    [% 48875.fmt('%x') %]  Prints beeb

=item Single quoted strings.

Returns the string.  No variable interpolation happens.

    [% 'foobar' %]          Prints "foobar".
    [% '$foo\n' %]          Prints "$foo\\n".  # the \\n is a literal "\" and an "n"
    [% 'That\'s nice' %]    Prints "That's nice".
    [% str = 'A string' %]  Sets the value of str.
    [% 'A string'.split %]  Splits the string on ' ' and returns the list.

Note: virtual methods can only be used on literal strings in CET, not in TT.

You may also embed the current tags in strings (CET only).

    [% '[% 1 + 2 %]' | eval %]  Prints "3"

=item Double quoted strings.

Returns the string.  Variable interpolation happens.

    [% "foobar" %]                   Prints "foobar".
    [% "$foo"   %]                   Prints "bar" (assuming the value of foo is bar).
    [% "${foo}" %]                   Prints "bar" (assuming the value of foo is bar).
    [% "foobar\n" %]                 Prints "foobar\n".  # the \n is a newline.
    [% str = "Hello" %]              Sets the value of str.
    [% "foo".replace('foo','bar') %] Prints "bar".

Note: virtual methods can only be used on literal strings in CET, not in TT.

You may also embed the current tags in strings (CET only).

    [% "[% 1 + 2 %]" | eval %]  Prints "3"

=item Array Constructs.

    [% [1, 2, 3] %]               Prints something like ARRAY(0x8309e90).
    [% array1 = [1 .. 3] %]       Sets the value of array1.
    [% array2 = [foo, 'a', []] %] Sets the value of array2.
    [% [4, 5, 6].size %]          Prints 3.
    [% [7, 8, 9].reverse.0 %]     Prints 9.

Note: virtual methods can only be used on array contructs in CET, not in TT.

=item Quoted Array Constructs.

    [% qw/1 2 3/ %]                Prints something like ARRAY(0x8309e90).
    [% array1 = qw{Foo Bar Baz} %] Sets the value of array1.
    [% qw[4 5 6].size %]           Prints 3.
    [% qw(Red Blue).reverse.0 %]   Prints Blue.

Note: this works in CET and is planned for TT3.

=item Hash Constructs.

    [% {foo => 'bar'} %]                 Prints something like HASH(0x8305880)
    [% hash = {foo => 'bar', c => {}} %] Sets the value of hash.
    [% {a => 'A', b => 'B'}.size %]      Prints 2.
    [% {'a' => 'A', 'b' => 'B'}.size %]  Prints 2.
    [% name = "Tom" %]
    [% {Tom => 'You are Tom',
        Kay => 'You are Kay'}.$name %]   Prints You are Tom

Note: virtual methods can only be used on hash contructs in CET, not in TT.

=item Regex Constructs.

    [% /foo/ %]                              Prints (?-xism:foo)
    [% a = /(foo)/i %][% "FOO".match(a).0 %] Prints FOO

Note: this works in CET and is planned for TT3.

=head1 EXPRESSIONS

Expressions are one or more variables or literals joined together with
operators.  An expression can be used anywhere a variable can be used
with the exception of the variable name in the SET directive, and the
filename of PROCESS, INCLUDE, WRAPPER, and INSERT.

The following section shows some samples of expressions.  For a full
list of available operators, please see the section titled OPERATORS.

    [% 1 + 2 %]           Prints 3
    [% 1 + 2 * 3 %]       Prints 7
    [% (1 + 2) * 3 %]     Prints 9

    [% x = 2 %]                      # assignments don't return anything
    [% (x = 2) %]         Prints 2   # unless they are in parens
    [% y = 3 %]
    [% x * (y - 1) %]     Prints 4

=head1 VIRTUAL METHODS

The following is the list of builtin virtual methods and filters that
can be called on each type of data.

In CGI::Ex::Template, the "|" operator can be used to call virtual
methods just the same way that the "." operator can.  The main
difference between the two is that on access to hashrefs or objects,
the "|" means to always call the virtual method or filter rather than
looking in the hashref for a key by that name, or trying to call that
method on the object.  This is similar to how TT3 will function.

Virtual methods are also made available via Virtual Objects which
are discussed in a later section.

=head2 SCALAR VIRTUAL METHODS AND FILTERS

The following is the list of builtin virtual methods and filters that
can be called on scalar data types.  In CET and TT3, filters and
virtual methods are more closely related than in TT2.  In general
anywhere a virtual method can be used a filter can be used also - and
likewise all scalar virtual methods can be used as filters.

In addition to the filters listed below, CET will automatically load
Template::Filters and use them if Template::Toolkit is installed.

In addition to the scalar virtual methods, any scalar will be
automatically converted to a single item list if a list virtual method
is called on it.

Scalar virtual methods are also available through the "Text" virtual
object (except for true filters such as eval and redirect).

All scalar virtual methods are available as top level functions as well.
This is not true of TT2.  In CGI::Ex::Template the following are equivalent:

    [% "abc".length %]
    [% length("abc") %]

You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.

=over 4

=item '0'

    [% item = 'foo' %][% item.0 %] Returns foo.

Allows for scalars to mask as arrays (scalars already will, but this
allows for more direct access).

=item abs

    [% -1.abs %] Returns the absolute value

=item atan2

    [% pi = 4 * 1.atan2(1) %]

Returns the arctangent.  The item itself represents Y, the passed argument represents X.

=item chunk

    [% item.chunk(60).join("\n") %] Split string up into a list of chunks of text 60 chars wide.

=item collapse

    [% item.collapse %] Strip leading and trailing whitespace and collapse all other space to one space.

=item cos

    [% item.cos %] Returns the cosine of the item.

=item defined

    [% item.defined %] Always true - because the undef sub translates all undefs to ''.

=item eval

    [% item.eval %]

Process the string as though it was a template.  This will start the parsing
engine and will use the same configuration as the current process.  CET is several times
faster at doing this than TT is and is considered acceptable.

This is a filter and is not available via the Text virtual object.

=item evaltt

    Same as the eval filter.

=item exp

    [% 1.exp %] Something like 2.71828182845905

Returns "e" to the power of the item.

=item file

    Same as the redirect filter.

=item fmt

    [% item.fmt('%d') %]
    [% item.fmt('%6s') %]
    [% item.fmt('%*s', 6) %]

Similar to format.  Returns a string formatted with the passed pattern.  Default pattern is %s.
Opposite from of the sprintf vmethod.

=item format

    [% item.format('%d') %]
    [% item.format('%6s') %]
    [% item.format('%*s', 6) %]

Print the string out in the specified format.  It is similar to
the "fmt" virtual method, except that the item is split on newline and each line is
processed separately.

=item hash

    [% item.hash %] Returns a one item hash with a key of "value" and a value of the item.


=item hex

    [% "FF".hex %]

Returns the decimal value of the passed hex numbers.  Note that you
may also just use [% 0xFF %].

=item html

    [% item.html %] Performs a very basic html encoding (swaps out &, <, > and " for the html entities)

=item indent

    [% item.indent(3) %] Indent that number of spaces.

    [% item.indent("Foo: ") %] Add the string "Foo: " to the beginning of every line.

=item int

    [% item.int %] Return the integer portion of the value (0 if none).

=item lc

Same as the lower vmethod.  Returns the lower cased version of the item.

=item lcfirst

    [% item.lcfirst %] Capitalize the leading letter.

=item length

    [% item.length %] Return the length of the string.

=item list

    [% item.list %] Returns a list with a single value of the item.

=item log

    [% 8.exp.log %] Equal to 8.

Returns the natural log base "e" of the item.

=item lower

    [% item.lower %] Return a lower-casified string.

=item match

    [% item.match("(\w+) (\w+)") %] Return a list of items matching the pattern.

    [% item.match("(\w+) (\w+)", 1) %] Same as before - but match globally.

In CGI::Ex::Template and TT3 you can use regular expressions notation as well.

    [% item.match( /(\w+) (\w+)/ ) %] Same as before.

    [% item.match( m{(\w+) (\w+)} ) %] Same as before.

=item null

    [% item.null %] Do nothing.

=item oct

    [% "377".oct %]

Returns the decimal value of the octal string.  On recent versions of perl you
may also pass numbers starting with 0x which will be interpreted as hexidecimal,
and starting with 0b which will be interpreted as binary.

=item rand

    [% item = 10; item.rand %] Returns a number greater or equal to 0 but less than 10.
    [% 1.rand %]

Note: This filter is not available as of TT2.15.

=item remove

    [% item.remove("\s+") %] Same as replace - but is global and replaces with nothing.

=item redirect

    [% item.redirect("output_file.html") %]

Writes the contents out to the specified file.  The filename
must be relative to the OUTPUT_PATH configuration variable and the OUTPUT_PATH variable must be set.

This is a filter and is not available via the Text virtual object.

=item repeat

    [% item.repeat(3) %] Repeat the item 3 times

    [% item.repeat(3, ' | ') %] Repeat the item 3 times separated with ' | '

=item replace

    [% item.replace("\s+", "&nbsp;") %] Globally replace all space with &nbsp;

    [% item.replace("foo", "bar", 0) %] Replace only the first instance of foo with bar.

    [% item.replace("(\w+)", "($1)") %] Surround all words with parenthesis.

In CGI::Ex::Template and TT3 you may also use normal regular expression notation.

    [% item.replace(/(\w+)/, "($1)") %] Same as before.

=item search

    [% item.search("(\w+)") %] Tests if the given pattern is in the string.

In CGI::Ex::Template and TT3 you may also use normal regular expression notation.

    [% item.search(/(\w+)/, "($1)") %] Same as before.

=item sin

    [% item.sin %] Returns the sine of the item.

=item size

    [% item.size %] Always returns 1.

=item split

    [% item.split %] Returns an arrayref from the item split on " "

    [% item.split("\s+") %] Returns an arrayref from the item split on /\s+/

    [% item.split("\s+", 3) %] Returns an arrayref from the item split on /\s+/ splitting until 3 elements are found.

In CGI::Ex::Template and TT3 you may also use normal regular expression notation.

    [% item.split( /\s+/, 3 ) %] Same as before.

=item sprintf

    [% item = "%d %d" %]
    [% item.sprintf(7, 8) %]

Uses the pattern stored in self, and passes it to sprintf with the passed arguments.
Opposite from the fmt vmethod.

=item sqrt

    [% item.sqrt %]

Returns the square root of the number.

=item srand

Calls the perl srand function to set the interal random seed.  This
will affect future calls to the rand vmethod.

=item stderr

    [% item.stderr %] Print the item to the current STDERR handle.

=item substr

    [% item.substr(i) %] Returns a substring of item starting at i and going to the end of the string.

    [% item.substr(i, n) %] Returns a substring of item starting at i and going n characters.

=item trim

    [% item.trim %] Strips leading and trailing whitespace.

=item uc

Same as the upper command.  Returns upper cased string.

=item ucfirst

    [% item.ucfirst %] Lower-case the leading letter.

=item upper

    [% item.upper %] Return a upper cased string.

=item uri

    [% item.uri %] Perform a very basic URI encoding.

=item url

    [% item.url %] Perform a URI encoding - but some characters such
                   as : and / are left intact.

=back

=head2 LIST VIRTUAL METHODS

The following methods can be called on an arrayref type data structures (scalar
types will automatically promote to a single element list and call these methods
if needed):

Additionally, list virtual methods can be accessed via the List
Virtual Object.

=over 4

=item fmt

    [% mylist.fmt('%s', ', ') %]
    [% mylist.fmt('%6s', ', ') %]
    [% mylist.fmt('%*s', ', ', 6) %]

Passed a pattern and an string to join on.  Returns a string of the values of the list
formatted with the passed pattern and joined with the passed string.
Default pattern is %s and the default join string is a space.

=item first

    [% mylist.first(3) %]  Returns a list of the first 3 items in the list.

=item grep

    [% mylist.grep("^\w+\.\w+$") %] Returns a list of all items matching the pattern.

=item hash

    [% mylist.hash %] Returns a hashref with the array indexes as keys and the values as values.

=item join

    [% mylist.join %] Joins on space.
    [% mylist.join(", ") Joins on the passed argument.

=item last

    [% mylist.last(3) %]  Returns a list of the last 3 items in the list.

=item list

    [% mylist.list %] Returns a reference to the list.

=item max

    [% mylist.max %] Returns the last item in the array.

=item merge

    [% mylist.merge(list2) %] Returns a new list with all defined items from list2 added.

=item nsort

    [% mylist.nsort %] Returns the numerically sorted items of the list.  If the items are
    hashrefs, a key containing the field to sort on can be passed.

=item pop

    [% mylist.pop %] Removes and returns the last element from the arrayref (the stash is modified).

=item push

    [% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).

=item pick

    [% mylist.pick %] Returns a random item from the list.
    [% ['a' .. 'z'].pick %]

An additional numeric argument is how many items to return.

    [% ['a' .. 'z'].pick(8).join('') %]

Note: This filter is not available as of TT2.15.

=item reverse

    [% mylist.reverse %] Returns the list in reverse order.

=item shift

    [% mylist.shift %] Removes and returns the first element of the arrayref (the stash is modified).

=item size

    [% mylist.size %] Returns the number of elements in the array.

=item slice

    [% mylist.slice(i, n) %] Returns a list from the arrayref beginning at index i and continuing for n items.

=item sort

    [% mylist.sort %] Returns the alphabetically sorted items of the list.  If the items are
    hashrefs, a key containing the field to sort on can be passed.

=item splice

    [% mylist.splice(i, n) %] Removes items from array beginning at i and continuing for n items.

    [% mylist.splice(i, n, list2) %] Same as before, but replaces removed items with the items
    from list2.

=item unique

    [% mylist.unique %] Return a list of the unique items in the array.

=item unshift

    [% mylist.unshift(23) %] Adds an item to the beginning of the arrayref.

=back 4

=head2 HASH VIRTUAL METHODS

The following methods can be called on hash type data structures:

Additionally, list virtual methods can be accessed via the Hash
Virtual Object.

=over 4

=item fmt

    [% myhash.fmt('%s => %s', "\n") %]
    [% myhash.fmt('%4s => %5s', "\n") %]
    [% myhash.fmt('%*s => %*s', "\n", 4, 5) %]

Passed a pattern and an string to join on.  Returns a string of the key/value pairs
of the hash formatted with the passed pattern and joined with the passed string.
Default pattern is "%s\t%s" and the default join string is a newline.

=item defined

    [% myhash.defined('a') %]  Checks if a is defined in the hash.

=item delete

    [% myhash.delete('a') %]  Deletes the item from the hash.

Unlink Perl the value is not returned.  Multiple values may be passed
and represent the keys to be deleted.

=item each

    [% myhash.each.join(", ") %]  Turns the contents of the hash into a list - subject
    to change as TT is changing the operations of each and list.

=item exists

    [% myhash.exists('a') %]  Checks if a is in the hash.

=item hash

    [% myhash.hash %]  Returns a reference to the hash.

=item import

    [% myhash.import(hash2) %]  Overlays the keys of hash2 over the keys of myhash.

=item item

    [% myhash.item(key) %] Returns the hashes value for that key.

=item items

    [% myhash.items %] Returns a list of the key and values (flattened hash)

=item keys

    [% myhash.keys.join(', ') %] Returns an arrayref of the keys of the hash.

=item list

    [% myhash.list %] Returns an arrayref with the hash as a single value (subject to change).

=item pairs

    [% myhash.pairs %] Returns an arrayref of hashrefs where each hash contains {key => $key, value => $value}
    for each value of the hash.

=item nsort

    [% myhash.nsort.join(", ") %] Returns a numerically sorted list of the keys.

=item size

    [% myhash.size %] Returns the number of key/value pairs in the hash.

=item sort

    [% myhash.sort.join(", ") Returns an alphabetically sorted list.

=item values

    [% myhash.values.join(', ') %] Returns an arrayref of the values of the hash.

=back

=head1 VIRTUAL OBJECTS

TT3 has a concept of Text, List, and Hash virtual objects which provide
direct access to the scalar, list, and hash virtual methods.  In the TT3
engine this will allow for more concise generated code.  Because CET does
not generated perl code to be executed later, CET provides for these virtual
objects but does so as more of a namespace (using the methods does not
provide a speed optimization in your template - just may help clarify things).

    [% a = "foo"; a.length %] => 3

    [% a = "foo"; Text.length(a) %] => 3

    [% a = Text.new("foo"); a.length %] => 3


    [% a = [1 .. 30]; a.size %] => 30

    [% a = [1 .. 30]; List.size(a) %] => 30

    [% a = List.new(1 .. 30); a.size %] => 30


    [% a = {a => 1, b => 2}; a.size %] => 2

    [% a = {a => 1, b => 2}; Hash.size(a) %] => 2

    [% a = Hash.new({a => 1, b => 2}); a.size %] => 2

    [% a = Hash.new(a => 1, b => 2); a.size %] => 2

    [% a = Hash.new(a = 1, b = 2); a.size %] => 2

    [% a = Hash.new('a', 1, 'b', 2); a.size %] => 2

One limitation is that if you pass a key named "Text",
"List", or "Hash" in your variable stash - the corresponding
virtual object will be hidden.

Additionally, you can use all of the Virtual object methods with
the pipe operator.

    [% {a => 1, b => 2}
       | Hash.keys
       | List.join(", ") %] => a, b

Again, there aren't any speed optimizations to using the virtual
objects in CET, but it can help clarify the intent in some cases.

Note: these aren't really objects.  All of the "virtual objects" are
references to the $SCALAR_OPS, $LIST_OPS, and $HASH_OPS hashes
found in the $VOBJS hash of CGI::Ex::Template.

=head1 DIRECTIVES (TT Style)

This section contains the alphabetical list of DIRECTIVES available in
the TT language.  DIRECTIVES are the "functions" and control
structures of the Template Toolkit mini-language.  For further
discussion and examples beyond what is listed below, please refer to
the TT directives documentation.

    [% IF 1 %]One[% END %]
    [% FOREACH a = [1 .. 3] %]
        a = [% a %]
    [% END %]

    [% SET a = 1 %][% SET a = 2 %][% GET a %]

Multiple directives can be inside the same set of '[%' and '%]' tags
as long as they are separated by space or semi-colons (;).  Any block
directive that can also be used as a post-operative directive (such as
IF, WHILE, FOREACH, UNLESS, FILTER, and WRAPPER) must be separated
from preceding directives with a semi-colon if it is being used as a
block directive.  It is more safe to always use a semi-colon.  Note:
separating by space is only available in CET but is a planned TT3
feature.

    [% SET a = 1 ; SET a = 2 ; GET a %]
    [% SET a = 1
       SET a = 2
       GET a
     %]

    [% GET 1
         IF 0   # is a post-operative
       GET 2 %] # prints 2

    [% GET 1;
       IF 0     # it is block based
         GET 2
       END
     %]         # prints 1

The following is the list of directives.

=over 4

=item C<BLOCK>

Saves a block of text under a name for later use in PROCESS, INCLUDE,
and WRAPPER directives.  Blocks may be placed anywhere within the
template being processed including after where they are used.

    [% BLOCK foo %]Some text[% END %]
    [% PROCESS foo %]

    Would print

    Some text

    [% INCLUDE foo %]
    [% BLOCK foo %]Some text[% END %]

    Would print

    Some text

Anonymous BLOCKS can be used for capturing.

    [% a = BLOCK %]Some text[% END %][% a %]

    Would print

    Some text

Anonymous BLOCKS can be used with macros.


=item C<BREAK>

Alias for LAST.  Used for exiting FOREACH and WHILE loops.

=item C<CALL>

Calls the variable (and any underlying coderefs) as in the GET method, but
always returns an empty string.

=item C<CASE>

Used with the SWITCH directive.  See the L</"SWITCH"> directive.

=item C<CATCH>

Used with the TRY directive.  See the L</"TRY"> directive.

=item C<CLEAR>

Clears any of the content currently generated in the innermost block
or template.  This can be useful when used in conjunction with the TRY
statement to clear generated content if an error occurs later.

=item C<CONFIG>

Allow for changing the value of some compile time and runtime configuration
options.

    [% CONFIG
        ANYCASE   => 1
        PRE_CHOMP => '-'
    %]

The following compile time configuration options may be set:

    ANYCASE
    INTERPOLATE
    PRE_CHOMP
    POST_CHOMP
    V1DOLLAR
    V2PIPE
    V2EQUALS

The following runtime configuration options may be set:

    DUMP
    VMETHOD_FUNCTIONS

If non-named parameters as passed, they will show the current configuration:

   [% CONFIG ANYCASE, PRE_CHOMP %]

   CONFIG ANYCASE = undef
   CONFIG PRE_CHOMP = undef

=item C<DEBUG>

Used to reset the DEBUG_FORMAT configuration variable, or to turn
DEBUG statements on or off.  This only has effect if the DEBUG_DIRS or
DEBUG_ALL flags were passed to the DEBUG configuration variable.

    [% DEBUG format '($file) (line $line) ($text)' %]
    [% DEBUG on %]
    [% DEBUG off %]

=item C<DEFAULT>

Similar to SET, but only sets the value if a previous value was not
defined or was zero length.

    [% DEFAULT foo = 'bar' %][% foo %] => 'bar'

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

=item C<DUMP>

DUMP inserts a Data::Dumper printout of the variable or expression.
If no argument is passed it will dump the entire contents of the
current variable stash (with private keys removed).

The output also includes the current file and line number that the
DUMP directive was called from.

See the DUMP configuration item for ways to customize and control
the output available to the DUMP directive.

    [% DUMP %] # dumps everything

    [% DUMP 1 + 2 %]

=item C<ELSE>

Used with the IF directive.  See the L</"IF"> directive.

=item C<ELSIF>

Used with the IF directive.  See the L</"IF"> directive.

=item C<END>

Used to end a block directive.

=item C<FILTER>

Used to apply different treatments to blocks of text.  It may operate as a BLOCK
directive or as a post operative directive.  CET supports all of the filters in
Template::Filters.  The lines between scalar virtual methods and filters is blurred (or
non-existent) in CET.  Anything that is a scalar virtual method may be used as a FILTER.

TODO - enumerate the at least 7 ways to pass and use filters.

=item C<'|'>

Alias for the FILTER directive.  Note that | is similar to the
'.' in CGI::Ex::Template.  Therefore a pipe cannot be used directly after a
variable name in some situations (the pipe will act only on that variable).
This is the behavior employed by TT3.  To get the TT2 behavior for a PIPE, use
the V2PIPE configuration item.

=item C<FINAL>

Used with the TRY directive.  See the L</"TRY"> directive.

=item C<FOR>

Alias for FOREACH

=item C<FOREACH>

Allows for iterating over the contents of any arrayref.  If the variable is not an
arrayref, it is automatically promoted to one.

    [% FOREACH i IN [1 .. 3] %]
        The variable i = [% i %]
    [%~ END %]

    [% a = [1 .. 3] %]
    [% FOREACH j IN a %]
        The variable j = [% j %]
    [%~ END %]

Would print:

        The variable i = 1
        The variable i = 2
        The variable i = 3

        The variable j = 1
        The variable j = 2
        The variable j = 3

You can also use the "=" instead of "IN" or "in".

    [% FOREACH i = [1 .. 3] %]
        The variable i = [% i %]
    [%~ END %]

    Same as before.

Setting into a variable is optional.

    [% a = [1 .. 3] %]
    [% FOREACH a %] Hi [% END %]

Would print:

     hi  hi  hi 

If the item being iterated is a hashref and the FOREACH does not
set into a variable, then values of the hashref are copied into
the variable stash.

    [% FOREACH [{a => 1}, {a => 2}] %]
        Key a = [% a %]
    [%~ END %]

Would print:

        Key a = 1
        Key a = 2

The FOREACH process uses the CGI::Ex::Template::Iterator class to handle
iterations (It is compatible with Template::Iterator).  During the FOREACH
loop an object blessed into the iterator class is stored in the variable "loop".

The loop variable provides the following information during a FOREACH:

    index  - the current index
    max    - the max index of the list
    size   - the number of items in the list
    count  - index + 1
    number - index + 1
    first  - true if on the first item
    last   - true if on the last item
    next   - return the next item in the list
    prev   - return the previous item in the list

The following:

    [% FOREACH [1 .. 3] %] [% loop.count %]/[% loop.size %] [% END %]

Would print:

     1/3  2/3  3/3 

The iterator is also available using a plugin.  This allows for access
to multiple "loop" variables in a nested FOREACH directive.

    [%~ USE outer_loop = Iterator(["a", "b"]) %]
    [%~ FOREACH i = outer_loop %]
        [%~ FOREACH j = ["X", "Y"] %]
           [% outer_loop.count %]-[% loop.count %] = ([% i %] and [% j %])
        [%~ END %]
    [%~ END %]

Would print:

           1-1 = (a and X)
           1-2 = (a and Y)
           2-1 = (b and X)
           2-2 = (b and Y)

FOREACH may also be used as a post operative directive.

    [% "$i" FOREACH i = [1 .. 5] %] => 12345

=item C<GET>

Return the value of a variable or expression.

    [% GET a %]

The GET keyword may be omitted.

    [% a %]

    [% 7 + 2 - 3 %] => 6

See the section on VARIABLES.

=item C<IF (IF / ELSIF / ELSE)>

Allows for conditional testing.  Expects an expression as its only
argument.  If the expression is true, the contents of its block are
processed.  If false, the processor looks for an ELSIF block.  If an
ELSIF's expression is true then it is processed.  Finally it looks for
an ELSE block which is processed if none of the IF or ELSIF's
expressions were true.

    [% IF a == b %]A equaled B[% END %]

    [% IF a == b -%]
        A equaled B
    [%- ELSIF a == c -%]
        A equaled C
    [%- ELSE -%]
        Couldn't determine that A equaled anything.
    [%- END %]

IF may also be used as a post operative directive.

    [% 'A equaled B' IF a == b %]

Note: If you are using HTML::Template style documents, the TMPL_IF
tag parses using the limited HTML::Template parsing rules.  However,
you may use EXPR="" to embed a TT3 style expression.

=item C<INCLUDE>

Parse the contents of a file or block and insert them.  Variables defined
or modifications made to existing variables are discarded after
a template is included.

    [% INCLUDE path/to/template.html %]

    [% INCLUDE "path/to/template.html" %]

    [% file = "path/to/template.html" %]
    [% INCLUDE $file %]

    [% BLOCK foo %]This is foo[% END %]
    [% INCLUDE foo %]

Arguments may also be passed to the template:

    [% INCLUDE "path/to/template.html" a = "An arg" b = "Another arg" %]

Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE
or RELATIVE configuration items are set.

Multiple filenames can be passed by separating them with a plus, a space,
or commas (TT2 doesn't support the comma).  Any supplied arguments will
be used on all templates.

    [% INCLUDE "path/to/template.html",
               "path/to/template2.html" a = "An arg" b = "Another arg" %]

=item C<INSERT>

Insert the contents of a file without template parsing.

Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE
or RELATIVE configuration items are set.

Multiple filenames can be passed by separating them with a plus, a space,
or commas (TT2 doesn't support the comma).

    [% INSERT "path/to/template.html",
              "path/to/template2.html" %]

=item C<LAST>

Used to exit out of a WHILE or FOREACH loop.

=item C<LOOP>

This directive operates similar to the HTML::Template loop directive.
The LOOP directive expects a single variable name.  This variable name
should point to an arrayref of hashrefs.  The keys of each hashref
will be added to the variable stash when it is iterated.

    [% var a = [{b => 1}, {b => 2}, {b => 3}] %]

    [% LOOP a %] ([% b %]) [% END %]

Would print:

     (1)  (2)  (3) 

If CET is in HT mode and GLOBAL_VARS is false, the contents of
the hashref will be the only items available during the loop iteration.

If LOOP_CONTEXT_VARS is true, and $QR_PRIVATE is false (default when
called through the output method), then the variables __first__, __last__,
 __inner__, __odd__, and __counter__ will be set.  See the HTML::Template
loop_context_vars configuration item for more information.

=item C<MACRO>

Takes a directive and turns it into a variable that can take arguments.

    [% MACRO foo(i, j) BLOCK %]You passed me [% i %] and [% j %].[% END %]

    [%~ foo("a", "b") %]
    [% foo(1, 2) %]

Would print:

    You passed me a and b.
    You passed me 1 and 2.

Another example:

    [% MACRO bar(max) FOREACH i = [1 .. max] %]([% i %])[% END %]

    [%~ bar(4) %]

Would print:

    (1)(2)(3)(4)

=item C<META>

Used to define variables that will be available via either the
template or component namespace.

Once defined, they cannot be overwritten.

    [% template.foobar %]
    [%~ META foobar = 'baz' %]
    [%~ META foobar = 'bing' %]

Would print:

    baz

=item C<NEXT>

Used to go to the next iteration of a WHILE or FOREACH loop.

=item C<PERL>

Only available if the EVAL_PERL configuration item is true (default is false).

Allow eval'ing the block of text as perl.  The block will be parsed and then eval'ed.

    [% a = "BimBam" %]
    [%~ PERL %]
        my $a = "[% a %]";
        print "The variable \$a was \"$a\"";
        $stash->set('b', "FooBar");
    [% END %]
    [% b %]

Would print:

    The variable $a was "BimBam"
    FooBar

During execution, anything printed to STDOUT will be inserted into the template.  Also,
the $stash and $context variables are set and are references to objects that mimic the
interface provided by Template::Context and Template::Stash.  These are provided for
compatibility only.  $self contains the current CGI::Ex::Template object.

=item C<PROCESS>

Parse the contents of a file or block and insert them.  Unlike INCLUDE,
no variable localization happens so variables defined or modifications made
to existing variables remain after the template is processed.

    [% PROCESS path/to/template.html %]

    [% PROCESS "path/to/template.html" %]

    [% file = "path/to/template.html" %]
    [% PROCESS $file %]

    [% BLOCK foo %]This is foo[% END %]
    [% PROCESS foo %]

Arguments may also be passed to the template:

    [% PROCESS "path/to/template.html" a = "An arg" b = "Another arg" %]

Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE
or RELATIVE configuration items are set.

Multiple filenames can be passed by separating them with a plus, a space,
or commas (TT2 doesn't support the comma).  Any supplied arguments will
be used on all templates.

    [% PROCESS "path/to/template.html",
               "path/to/template2.html" a = "An arg" b = "Another arg" %]

=item C<RAWPERL>

Only available if the EVAL_PERL configuration item is true (default is false).
Similar to the PERL directive, but you will need to append
to the $output variable rather than just calling PRINT.

=item C<RETURN>

Used to exit the innermost block or template and continue processing
in the surrounding block or template.

=item C<SET>

Used to set variables.

   [% SET a = 1 %][% a %]             => "1"
   [% a = 1 %][% a %]                 => "1"
   [% b = 1 %][% SET a = b %][% a %]  => "1"
   [% a = 1 %][% SET a %][% a %]      => ""
   [% SET a = [1, 2, 3] %][% a.1 %]   => "2"
   [% SET a = {b => 'c'} %][% a.b %]  => "c"

=item C<STOP>

Used to exit the entire process method (out of all blocks and templates).
No content will be processed beyond this point.

=item C<SWITCH>

Allow for SWITCH and CASE functionality.

   [% a = "hi" %]
   [% b = "bar" %]
   [% SWITCH a %]
       [% CASE "foo"           %]a was foo
       [% CASE b               %]a was bar
       [% CASE ["hi", "hello"] %]You said hi or hello
       [% CASE DEFAULT         %]I don't know what you said
   [% END %]

Would print:

   You said hi or hello

=item C<TAGS>

Change the type of enclosing braces used to delineate template tags.  This
remains in effect until the end of the enclosing block or template or until
the next TAGS directive.  Either a named set of tags must be supplied, or
two tags themselves must be supplied.

    [% TAGS html %]

    [% TAGS <!-- --> %]

The named tags are (duplicated from TT):

    asp       => ['<%',     '%>'    ], # ASP
    default   => ['\[%',    '%\]'   ], # default
    html      => ['<!--',   '-->'   ], # HTML comments
    mason     => ['<%',     '>'     ], # HTML::Mason
    metatext  => ['%%',     '%%'    ], # Text::MetaText
    php       => ['<\?',    '\?>'   ], # PHP
    star      => ['\[\*',   '\*\]'  ], # TT alternate
    template  => ['\[%',    '%\]'   ], # Normal Template Toolkit
    template1 => ['[\[%]%', '%[%\]]'], # allow TT1 style
    tt2       => ['\[%',    '%\]'   ], # TT2

If custom tags are supplied, by default they are escaped using
quotemeta.  You may also pass explicitly quoted strings,
or regular expressions as arguments as well (if your
regex begins with a ', ", or / you must quote it.

    [% TAGS [<] [>] %]          matches "[<] tag [>]"

    [% TAGS '[<]' '[>]' %]      matches "[<] tag [>]"

    [% TAGS "[<]" "[>]" %]      matches "[<] tag [>]"

    [% TAGS /[<]/ /[>]/ %]      matches "< tag >"

    [% TAGS ** ** %]            matches "** tag **"

    [% TAGS /**/ /**/ %]        Throws an exception.

=item C<THROW>

Allows for throwing an exception.  If the exception is not caught
via the TRY DIRECTIVE, the template will abort processing of the directive.

    [% THROW mytypes.sometime 'Something happened' arg1 => val1 %]

See the TRY directive for examples of usage.

=item C<TRY>

The TRY block directive will catch exceptions that are thrown
while processing its block (It cannot catch parse errors unless
they are in included files or evaltt'ed strings.   The TRY block
will then look for a CATCH block that will be processed.  While
it is being processed, the "error" variable will be set with the thrown
exception as the value.  After the TRY block - the FINAL
block will be ran whether or not an error was thrown (unless a CATCH
block throws an error).

Note: Parse errors cannot be caught unless they are in an eval FILTER, or are
in a separate template being INCLUDEd or PROCESSed.

    [% TRY %]
    Nothing bad happened.
    [% CATCH %]
    Caught the error.
    [% FINAL %]
    This section runs no matter what happens.
    [% END %]

Would print:

    Nothing bad happened.
    This section runs no matter what happens.

Another example:

    [% TRY %]
    [% THROW "Something happened" %]
    [% CATCH %]
      Error:               [% error %]
      Error.type:          [% error.type %]
      Error.info:          [% error.info %]
    [% FINAL %]
      This section runs no matter what happens.
    [% END %]

Would print:

      Error:               undef error - Something happened
      Error.type:          undef
      Error.info:          Something happened
      This section runs no matter what happens.

You can give the error a type and more information including named arguments.
This information replaces the "info" property of the exception.

    [% TRY %]
    [% THROW foo.bar "Something happened" "grrrr" foo => 'bar' %]
    [% CATCH %]
      Error:               [% error %]
      Error.type:          [% error.type %]
      Error.info:          [% error.info %]
      Error.info.0:        [% error.info.0 %]
      Error.info.1:        [% error.info.1 %]
      Error.info.args.0:   [% error.info.args.0 %]
      Error.info.foo:      [% error.info.foo %]
    [% END %]

Would print something like:

      Error:               foo.bar error - HASH(0x82a395c)
      Error.type:          foo.bar
      Error.info:          HASH(0x82a395c)
      Error.info.0:        Something happened
      Error.info.1:        grrrr
      Error.info.args.0:   Something happened
      Error.info.foo:      bar

You can also give the CATCH block a type to catch.  And you
can nest TRY blocks.  If types are specified, CET will try and
find the closest matching type.  Also, an error object can
be re-thrown using $error as the argument to THROW.

    [% TRY %]
      [% TRY %]
        [% THROW foo.bar "Something happened" %]
      [% CATCH bar %]
        Caught bar.
      [% CATCH DEFAULT %]
        Caught default - but rethrew.
        [% THROW $error %]
      [% END %]
    [% CATCH foo %]
      Caught foo.
    [% CATCH foo.bar %]
      Caught foo.bar.
    [% CATCH %]
      Caught anything else.
    [% END %]

Would print:

        Caught default - but rethrew.

      Caught foo.bar.

=item C<UNLESS>

Same as IF but condition is negated.

    [% UNLESS 0 %]hi[% END %]  => hi

Can also be a post operative directive.

=item C<USE>

Allows for loading a Template::Toolkit style plugin.

    [% USE iter = Iterator(['foo', 'bar']) %]
    [%~ iter.get_first %]
    [% iter.size %]

Would print:

    foo
    2

Note that it is possible to send arguments to the new object
constructor.  It is also possible to omit the variable name being
assigned.  In that case the name of the plugin becomes the variable.

    [% USE Iterator(['foo', 'bar', 'baz']) %]
    [%~ Iterator.get_first %]
    [% Iterator.size %]

Would print:

    foo
    3

Plugins that are loaded are looked up for in the namespace listed in
the PLUGIN_BASE directive which defaults to Template::Plugin.  So in
the previous example, if Template::Toolkit was installed, the iter
object would loaded by the class Template::Plugin::Iterator.  In CET,
an effective way to disable plugins is to set the PLUGIN_BASE to a
non-existent base such as "_" (In TT it will still fall back to look
in Template::Plugin).

Note: The iterator plugin will fall back and use
CGI::Ex::Template::Iterator if Template::Toolkit is not installed.  No
other plugins come installed with CGI::Ex::Template.

The names of the Plugin being loaded from PLUGIN_BASE are case
insensitive.  However, using case insensitive names is bad as it
requires scanning the @INC directories for any module matching the
PLUGIN_BASE and caching the result (OK - not that bad).

If the plugin is not found and the LOAD_PERL directive is set, then
CET will try and load a module by that name (note: this type of lookup
is case sensitive and will not scan the @INC dirs for a matching
file).

    # The LOAD_PERL directive should be set to 1
    [% USE cet = CGI::Ex::Template %]
    [%~ cet.dump_parse_expr('2 * 3').replace('\s+', ' ') %]

Would print:

    $VAR1 = [ [ undef, '*', '2', '3' ], 0 ];

See the PLUGIN_BASE, and PLUGINS configuration items.

See the documentation for Template::Manual::Plugins.

=item C<VIEW>

Implement a TT style view.  For more information, please
see the Template::View documentation.  This DIRECTIVE
will correctly parse the arguments and then pass them
along to a newly created Template::View object.  It
will fail if Template::View can not be found.

=item C<WHILE>

Will process a block of code while a condition is true.

    [% WHILE i < 3 %]
        [%~ i = i + 1 %]
        i = [% i %]
    [%~ END %]

Would print:

        i = 1
        i = 2
        i = 3

You could also do:

    [% i = 4 %]
    [% WHILE (i = i - 1) %]
        i = [% i %]
    [%~ END %]

Would print:

        i = 3
        i = 2
        i = 1

Note that (f = f - 1) is a valid expression that returns the value
of the assignment.  The parenthesis are not optional.

WHILE has a built in limit of 1000 iterations.  This is controlled by the
global variable $WHILE_MAX in CGI::Ex::Template.

WHILE may also be used as a post operative directive.

    [% "$i" WHILE (i = i + 1) < 7 %] => 123456

=item C<WRAPPER>

Block directive.  Processes contents of its block and then passes them
in the [% content %] variable to the block or filename listed in the
WRAPPER tag.

    [% WRAPPER foo b = 23 %]
    My content to be processed ([% b %]).[% a = 2 %]
    [% END %]

    [% BLOCK foo %]
    A header ([% a %]).
    [% content %]
    A footer ([% a %]).
    [% END %]

This would print.

    A header (2).
    My content to be processed (23).
    A footer (2).

The WRAPPER directive may also be used as a post operative directive.

    [% BLOCK baz %]([% content %])[% END -%]
    [% "foobar" WRAPPER baz %]

Would print

    (foobar)');

Multiple filenames can be passed by separating them with a plus, a space,
or commas (TT2 doesn't support the comma).  Any supplied arguments will
be used on all templates.  Wrappers are processed in reverse order, so
that the first wrapper listed will surround each subsequent wrapper listed.
Variables from inner wrappers are available to the next wrapper that
surrounds it.

    [% WRAPPER "path/to/outer.html",
               "path/to/inner.html" a = "An arg" b = "Another arg" %]


=back

=head1 DIRECTIVES (HTML::Template Style)

HTML::Template templates use directives that look similar to the
following:

    <TMPL_VAR NAME="foo">

    <TMPL_IF NAME="bar">
      BAR
    </TMPL_IF>

The normal set of HTML::Template directives are TMPL_VAR,
TMPL_IF, TMPL_ELSE, TMPL_UNLESS, TMPL_INCLUDE, and TMPL_LOOP.
These tags should have either a NAME attribute, an EXPR attribute,
or a bare variable name that is used to specify the value to
be operated.  If a NAME is specified, it may only be a single
level value (as opposed to a TT chained variable).  In the case
of the TMPL_INCLUDE directive, the NAME is the file to be included.

In CET, the EXPR attribute can be used with any of these types to
specify TT compatible variable or expression that will be used for
the value.

    <TMPL_VAR NAME="foo">          Prints the value contained in foo
    <TMPL_VAR foo>                 Prints the value contained in foo
    <TMPL_VAR EXPR="foo">          Prints the value contained in foo

    <TMPL_VAR NAME="foo.bar.baz">  Prints the value contained in {'foo.bar.baz'}
    <TMPL_VAR EXPR="foo.bar.baz">  Prints the value contained in {foo}->{bar}->{baz}

    <TMPL_IF foo>                  Prints FOO if foo is true
      FOO
    </TMPL_IF

    <TMPL_UNLESS foo>              Prints FOO unless foo is true
      FOO
    </TMPL_UNLESS

    <TMPL_INCLUDE NAME="foo.ht">   Includes the template in "foo.ht"

    <TMPL_LOOP foo>                Iterates on the arrayref foo
      <TMPL_VAR name>
    </TMPL_LOOP>

CGI::Ex::Template makes all of the other TT3 directives available
in addition to the normal set of HTML::Template directives.  For
example, the following is valid in CET.

    <TMPL_MACRO bar(n) BLOCK>You said <TMPL_VAR n></TMPL_MACRO>
    <TMPL_GET bar("hello")>

The TMPL_VAR tag may also include an optional ESCAPE attribute.
This specifies how the value of the tag should be escaped prior
to substituting into the template.

    Escape value |   Type of escape
    ---------------------------------
    HTML, 1      |   HTML encoding
    URL          |   URL encoding
    JS           |   basic javascript encoding (\n, \r, and \")
    NONE, 0      |   No encoding (default).

The TMPL_VAR tag may also include an optional DEFAULT attribute
that contains a string that will be used if the variable returns
false.

    <TMPL_VAR foo DEFAULT="Foo was false">

=head1 OPERATORS

The following operators are available in CGI::Ex::Template.  Except
where noted these are the same operators available in TT.  They are
listed in the order of their precedence (the higher the precedence the
tighter it binds).

=over 4

=item C<.>

The dot operator.  Allows for accessing sub-members, methods, or
virtual methods of nested data structures.

    my $obj->process(\$content, {a => {b => [0, {c => [34, 57]}]}}, \$output);

    [% a.b.1.c.0 %] => 34

Note: on access to hashrefs, any hash keys that match the sub key name
will be used before a virtual method of the same name.  For example if
a passed hash contained pair with a keyname "defined" and a value of
"2", then any calls to hash.defined(another_keyname) would always
return 2 rather than using the vmethod named "defined."  To get around
this limitation use the "|" operator (listed next).  Also - on objects
the "." will always try and call the method by that name.  To always
call the vmethod - use "|".

=item C<|>

The pipe operator.  Similar to the dot operator.  Allows for
explicit calling of virtual methods and filters (filters are "merged"
with virtual methods in CGI::Ex::Template and TT3) when accessing
hashrefs and objects.  See the note for the "." operator.

The pipe character is similar to TT2 in that it can be used in place
of a directive as an alias for FILTER.  It similar to TT3 in that it
can be used for virtual method access.  This duality is one source of
difference between CGI::Ex::Template and TT2 compatibility.  Templates
that have directives that end with a variable name that then use the
"|" directive to apply a filter will be broken as the "|" will be
applied to the variable name.

The following two cases will do the same thing.

    [% foo | html %]

    [% foo FILTER html %]

Though they do the same thing, internally, foo|html is stored as a
single variable while "foo FILTER html" is stored as the variable foo
which is then passed to the FILTER html.

A TT2 sample that would break in CGI::Ex::Template or TT3 is:

    [% PROCESS foo a = b | html %]

Under TT2 the content returned by "PROCESS foo a = b" would all be
passed to the html filter.  Under CGI::Ex::Template and TT3, b would
be passed to the html filter before assigning it to the variable "a"
before the template foo was processed.

A simple fix is to do any of the following:

    [% PROCESS foo a = b FILTER html %]

    [% | html %][% PROCESS foo a = b %][% END %]

    [% FILTER html %][% PROCESS foo a = b %][% END %]

This shouldn't be too much hardship and offers the great return of disambiguating
virtual method access.

=item C<\>

Unary.  The reference operator.  Not well publicized in TT.  Stores a reference
to a variable for use later.  Can also be used to "alias" long names.

    [% f = 7 ; foo = \f ; f = 8 ; foo %] => 8

    [% foo = \f.g.h.i.j.k; f.g.h.i.j.k = 7; foo %] => 7

    [% f = "abcd"; foo = \f.replace("ab", "-AB-") ; foo %] => -AB-cd

    [% f = "abcd"; foo = \f.replace("bc") ; foo("-BC-") %] => a-BC-d

    [% f = "abcd"; foo = \f.replace ; foo("cd", "-CD-") %] => ab-CD-

=item C<++ -->

Pre and post increment and decrement.  My be used as either a prefix
or postfix operator.

    [% ++a %][% ++a %] => 12

    [% a++ %][% a++ %] => 01

    [% --a %][% --a %] => -1-2

    [% a-- %][% a-- %] => 0-1

=item C<**  ^  pow>

Right associative binary.  X raised to the Y power.  This isn't available in TT 2.15.

    [% 2 ** 3 %] => 8

=item C<!>

Prefix not.  Negation of the value.

=item C<->

Prefix minus.  Returns the value multiplied by -1.

    [% a = 1 ; b = -a ; b %] => -1

=item C<*>

Left associative binary. Multiplication.

=item C</  div  DIV>

Left associative binary. Division.  Note that / is floating point division, but div and
DIV are integer division.

   [% 10  /  4 %] => 2.5
   [% 10 div 4 %] => 2

=item C<%  mod  MOD>

Left associative binary. Modulus.

   [% 15 % 8 %] => 7

=item C<+>

Left associative binary.  Addition.

=item C<->

Left associative binary.  Minus.

=item C<_  ~>

Left associative binary.  String concatenation.

    [% "a" ~ "b" %] => ab

=item C<< <  >  <=  >= >>

Non associative binary.  Numerical comparators.

=item C<lt  gt  le  ge>

Non associative binary.  String comparators.

=item C<eq>

Non associative binary.  String equality test.

=item C<==>

Non associative binary. In TT syntaxes the V2EQUALS configuration
item defaults to true which means this operator will operate
the same as the "eq" operator.  Setting V2EQUALS to 0 will
change this operator to mean numeric equality.  You could also use [% ! (a <=> b) %]
but that is a bit messy.

The HTML::Template syntaxes default V2EQUALS to 0 which means
that it will test for numeric equality just as you would normally
expect.

In either case - you should always use "eq" when you mean "eq".
The V2EQUALS will most likely eventually default to 0.

=item C<ne>

Non associative binary.  String non-equality test.

=item C<!=>

Non associative binary. In TT syntaxes the V2EQUALS configuration
item defaults to true which means this operator will operate
the same as the "ne" operator.  Setting V2EQUALS to 0 will
change this operator to mean numeric non-equality.
You could also use [% (a <=> b) %] but that is a bit messy.

The HTML::Template syntaxes default V2EQUALS to 0 which means
that it will test for numeric non-equality just as you would
normally expect.

In either case - you should always use "ne" when you mean "ne".
The V2EQUALS will most likely eventually default to 0.

=item C<< <=> >>

Non associative binary.  Numeric comparison operator.  Returns -1 if the first argument is
less than the second, 0 if they are equal, and 1 if the first argument is greater.

=item C<< cmp >>

Non associative binary.  String comparison operator.  Returns -1 if the first argument is
less than the second, 0 if they are equal, and 1 if the first argument is greater.

=item C<&&>

Left associative binary.  And.  All values must be true.  If all values are true, the last
value is returned as the truth value.

    [% 2 && 3 && 4 %] => 4

=item C<||>

Right associative binary.  Or.  The first true value is returned.

    [% 0 || '' || 7 %] => 7

Note: perl is left associative on this operator - but it doesn't matter because
|| has its own precedence level.  Setting it to right allows for CET to short
circuit earlier in the expression optree (left is (((1,2), 3), 4) while right
is (1, (2, (3, 4))).

=item C<..>

Non associative binary.  Range creator.  Returns an arrayref containing the values
between and including the first and last arguments.

    [% t = [1 .. 5] %] => variable t contains an array with 1,2,3,4, and 5

It is possible to place multiple ranges in the same [] constructor.  This is not available in TT.

    [% t = [1..3, 6..8] %] => variable t contains an array with 1,2,3,6,7,8

The .. operator is the only operator that returns a list of items.

=item C<? :>

Ternary - right associative.  Can be nested with other ?: pairs.

    [% 1 ? 2 : 3 %] => 2
    [% 0 ? 2 : 3 %] => 3

=item C<*= += -= /= **= %= ~=>

Self-modifying assignment - right associative.  Sets the left hand side
to the operation of the left hand side and right (clear as mud).
In order to not conflict with SET, FOREACH and other operations, this
operator is only available in parenthesis.

   [% a = 2 %][%  a += 3  %] --- [% a %]    => --- 5   # is handled by SET
   [% a = 2 %][% (a += 3) %] --- [% a %]    => 5 --- 5

=item C<=>

Assignment - right associative.  Sets the left-hand side to the value of the righthand side.  In order
to not conflict with SET, FOREACH and other operations, this operator is only
available in parenthesis.  Returns the value of the righthand side.

   [%  a = 1  %] --- [% a %]    => --- 1   # is handled by SET
   [% (a = 1) %] --- [% a %]    => 1 --- 1

=item C<not  NOT>

Prefix. Lower precedence version of the '!' operator.

=item C<and  AND>

Left associative. Lower precedence version of the '&&' operator.

=item C<or OR>

Right associative. Lower precedence version of the '||' operator.

=item C<{}>

This operator is not used in TT.  It is used internally
by CGI::Ex::Template to delay the creation of a hash until the
execution of the compiled template.

=item C<[]>

This operator is not used in TT.  It is used internally
by CGI::Ex::Template to delay the creation of an array until the
execution of the compiled template.

=item C<qr>

This operator is not used in TT.  It is used internally
by CGI::Ex::Template to store a regular expression and its options.
It will return a compiled Regexp object when compiled.

=back


=head1 CHOMPING

Chomping refers to the handling of whitespace immediately before and
immediately after template tags.  By default, nothing happens to this
whitespace.  Modifiers can be placed just inside the opening and just
before the closing tags to control this behavior.

Additionally, the PRE_CHOMP and POST_CHOMP configuration variables can
be set and will globally control all chomping behavior for tags that
do not have their own chomp modifier.  PRE_CHOMP and POST_CHOMP can
be set to any of the following values:

    none:      0   +   Template::Constants::CHOMP_NONE
    one:       1   -   Template::Constants::CHOMP_ONE
    collapse:  2   =   Template::Constants::CHOMP_COLLAPSE
    greedy:    3   ~   Template::Constants::CHOMP_GREEDY

=over 4

=item CHOMP_NONE

Don't do any chomping.  The "+" sign is used to indicate CHOMP_NONE.

    Hello.

    [%+ "Hi." +%]

    Howdy.

Would print:

    Hello.

    Hi.

    Howdy.

=item CHOMP_ONE (formerly known as CHOMP_ALL)

Delete any whitespace up to the adjacent newline.  The "-" is used to indicate CHOMP_ONE.

    Hello.

    [%- "Hi." -%]

    Howdy.

Would print:

    Hello.
    Hi.
    Howdy.

=item CHOMP_COLLAPSE

Collapse adjacent whitespace to a single space.  The "=" is used to indicate CHOMP_COLLAPSE.

    Hello.

    [%= "Hi." =%]

    Howdy.

Would print:

    Hello. Hi. Howdy.

=item CHOMP_GREEDY

Remove all adjacent whitespace.  The "~" is used to indicate CHOMP_GREEDY.

    Hello.

    [%~ "Hi." ~%]

    Howdy.

Would print:

    Hello.Hi.Howdy.

=head1 CONFIGURATION (TT STYLE)

The following TT2 configuration variables are supported (in
alphabetical order).  Note: for further discussion you can refer to
the TT config documentation.

Items may be passed in upper or lower case.

These variables should be passed to the "new" constructor.

    my $obj = CGI::Ex::Template->new(
        VARIABLES  => \%hash_of_variables,
        AUTO_RESET => 0,
        TRIM       => 1,
        POST_CHOMP => "=",
        PRE_CHOMP  => "-",
    );


=over 4

=item ABSOLUTE

Boolean.  Default false.  Are absolute paths allowed for included files.

=item ANYCASE

Allow directive matching to be case insensitive.

    [% get 23 %] prints 23 with ANYCASE => 1

=item AUTO_RESET

Boolean.  Default 1.  Clear blocks that were set during the process method.

=item BLOCKS

A hashref of blocks that can be used by the process method.

    BLOCKS => {
        block_1 => sub { ... }, # coderef that returns a block
        block_2 => 'A String',  # simple string
    },

Note that a Template::Document cannot be supplied as a value (TT
supports this).  However, it is possible to supply a value that is
equal to the hashref returned by the load_parsed_tree method.

=item CACHE_SIZE

Number of compiled templates to keep in memory.  Default undef.
Undefined means to allow all templates to cache.  A value of 0 will
force no caching.  The cache mechanism will clear templates that have
not been used recently.

=item COMPILE_DIR

Base directory to store compiled templates.  Default undef. Compiled
templates will only be stored if one of COMPILE_DIR and COMPILE_EXT is
set.

=item COMPILE_EXT

Extension to add to stored compiled template filenames.  Default undef.

=item CONSTANTS

Hashref.  Used to define variables that will be "folded" into the
compiled template.  Variables defined here cannot be overridden.

    CONSTANTS => {my_constant => 42},

    A template containing:

    [% constants.my_constant %]

    Will have the value 42 compiled in.

Constants defined in this way can be chained as in [%
constant.foo.bar.baz %].

=item CONSTANT_NAMESPACE

Allow for setting the top level of values passed in CONSTANTS.  Default
value is 'constants'.

=item DEBUG

Takes a list of constants |'ed together which enables different
debugging modes.  Alternately the lowercase names may be used
(multiple values joined by a ",").

    The only supported TT values are:
    DEBUG_UNDEF (2)    - debug when an undefined value is used.
    DEBUG_DIRS  (8)    - debug when a directive is used.
    DEBUG_ALL   (2047) - turn on all debugging.

    Either of the following would turn on undef and directive debugging:

    DEBUG => 'undef, dirs',            # preferred
    DEBUG => 2 | 8,
    DEBUG => DEBUG_UNDEF | DEBUG_DIRS, # constants from Template::Constants

=item DEBUG_FORMAT

Change the format of messages inserted when DEBUG has DEBUG_DIRS set on.
This essentially the same thing as setting the format using the DEBUG
directive.

=item DEFAULT

The name of a default template file to use if the passed one is not found.

=item DELIMITER

String to use to split INCLUDE_PATH with.  Default is :.  It is more
straight forward to just send INCLUDE_PATH an arrayref of paths.

=item DUMP

Configures the behavior of the DUMP tag.  May be set to 0, a hashref,
or another true value.  Default is true.

If set to 0, all DUMP directives will do nothing.  This is useful if
you would like to turn off the DUMP directives under some environments.

IF set to a true value (or undefined) then DUMP directives will operate.

If set to a hashref, the values of the hash can be used to configure
the operation of the DUMP directives.  The following are the values
that can be set in this hash.

=over 4

=item EntireStash

Default 1.  If set to 0, then the DUMP directive will not print the
entire contents of the stash when a DUMP directive is called without
arguments.

=item handler

Defaults to an internal coderef.  If set to a coderef, the DUMP directive will pass the
arguments to be dumped and expects a string with the dumped data.  This
gives complete control over the dump process.

Note 1: The default handler makes sure that values matching the
private variable regex are not included.  If you install your own handler,
you will need to take care of these variables if you intend for them
to not be shown.

Note 2: If you would like the name of the variable to be dumped, include
the string '$VAR1' and the DUMP directive will interpolate the value.  For
example, to dump all output as YAML - you could do the following:

    DUMP => {
       handler => sub {
           require YAML;
           return "\$VAR1 =\n".YAML::Dump(shift);
       },
    }

=item header

Default 1.  Controls whether a header is printed for each DUMP directive.
The header contains the file and line number the DUMP directive was
called from.  If set to 0 the headers are disabled.

=item html

Defaults to 1 if $ENV{'REQUEST_METHOD'} is set - 0 otherwise.  If set to
1, then the output of the DUMP directive is passed to the html filter
and encased in "pre" tags.  If set to 0 no html encoding takes place.

=item Sortkeys, Useqq, Ident, Pad, etc

Any of the Data::Dumper configuration items may be passed.

=back

=item END_TAG

Set a string to use as the closing delimiter for TT.  Default is "%]".

=item ERROR

Used as a fall back when the processing of a template fails.  May either
be a single filename that will be used in all cases, or may be a hashref
of options where the keynames represent error types that will be handled
by the filename in their value.  A key named default will be used if no
other matching keyname can be found.  The selection process is similar
to that of the TRY/CATCH/THROW directives (see those directives for more
information).

    my $t = CGI::Ex::Template->new({
        ERROR => 'general/catch_all_errors.html',
    });

    my $t = CGI::Ex::Template->new({
        ERROR => {
            default   => 'general/catch_all_errors.html',
            foo       => 'catch_all_general_foo_errors.html',
            'foo.bar' => 'catch_foo_bar_errors.html',
        },
    });

Note that the ERROR handler will only be used for errors during the
processing of the main document.  It will not catch errors that
occur in templates found in the PRE_PROCESS, POST_PROCESS, and WRAPPER
configuration items.

=item ERRORS

Same as the ERROR configuration item.  Both may be used interchangably.

=item EVAL_PERL

Boolean.  Default false.  If set to a true value, PERL and RAWPERL blocks
will be allowed to run.  This is a potential security hole, as arbitrary
perl can be included in the template.  If Template::Toolkit is installed,
a true EVAL_PERL value also allows the perl and evalperl filters to be used.

=item FILTERS

Allow for passing in TT style filters.

    my $filters = {
        filter1 =>  sub { my $str = shift; $s =~ s/./1/gs; $s },
        filter2 => [sub { my $str = shift; $s =~ s/./2/gs; $s }, 0],
        filter3 => [sub { my ($context, @args) = @_; return sub { my $s = shift; $s =~ s/./3/gs; $s } }, 1],
    };

    my $str = q{
        [% a = "Hello" %]
        1 ([% a | filter1 %])
        2 ([% a | filter2 %])
        3 ([% a | filter3 %])
    };

    my $obj = CGI::Ex::Template->new(FILTERS => $filters);
    $obj->process(\$str) || die $obj->error;

Would print:

        1 (11111)
        2 (22222)
        3 (33333)

Filters passed in as an arrayref should contain a coderef and a value
indicating if they are dynamic or static (true meaning dynamic).  The
dynamic filters are passed the pseudo context object and any arguments
and should return a coderef that will be called as the filter.  The filter
coderef is then passed the string.

=item INCLUDE_PATH

A string or an arrayref or coderef that returns an arrayref that
contains directories to look for files included by processed
templates.

=item INCLUDE_PATHS

Non-TT item.  Same as INCLUDE_PATH but only takes an arrayref.  If not specified
then INCLUDE_PATH is turned into an arrayref and stored in INCLUDE_PATHS.
Overrides INCLUDE_PATH.

=item INTERPOLATE

Boolean.  Specifies whether variables in text portions of the template will be
interpolated.  For example, the $variable and ${var.value} would be substituted
with the appropriate values from the variable cache (if INTERPOLATE is on).

    [% IF 1 %]The variable $variable had a value ${var.value}[% END %]

=item LOAD_PERL

Indicates if the USE directive can fall back and try and load a perl module
if the indicated module was not found in the PLUGIN_BASE path.  See the
USE directive.

=item MAX_EVAL_RECURSE (CET only)

Will use $CGI::Ex::Template::MAX_EVAL_RECURSE if not present.  Default is 50.
Prevents runaway on the following:

    [% f = "[% f|eval %]" %][% f|eval %]

=item MAX_MACRO_RECURSE (CET only)

Will use $CGI::Ex::Template::MAX_MACRO_RECURSE if not present.  Default is 50.
Prevents runaway on the following:

    [% MACRO f BLOCK %][% f %][% END %][% f %]

=item NAMESPACE

No Template::Namespace::Constants support.  Hashref of hashrefs representing
constants that will be folded into the template at compile time.

    CGI::Ex::Template->new(NAMESPACE => {constants => {
         foo => 'bar',
    }});

Is the same as

    CGI::Ex::Template->new(CONSTANTS => {
         foo => 'bar',
    });

Any number of hashes can be added to the NAMESPACE hash.

=item NEGATIVE_STAT_TTL (Not in TT)

Defaults to STAT_TTL which defaults to $STAT_TTL which defaults to 1.

Similar to STAT_TTL - but represents the time-to-live
seconds until a document that was not found is checked again against
the system for modifications.  Setting this number higher will allow for
fewer file system accesses.  Setting it to a negative number will allow
for the file system to be checked every hit.

=item OUTPUT

Alternate way of passing in the output location for processed templates.
If process is not passed an output argument, it will look for this value.

See the process method for a listing of possible values.

=item OUTPUT_PATH

Base path for files written out via the process method or via the redirect
and file filters.  See the redirect virtual method and the process method
for more information.

=item PLUGINS

A hashref of mappings of plugin modules.

   PLUGINS => {
      Iterator => 'Template::Plugin::Iterator',
      DBI      => 'MyDBI',
   },

See the USE directive for more information.

=item PLUGIN_BASE

Default value is Template::Plugin.  The base module namespace
that template plugins will be looked for.  See the USE directive
for more information.  May be either a single namespace, or an arrayref
of namespaces.

=item POST_CHOMP

Set the type of chomping at the ending of a tag.
See the section on chomping for more information.

=item POST_PROCESS

A list of templates to be processed and appended to the content
after the main template.  During this processing the "template"
namespace will contain the name of the main file being processed.

This is useful for adding a global footer to all templates.

=item PRE_CHOMP

Set the type of chomping at the beginning of a tag.
See the section on chomping for more information.

=item PRE_DEFINE

Same as the VARIABLES configuration item.

=item PRE_PROCESS

A list of templates to be processed before and pre-pended to the content
before the main template.  During this processing the "template"
namespace will contain the name of the main file being processed.

This is useful for adding a global header to all templates.

=item PROCESS

Specify a file to use as the template rather than the one passed in
to the ->process method.

=item RECURSION

Boolean.  Default false.  Indicates that INCLUDED or PROCESSED files
can refer to each other in a circular manner.  Be careful about recursion.

=item RELATIVE

Boolean.  Default false.  If true, allows filenames to be specified
that are relative to the currently running process.

=item SEMICOLONS

Boolean.  Default fast.  If true, then the syntax will require that
semi-colons separate multiple directives in the same tag.  This is
useful for keeping the syntax a little more clean as well as trouble
shooting some errors.

=item START_TAG

Set a string to use as the opening delimiter for TT.  Default is "[%".

=item STAT_TTL

Defaults to $STAT_TTL which defaults to 1.  Represents time-to-live
seconds until a cached in memory document is compared to the file
system for modifications.  Setting this number higher will allow for
fewer file system accesses.  Setting it to a negative number will allow
for the file system to be checked every hit.

=item SYNTAX (not in TT)

Defaults to "cet".  Indicates the syntax that will be used for parsing
included templates or eval'ed strings.  You can use the CONFIG
directive to change the SYNTAX on the fly (it will not affect
the syntax of the document currently being parsed).

The syntax may be passed in upper or lower case.

The available choices are:

    cet - CGI::Ex::Template style - the same as TT3
    tt3 - Template::Toolkit ver3 - same as CET
    tt2 - Template::Toolkit ver2 - almost the same as TT3
    tt1 - Template::Toolkit ver1 - almost the same as TT2
    ht  - HTML::Template - same as HTML::Template::Expr without EXPR
    hte - HTML::Template::Expr

Passing in a different syntax allows for the process method
to use a non-TT syntax and for the output method to use a non-HT
syntax.

The following is a sample of HTML::Template interface usage parsing
a Template::Toolkit style document.

    my $obj = CGI::Ex::Template->new(filename => 'my/template.tt'
                                     syntax   => 'cet');
    $obj->param(\%swap);
    print $obj->output;

The following is a sample of Template::Toolkit interface usage parsing
a HTML::Template::Expr style document.

    my $obj = CGI::Ex::Template->new(SYNTAX => 'hte');
    $obj->process('my/template.ht', \%swap);

You can use the define_syntax method to add another custom syntax to
the list of available options.

=item TAG_STYLE

Allow for setting the type of tag delimiters to use for parsing the TT.
See the TAGS directive for a listing of the available types.

=item TRIM

Remove leading and trailing whitespace from blocks and templates.
This operation is performed after all enclosed template tags have
been executed.

=item UNDEFINED_ANY

This is not a TT configuration option.  This option expects to be a code
ref that will be called if a variable is undefined during a call to play_expr.
It is passed the variable identity array as a single argument.  This
is most similar to the "undefined" method of Template::Stash.  It allows
for the "auto-defining" of a variable for use in the template.  It is
suggested that UNDEFINED_GET be used instead as UNDEFINED_ANY is a little
to general in defining variables.

You can also sub class the module and override the undefined_any method.

=item UNDEFINED_GET

This is not a TT configuration option.  This option expects to be a code
ref that will be called if a variable is undefined during a call to GET.
It is passed the variable identity array as a single argument.  This is more useful
than UNDEFINED_ANY in that it is only called during a GET directive
rather than in embedded expressions (such as [% a || b || c %]).

You can also sub class the module and override the undefined_get method.

=item V1DOLLAR

This allows for some compatibility with TT1 templates.  The only real
behavior change is that [% $foo %] becomes the same as [% foo %].  The
following is a basic table of changes invoked by using V1DOLLAR.

   With V1DOLLAR        Equivalent Without V1DOLLAR (Normal default)
   "[% foo %]"          "[% foo %]"
   "[% $foo %]"         "[% foo %]"
   "[% ${foo} %]"       "[% ${foo} %]"
   "[% foo.$bar %]"     "[% foo.bar %]"
   "[% ${foo.bar} %]"   "[% ${foo.bar} %]"
   "[% ${foo.$bar} %]"  "[% ${foo.bar} %]"
   "Text: $foo"         "Text: $foo"
   "Text: ${foo}"       "Text: ${foo}"
   "Text: ${$foo}"      "Text: ${foo}"

=item V2EQUALS

Default 1 in TT syntaxes, defaults to 0 in HTML::Template syntaxes.

If set to 1 then "==" is an alias for "eq" and "!= is an alias for
"ne".

    [% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
    [% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]

    Prints

    0
    1

=item V2PIPE

Restores the behavior of the pipe operator to be compatible with TT2.

With V2PIPE = 1

    [%- BLOCK a %]b is [% b %]
    [% END %]
    [%- PROCESS a b => 237 | repeat(2) %]

    # output of block "a" with b set to 237 is passed to the repeat(2) filter

    b is 237
    b is 237

With V2PIPE = 0 (default)

    [%- BLOCK a %]b is [% b %]
    [% END %]
    [% PROCESS a b => 237 | repeat(2) %]

    # b set to 237 repeated twice, and b passed to block "a"

    b is 237237

=item VARIABLES

A hashref of variables to initialize the template stash with.  These
variables are available for use in any of the executed templates.
See the section on VARIABLES for the types of information that can be passed in.

=item VMETHOD_FUNCTIONS

Defaults to 1.  All scalar virtual methods are available as top level functions as well.
This is not true of TT2.  In CGI::Ex::Template the following are equivalent:

    [% "abc".length %]
    [% length("abc") %]

You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.

=item WRAPPER

Operates similar to the WRAPPER directive.  The option can be given a
single filename, or an arrayref of filenames that will be used to wrap
the processed content.  If an arrayref is passed the filenames are
processed in reverse order, so that the first filename specified will
end up being on the outside (surrounding all other wrappers).

   my $t = CGI::Ex::Template->new(
       WRAPPER => ['my/wrappers/outer.html', 'my/wrappers/inner.html'],
   );

Content generated by the PRE_PROCESS and POST_PROCESS will come before
and after (respectively) the content generated by the WRAPPER
configuration item.

See the WRAPPER direcive for more examples of how wrappers are construted.

=back

=head1 CONFIGURATION (HTML::Template STYLE)

The following HTML::Template and HTML::Template::Expr
configuration variables are supported (in HTML::Template documentation order).
Note: for further discussion you can refer to the HT documentation.
Many of the variables mentioned in the TT CONFIGURATION section
apply here as well.  Unless noted, these items only apply when
using the output method.

Items may be passed in upper or lower case.

These variables should be passed to the "new" constructor.

    my $obj = CGI::Ex::Template->new(
        type   => 'filename',
        source => 'my/template.ht',
        die_on_bad_params => 1,
        loop_context_vars => 1,
        global_vars       => 1
        post_chomp => "=",
        pre_chomp  => "-",
    );

=over 4

=item type

Can be one of filename, filehandle, arrayref, or scalarref.  Indicates what type
of input is in the "source" configuration item.

=item source

Stores where to read the input file.  The type is specified in the "type"
configuration item.

=item filename

Indicates a filename to read the template from.  Same as putting the
filename in the "source" item and setting "type" to "filename".

Must be set to enable caching.

=item filehandle

Should contain an open filehandle to read the template from.  Same as
putting the filehandle in the "source" item and setting "type" to "filehandle".

Will not be cached.

=item arrayref

Should contain an arrayref whose values are the lines of the template.  Same as
putting the arrayref in the "source" item and setting "type" to "arrayref".

Will not be cached.

=item scalarref

Should contain an reference to a scalar that contains the template.  Same as
putting the scalar ref in the "source" item and setting "type" to "scalarref".

Will not be cached.

=item cache

If set to one, then CET will use a global, in-memory document cache
to store compiled templates in between calls.  This is generally only
useful in a mod_perl environment.  The document is checked for a different
modification time at each request.

=item blind_cache

Same as with cache enabled, but will not check if the document has
been modified.

=item file_cache

If set to 1, will cache the compiled document on the file system.  If
true, file_cache_dir must be set.

=item file_cache_dir

The directory where to store cached documents when file_cache is true.
This is similar to the TT compile_dir option.

=item double_file_cache

Uses a combination of file_cache and cache.

=item path

Same as INCLUDE_PATH when using the process method.

=item associate

May be a single CGI object or an arrayref of objects.  The params
from these objects will be added to the params during the
output call.

=item case_sensitive

Allow passed variables set through the param method, or the
associate configuration to be used case sensitively.  Default is
off.  It is highly suggested that this be set to 1.

=item loop_context_vars

Default false.  When true, calls to the loop directive will
create the following variables that give information about the
current iteration of the loop:

   __first__   - True on first iteration only
   __last__    - True on last iteration only
   __inner__   - True on any iteration that isn't first or last
   __odd__     - True on odd iterations
   __counter__ - The iteration count

These variables are also available to LOOPs run under
TT syntax if loop_context_vars is set and if QR_PRIVATE is set to 0.

=item no_includes

Default false.  If true, calls to INCLUDE, PROCESS, WRAPPER and INSERT
will fail.  This option is also available when using the process method.

=item global_vars.

Default true in HTE mode.  Default false in HT.  Allows top level
variables to be used in LOOPs.  When false, only variables defined
in the current LOOP iteration hashref will be available.

=item default_escape

Controls the type of escape used on named variables in TMPL_VAR
directives.  Can be one of HTML, URL, or JS.  The values of
TMPL_VAR directives will be encoded with this type unless
they specify their own type via an ESCAPE attribute.

=back

=head1 UNSUPPORTED HT CONFIGURATION

=over 4

=item die_on_bad_params

CET does not resolve variables until the template is output.

=item force_untaint

=item strict

CET is strict on parsing HT documents.

=item shared_cache, double_cache

CET doesn't have shared caching.  Yet.

=item search_path_on_include

CET will check the full path array on each include.

=item debug items

The HTML::Template style options are included here, but you
can use the TT style DEBUG and DUMP directives to do intropection.

=item max_includes

CET uses TT's recursion protection.

=item filter

CET doesn't offer these.

=back

=head1 UNSUPPORTED TT2 CONFIGURATION

=over 4

=item LOAD_TEMPLATES

CGI::Ex::Template has its own mechanism for loading and storing
compiled templates.  TT would use a Template::Provider that would
return a Template::Document.  The closest thing in CGI::Ex::Template
is the load_parsed_template method.  There is no immediate plan to
support the TT behavior.

=item LOAD_PLUGINS

CGI::Ex::Template uses its own mechanism for loading plugins.  TT
would use a Template::Plugins object to load plugins requested via the
USE directive.  The functionality for doing this in CGI::Ex::Template
is contained in the list_plugins method and the play_USE method.  There
is no immediate plan to support the TT behavior.

Full support is offered for the PLUGINS and LOAD_PERL configuration items.

Also note that CGI::Ex::Template only natively supports the Iterator plugin.
Any of the other plugins requested will need to provided by installing
Template::Toolkit or the appropriate plugin module.

=item LOAD_FILTERS

CGI::Ex::Template uses its own mechanism for loading filters.  TT
would use the Template::Filters object to load filters requested via the
FILTER directive.  The functionality for doing this in CGI::Ex::Template
is contained in the list_filters method and the play_expr method.

Full support is offered for the FILTERS configuration item.

=item TOLERANT

This option is used by the LOAD_TEMPLATES and LOAD_PLUGINS options and
is not applicable in CGI::Ex::Template.

=item SERVICE

CGI::Ex::Template has no concept of service (theoretically the CGI::Ex::Template
is the "service").

=item CONTEXT

CGI::Ex::Template provides its own pseudo context object to plugins,
filters, and perl blocks.  The CGI::Ex::Template model doesn't really
allow for a separate context.  CGI::Ex::Template IS the context.

=item STASH

CGI::Ex::Template manages its own stash of variables.  A pseudo stash
object is available via the pseudo context object for use in plugins,
filters, and perl blocks.

=item PARSER

CGI::Ex::Template has its own built in parser.  The closest similarity is
the parse_tree method.  The output of parse_tree is an optree that is
later run by execute_tree.  CET provides a backend to the Template::Parser::CET
module which can be used to replace the default parser when using
the standard Template::Toolkit library.

=item GRAMMAR

CGI::Ex::Template maintains its own grammar.  The grammar is defined
in the parse_tree method and the callbacks listed in the global
$DIRECTIVES hashref.

=back


=head1 VARIABLE PARSE TREE

CGI::Ex::Template parses templates into an tree of operations (an AST
or abstract syntax tree).  Even variable access is parsed into a tree.
This is done in a manner somewhat similar to the way that TT operates
except that nested variables such as foo.bar|baz contain the '.' or
'|' in between each name level.  Operators are parsed and stored as
part of the variable (it may be more appropriate to say we are parsing
a term or an expression).

The following table shows a variable or expression and the corresponding parsed tree
(this is what the parse_expr method would return).

    one                [ 'one',  0 ]
    one()              [ 'one',  [] ]
    one.two            [ 'one',  0, '.', 'two',  0 ]
    one|two            [ 'one',  0, '|', 'two',  0 ]
    one.$two           [ 'one',  0, '.', ['two', 0 ], 0 ]
    one(two)           [ 'one',  [ ['two', 0] ] ]
    one.${two().three} [ 'one',  0, '.', ['two', [], '.', 'three', 0], 0]
    2.34               2.34
    "one"              "one"
    1 + 2              [ [ undef, '+', 1, 2 ], 0]
    a + b              [ [ undef, '+', ['a', 0], ['b', 0] ], 0 ]
    "one"|length       [ [ undef, '~', "one" ], 0, '|', 'length', 0 ]
    "one $a two"       [ [ undef, '~', 'one ', ['a', 0], ' two' ], 0 ]
    [0, 1, 2]          [ [ undef, '[]', 0, 1, 2 ], 0 ]
    [0, 1, 2].size     [ [ undef, '[]', 0, 1, 2 ], 0, '.', 'size', 0 ]
    ['a', a, $a ]      [ [ undef, '[]', 'a', ['a', 0], [['a', 0], 0] ], 0]
    {a  => 'b'}        [ [ undef, '{}', 'a', 'b' ], 0 ]
    {a  => 'b'}.size   [ [ undef, '{}', 'a', 'b' ], 0, '.', 'size', 0 ]
    {$a => b}          [ [ undef, '{}', ['a', 0], ['b', 0] ], 0 ]
    a * (b + c)        [ [ undef, '*', ['a', 0], [ [undef, '+', ['b', 0], ['c', 0]], 0 ]], 0 ]
    (a + b)            [ [ undef, '+', ['a', 0], ['b', 0] ]], 0 ]
    (a + b) * c        [ [ undef, '*', [ [undef, '+', ['a', 0], ['b', 0] ], 0 ], ['c', 0] ], 0 ]
    a ? b : c          [ [ undef, '?', ['a', 0], ['b', 0], ['c', 0] ], 0 ]
    a || b || c        [ [ undef, '||', ['a', 0], [ [undef, '||', ['b', 0], ['c', 0] ], 0 ] ], 0 ]
    ! a                [ [ undef, '!', ['a', 0] ], 0 ]

Some notes on the parsing.

    Operators are parsed as part of the variable and become part of the variable tree.

    Operators are stored in the variable tree using an operator identity array which
    contains undef as the first value, the operator, and the operator arguments.  This
    allows for quickly descending the parsed variable tree and determining that the next
    node is an operator.

    Parenthesis () can be used at any point in an expression to disambiguate precedence.

    "Variables" that appear to be literal strings or literal numbers
    are returned as the literal (no operator tree).

The following perl can be typed at the command line to view the parsed variable tree:

    perl -e 'use CGI::Ex::Template; print CGI::Ex::Template::dump_parse_expr("foo.bar + 2")."\n"'

Also the following can be included in a template to view the output in a template:

    [% USE cet = CGI::Ex::Template %]
    [%~ cet.dump_parse_expr('foo.bar + 2').replace('\s+', ' ') %]


=head1 SEMI PUBLIC METHODS

The following list of methods are other interesting methods of CET that
may be re-implemented by subclasses of CET.

=over 4

=item C<dump_parse>

This method allows for returning a Data::Dumper dump of a parsed
template.  It is mainly used for testing.

=item C<dump_parse_expr>

This method allows for returning a Data::Dumper dump of a parsed
variable.  It is mainly used for testing.

=item C<exception>

Creates an exception object blessed into the package listed in
$CGI::Ex::Template::PACKAGE_EXCEPTION.

=item C<execute_tree>

Executes a parsed tree (returned from parse_tree)

=item C<play_expr>

Play the parsed expression.  Turns a variable identity array into the
parsed variable.  This method is also responsible for playing
operators and running virtual methods and filters.  The variable
identity array may also contain literal values, or operator identity
arrays.

=item C<include_filename>

Takes a file path, and resolves it into the full filename using
paths from INCLUDE_PATH or INCLUDE_PATHS.

=item C<_insert>

Resolves the file passed, and then returns its contents.

=item C<list_filters>

Dynamically loads the filters list from Template::Filters when a filter
is used that is not natively implemented in CET.

=item C<list_plugins>

Returns an arrayref of modules that are under a base Namespace.

  my @modules = @{ $self->list_plugins({base => 'Template::Plugins'}) }:

=item C<load_parsed_tree>

Given a filename or a string reference will return a parsed document
hash that contains the parsed tree.

  my $doc = $self->load_parsed_tree($file) || $self->throw('undef', "Zero length content");

=item C<parse_args>

Allow for the multitudinous ways that TT parses arguments.  This allows
for positional as well as named arguments.  Named arguments can be separated with a "=" or "=>",
and positional arguments should be separated by " " or ",".  This only returns an array
of parsed variables.   To get the actual values, you must call play_expr on each value.

=item C<parse_tree>

Used by load_parsed_tree.  This is the main grammar engine of the program.  It
uses method in the $DIRECTIVES hashref to parse different DIRECTIVE TYPES.

=item C<parse_expr>

Used to parse a variable, an expression, a literal string, or a number.  It
returns a parsed variable tree.  Samples of parsed variables can be found in the VARIABLE PARSE TREE
section.

=item C<set_variable>

Used to set a variable.  Expects a variable identity array and the value to set.  It
will autovifiy as necessary.

=item C<throw>

Creates an exception object from the arguments and dies.

=item C<undefined_any>

Called during play_expr if a value is returned that is undefined.  This could
be used to magically create variables on the fly.  This is similar to Template::Stash::undefined.
It is suggested that undefined_get be used instead.  Default behavior returns undef.  You
may also pass a coderef via the UNDEFINED_ANY configuration variable.  Also, you can try using
the DEBUG => 'undef', configuration option which will throw an error on undefined variables.

=item C<undefined_get>

Called when a variable is undefined during a GET directive.  This is useful to
see if a value that is about to get inserted into the text is undefined.  undefined_any is a little
too general for most cases.  Also, you may pass a coderef via the UNDEFINED_GET configuration variable.

=back


=head1 OTHER UTILITY METHODS

The following is a brief list of other methods used by CET.  Generally, these
shouldn't be overwritten by subclasses.

=over 4

=item C<apply_precedence>

Allows for parsed operator array to be translated to a tree based
upon operator precedence.

=item C<context>

Used to create a "pseudo" context object that allows for portability
of TT plugins, filters, and perl blocks that need a context object.

=item C<debug_node>

Used to get debug info on a directive if DEBUG_DIRS is set.

=item C<filter_*>

Methods by these names implement filters that are more complex than one liners.

=item C<get_line_number_by_index>

Used to turn string index position into line number

=item C<interpolate_node>

Used for parsing text nodes for dollar variables when interpolate is on.

=item C<parse_*>

Methods by these names are used by parse_tree to parse the template.  These are the grammar.

=item C<play_*>

Methods by these names are used by execute_tree to execute the parsed tree.

=item C<play_operator>

Used to execute any found operators.  The single argument is
an operator identy returned by the parse_expr method (if the expression
contained an operator).  Normally you would just call play_expr
instead and it will call play_operator if the structure
contains an operator.

=item C<_process>

Called by process and the PROCESS, INCLUDE and other directives.

=item C<slurp>

Reads contents of passed filename - throws file exception on error.

=item C<split_paths>

Used to split INCLUDE_PATH or other directives if an arrayref is not passed.

=item C<_vars>

Return a reference to the current stash of variables.  This is currently only used
by the pseudo context object and may disappear at some point.

=item C<vmethod_*>

Methods by these names implement virtual methods that are more complex than oneliners.

=back


=head1 AUTHOR

Paul Seamons <paul at seamons dot com>

=head1 LICENSE

This module may be distributed under the same terms as Perl itself.

=cut