]> Dogcows Code - chaz/p5-CGI-Ex/blobdiff - lib/CGI/Ex/Template.pod
CGI::Ex 2.12
[chaz/p5-CGI-Ex] / lib / CGI / Ex / Template.pod
index 52df7af946a9241ea9ef428b52c454792798d179..206dcba50de481df56efca3a6b77f2b064406ca2 100644 (file)
@@ -15,10 +15,15 @@ CGI::Ex::Template - Fast and lightweight TT2/3 template engine
         hash => {a => 'b'},
     };
 
+    # print to STDOUT
     $t->process('my/template.tt', $swap)
         || die $t->error;
 
-    ### Anything in the Template::Toolkit SYNOPSIS would fit here also
+    # process into a variable
+    my $out = '';
+    $t->process('my/template.tt', $swap, \$out);
+
+    ### CET uses the same syntax and configuration as Template::Toolkit
 
 =head1 DESCRIPTION
 
@@ -180,9 +185,7 @@ to Template::Stash::define_vmethod.
 
 =head1 TODO
 
-    Add WRAPPER configuration item (the WRAPPER directive is supported).
-
-    Add ERROR config item
+    Add HTML::Template support
 
 =head1 HOW IS CGI::Ex::Template DIFFERENT
 
@@ -235,6 +238,10 @@ not just variables.
     [% 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
@@ -266,6 +273,19 @@ the virtual method. (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 Virtual Object Namespaces. (TT3)
 
 The Text, List, and Hash types give direct access
@@ -311,6 +331,12 @@ to virtual methods.
 
     [% 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 %]
@@ -373,6 +399,21 @@ 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 CET does not generate Perl code.
 
 It generates an "opcode" tree.  The opcode tree is an arrayref
@@ -393,7 +434,8 @@ 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, and plugins.
+interface for use by some TT filters, eval perl blocks, views,
+and plugins.
 
 =item There is no stash.
 
@@ -408,30 +450,39 @@ perl blocks, and plugins.
 
 CET uses the load_parsed_tree method to get and cache templates.
 
-=item There is no grammar.
+=item There is no parser/grammar.
 
-CET has its own built-in recursive regex based grammar system.
+CET has its own built-in recursive regex based parser and grammar system.
 
-=item There is no VIEW directive.
+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 When debug dirs is on, directives on different lines separated by colons show the line they
-are on rather than a general line range.
+=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 VARIABLES
 
-This section discusses how to use variables and expressions in the TT mini-language.
+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.
+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.
 
     ### some sample variables
     my %vars = (
@@ -458,8 +509,9 @@ a hashref as the second argument to the process method, or by setting the "VARIA
 
 =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.
+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 %]
@@ -471,7 +523,8 @@ Would print when processed:
     1.0
     bar
 
-To access members of a hashref or an arrayref, you can chain together the names using a ".".
+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 %]
@@ -483,8 +536,9 @@ Would print:
     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.
+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() %]
@@ -498,7 +552,8 @@ Would print:
     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.
+If the value of a variable is an object, methods can be called using
+the "." operator.
 
     [% cet %]
 
@@ -526,9 +581,10 @@ Would print:
     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 "}".
+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} %]
@@ -544,8 +600,9 @@ Would print:
     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)
+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' } %]
@@ -559,8 +616,8 @@ Would print:
 
 =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.
+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 %]
@@ -703,6 +760,13 @@ Note: this works in CET and is planned for TT3.
 
 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
@@ -710,8 +774,8 @@ 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.
+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
@@ -738,11 +802,11 @@ 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.
+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.
@@ -758,8 +822,10 @@ object (except for true filters such as eval and redirect).
 
 =item '0'
 
-    [% item = 'foo' %][% item.0 %] Returns self.  Allows for scalars to mask as arrays (scalars
-                                   already will, but this allows for more direct access).
+    [% item = 'foo' %][% item.0 %] Returns foo.
+
+Allows for scalars to mask as arrays (scalars already will, but this
+allows for more direct access).
 
 =item chunk
 
@@ -849,6 +915,12 @@ processed separately.
 
     [% 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.
@@ -887,10 +959,18 @@ This is a filter and is not available via the Text virtual object.
 
     [% 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 size
 
     [% item.size %] Always returns 1.
@@ -903,6 +983,10 @@ This is a filter and is not available via the Text virtual object.
 
     [% 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 stderr
 
     [% item.stderr %] Print the item to the current STDERR handle.
@@ -929,6 +1013,11 @@ This is a filter and is not available via the Text virtual object.
 
     [% 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
@@ -998,10 +1087,14 @@ Default pattern is %s and the default join string is a space.
 
     [% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).
 
-=item random
+=item pick
+
+    [% mylist.pick %] Returns a random item from the list.
+    [% ['a' .. 'z'].pick %]
 
-    [% mylist.random %] Returns a random item from the list.
-    [% ['a' .. 'z'].random %]
+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.
 
@@ -1070,6 +1163,9 @@ Default pattern is "%s\t%s" and the default join string is a newline.
 
     [% 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
@@ -1277,6 +1373,36 @@ 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
+
+The following runtime configuration options may be set:
+
+    DUMP
+
+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
@@ -1298,13 +1424,15 @@ defined or was zero length.
 
 =item C<DUMP>
 
-This is not provided in TT.  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.
+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).
 
-If the template is being processed in a web request, DUMP will html
-encode the DUMP automatically.
+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
 
@@ -1336,7 +1464,8 @@ TODO - enumerate the at least 7 ways to pass and use filters.
 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.
+This is the behavior employed by TT3.  To get the TT2 behavior for a PIPE, use
+the V2PIPE configuration item.
 
 =item C<FINAL>
 
@@ -1505,6 +1634,13 @@ Arguments may also be passed to the template:
 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.
@@ -1512,6 +1648,12 @@ 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.
@@ -1606,6 +1748,13 @@ Arguments may also be passed to the template:
 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).
@@ -1670,19 +1819,26 @@ The named tags are (duplicated from TT):
     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.  If a third argument is given and is equal to "unquoted",
-then no quoting takes place on the new tags.
+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 [<] [>] unquoted %] matches "< tag >"
+    [% TAGS '[<]' '[>]' %]      matches "[<] tag [>]"
+
+    [% TAGS "[<]" "[>]" %]      matches "[<] tag [>]"
+
+    [% TAGS /[<]/ /[>]/ %]      matches "< tag >"
 
     [% TAGS ** ** %]            matches "** tag **"
 
-    [% TAGS ** ** unquoted %]   Throws an exception.
+    [% TAGS /**/ /**/ %]        Throws an exception.
 
 =item C<THROW>
 
@@ -1860,6 +2016,14 @@ 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.
@@ -1904,8 +2068,8 @@ 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 %]
-    My content to be processed.[% a = 2 %]
+    [% WRAPPER foo b = 23 %]
+    My content to be processed ([% b %]).[% a = 2 %]
     [% END %]
 
     [% BLOCK foo %]
@@ -1917,10 +2081,10 @@ WRAPPER tag.
 This would print.
 
     A header (2).
-    My content to be processed.
+    My content to be processed (23).
     A footer (2).
 
-The WRAPPER directive may also be used as a post directive.
+The WRAPPER directive may also be used as a post operative directive.
 
     [% BLOCK baz %]([% content %])[% END -%]
     [% "foobar" WRAPPER baz %]
@@ -1929,6 +2093,17 @@ 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
 
 
@@ -2180,6 +2355,12 @@ 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
 
 
@@ -2380,10 +2561,103 @@ The name of a default template file to use if the passed one is not found.
 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
@@ -2480,6 +2754,16 @@ Is the same as
 
 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.
@@ -2560,6 +2844,14 @@ that are relative to the currently running process.
 
 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 TAG_STYLE
 
 Allow for setting the type of tag delimiters to use for parsing the TT.
@@ -2610,27 +2902,61 @@ following is a basic table of changes invoked by using V1DOLLAR.
    "Text: ${foo}"       "Text: ${foo}"
    "Text: ${$foo}"      "Text: ${foo}"
 
+=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.
 
-=back
+=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'],
+   );
 
-=head1 UNSUPPORTED TT CONFIGURATION
+Content generated by the PRE_PROCESS and POST_PROCESS will come before
+and after (respectively) the content generated by the WRAPPER
+configuration item.
 
-=over 4
+See the WRAPPER direcive for more examples of how wrappers are construted.
 
-=item WRAPPER
+=back
 
-This will be supported - just not done yet.
 
-=item ERROR
+=head1 UNSUPPORTED TT CONFIGURATION
 
-This will be supported - just not done yet.
+=over 4
 
 =item LOAD_TEMPLATES
 
@@ -2689,7 +3015,9 @@ filters, and perl blocks.
 
 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.
+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
 
@@ -2702,12 +3030,13 @@ $DIRECTIVES hashref.
 
 =head1 VARIABLE PARSE TREE
 
-CGI::Ex::Template parses templates into an tree of operations.  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).
+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).
@@ -2721,6 +3050,8 @@ The following table shows a variable or expression and the corresponding parsed
     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 ]
@@ -2729,8 +3060,6 @@ The following table shows a variable or expression and the corresponding parsed
     {a  => 'b'}        [ [ undef, '{}', 'a', 'b' ], 0 ]
     {a  => 'b'}.size   [ [ undef, '{}', 'a', 'b' ], 0, '.', 'size', 0 ]
     {$a => b}          [ [ undef, '{}', ['a', 0], ['b', 0] ], 0 ]
-    1 + 2              [ [ undef, '+', 1, 2 ], 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 ]
@@ -2894,7 +3223,7 @@ 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 than one line.
+Methods by these names implement filters that are more complex than one liners.
 
 =item C<get_line_number_by_index>
 
@@ -2939,7 +3268,7 @@ by the pseudo context object and may disappear at some point.
 
 =item C<vmethod_*>
 
-Methods by these names implement virtual methods that are more than one line.
+Methods by these names implement virtual methods that are more complex than oneliners.
 
 =back
 
@@ -2948,4 +3277,8 @@ Methods by these names implement virtual methods that are more than one line.
 
 Paul Seamons <paul at seamons dot com>
 
+=head1 LICENSE
+
+This module may be distributed under the same terms as Perl itself.
+
 =cut
This page took 0.039348 seconds and 4 git commands to generate.