-=head1
+=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'],
);
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
+
+
+ ### 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
the features of TT2 as well as some from TT3. CGI::Ex::Template is a
full-featured implementation of the Template::Toolkit language.
-CGI::Ex::Template (CET hereafter) is smaller, faster, uses less memory
-and less CPU than TT2. However, it is most likely less portable, less
-extendable, and probably has many of the bugs that TT2 has already massaged
-out from years of bug reports and patches from a very active community
-and mailing list. CET does not have a vibrant community behind it. Fixes
-applied to TT2 will take longer to get into CET, should they get in at all.
-An attempt will be made to follow updates made to TT2 to keep the two
-in sync at a language level. There already has been, and it is expected that
-there will continue to be code sharing between the two projects. (Acutally
-I will try and keep applicable fixes in sync with TT).
-
-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.
-
-Note: A clarification on "faster". All templates are going to take
-different amounts of time to process. Different types of DIRECTIVES
-parse and play more quickly than others. The test script
-samples/benchmark/bench_template.pl was used to obtain sample numbers.
-In general the following statements are true:
-
- If you load a new Template object each time and pass a filename, CET
- is around 4 times faster.
-
- If you load a new Template object and pass a string ref, CET
- is around 3.5 times faster.
-
- If you load a new Template object and use CACHE_EXT, CET
- is around 1.5 times faster.
-
- If you use a cached object with a cached in memory template,
- then CET is 50% faster.
-
- If you use Template::Stash::XS with a cached in memory template,
- then CET is about as fast.
-
- Using TT with a compiled-in-memory template is only 33
- faster than CET with a new object compiling each time.
-
-It is pretty hard to beat the speed of XS stash with compiled in
-memory templates. Many systems don't have access to those so
-CET may make more sense. Hopefully as TT is revised, many of the CET
-speed advantages can be incorporated so that the core TT is just as
-fast or faster.
+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
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.
+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.
+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 staring processing. Any errors that results in the
-template being stopped processing will be stored and available via the ->error method.
-
-Process takes three arguments.
+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
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:
$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
- Add WRAPPER config item
+Move module to its own namespace.
- Add ERROR config item
+Cleanup operator API to allow for easier full customization of
+operators.
-=head1 HOW IS CGI::Ex::Template DIFFERENT
+Give better examples of overriding directives, syntax, and operators.
-CET uses the same template syntax and configuration items
-as TT2, but the internals of CET were written from scratch. In
-addition to this, the following is a list of some of the ways that
-configuration and syntax of CET different from that of TT.
+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
-Numerical hash keys work [% a = {1 => 2} %]
+=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 %]
-Quoted hash key interpolation is fine [% a = {"$foo" => 1} %]
+ [% "$foo".length %]
-Multiple ranges in same constructor [% a = [1..10, 21..30] %]
+ [% 123.length %] # = 3
-Constructor types can call virtual methods
+ [% 123.4.length %] # = 5
- [% a = [1..10].reverse %]
+ [% -123.4.length %] # = -5 ("." binds more tightly than "-")
- [% "$foo".length %]
+ [% (a ~ b).length %]
- [% 123.length %] # = 3
+ [% "hi".repeat(3) %] # = hihihi
- [% 123.4.length %] # = 5
+ [% {a => b}.size %] # = 1
- [% -123.4.length %] # = -5 ("." binds more tightly than "-")
+=item
- [% (a ~ b).length %]
+The "${" and "}" variable interpolators can contain expressions,
+not just variables.
- [% "hi".repeat(3) %]
+ [% [0..10].${ 1 + 2 } %] # = 4
- [% {a => b}.size %]
+ [% {ab => 'AB'}.${ 'a' ~ 'b' } %] # = AB
-Reserved names are less reserved
+ [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
+ # = RedBlueRedBlue
- [% GET GET %] # gets the variable named "GET"
+=item
- [% GET $GET %] # gets the variable who's name is stored in "GET"
+You can use regular expression quoting.
-Filters and SCALAR_OPS are interchangeable.
+ [% "foo".match( /(F\w+)/i ).0 %] # = foo
- [% a | length %]
+=item
- [% b . lower %]
+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.
+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
- [% a = {size => "foo"} %][% a.size %] # = foo
+Allows for turning off TT2 "==" behavior. Defaults to 1
+in TT syntaxes and to 0 in HT syntaxes.
- [% a = {size => "foo"} %][% a|size %] # = 1 (size of hash)
+ [% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
+ [% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]
-Pipe "|" and "." can be mixed.
+Prints
- [% "aa" | repeat(2) . length %] # = 4
+ 0
+ 1
-Whitespace is less meaningful.
+=item
- [% 2-1 %] # = 1 (fails in TT)
+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
+ [% 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 variables can be nested.
- [% FOREACH f.b = [1..10] ; f.b ; END %]
+ [% 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.
+Note that nested variables are subject to scoping issues.
+f.b will not be reset to its value before the FOREACH.
-Post operative directives can be nested.
+=item
- [% one IF two IF three %]
+Post operative directives can be nested. (TT3)
- same as
+Andy Wardley calls this side-by-side effect notation.
- [% IF three %][% IF two %][% one %][% END %][% END %]
+ [% one IF two IF three %]
+ same as
- [% a = [[1..3], [5..7]] %][% i FOREACH i = j FOREACH j = a %] # = 123567
+ [% 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.
-CET does not generate Perl code. It generates an "opcode" tree.
+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 uses storable for its compiled templates. If EVAL_PERL is off,
-CET will not eval_string on ANY piece of information.
+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.
-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.
+=item
-There is no stash. 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.
+The DEBUG directive is more limited.
-There is no provider. CET uses the load_parsed_tree method to get and
-cache templates.
+It only understands DEBUG_DIRS (8) and DEBUG_UNDEF (2).
-There is no grammar. CET has its own built in grammar system.
+=item
-There is no VIEW directive.
+CET has better line information
-There are no references. (There was in initial beta tests, but it was decided
-to remove the little used feature).
+When debug dirs is on, directives on different lines separated
+by colons show the line they are on rather than a general line range.
-The DEBUG directive only understands DEBUG_DIRS (8) and DEBUG_UNDEF (2).
+Parse errors actually know what line and character they occured at.
-When debug dirs is on, directives on different lines separated by colons show the line they
-are on rather than a general line range.
+=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">
-There is no ANYCASE configuration item. There was in initial beta tests, but it
-was dropped in favor of consistent parsing syntax.
+=item
-There is no V1DOLLAR configuration item. This is a TT version 1 compatibility item and
-is not available in CET.
+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.
+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.
+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 = (
### pass the variables during object creation (will be available to every process call)
my $cet = CGI::Ex::Template->new(VARIABLES => \%vars);
-=head1 GETTING VARIABLES
+=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 %]
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.0] [% my_list.1 %] [% my_list.-1 %]
[% some_data.c.2 %]
Would print:
A
- 20 21
+ 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() %]
You passed me ().
You passed me ().
You passed me (bar).
- You passed me (1, 2, 3).
+ 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 %]
- [% cet.dump_parse('1 + 2').replace('\s+', ' ') %]
+ [% cet.dump_parse_expr('1 + 2').replace('\s+', ' ') %]
Would print something like:
CGI::Ex::Template=HASH(0x814dc28)
- $VAR1 = [ \[ '+', '1', '2' ], 0 ];
+ $VAR1 = [ [ undef, '+', '1', '2' ], 0 ];
-Each type of data has virtual methods associated with them. Virtual methods
-allow for access to common functions. For the full list of built in virtual
-methods, please see the section titled VIRTUAL METHODS
+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 %]
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} %]
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.
+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 %]
2
val1 val2
-It is possible to set multiple values at the same time.
+It is possible to set multiple values in the same SET directive.
[% SET a = 'A'
b = 'B'
=head1 LITERALS AND CONSTRUCTORS
-The following are the types of literals 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.
+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
[% 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.
-=item Single quoted string.
+ [% 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 a "\n"
+ [% '$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.
-=item Double quoted string.
+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).
+ [% "${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.
-=item Array Constructor.
+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).
- [% [4, 5, 6].size %] Prints 3.
- [% [7, 8, 9].reverse.0 %] Prints 9.
[% 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: virtual methods can only be used on array contructors in CET, not in TT.
+Note: this works in CET and is planned for TT3.
-=item Hash Constructor.
+=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.
- [% hash = {foo => 'bar', c => {}} %] Sets the value of hash.
+ [% 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.
-Note: virtual methods can only be used on hash contructors 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
+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 of SET, and the filename of
-PROCESS, INCLUDE, WRAPPER, and INSERT.
+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
[% (1 + 2) * 3 %] Prints 9
- [% x = 2 %]
+ [% x = 2 %] # assignments don't return anything
+ [% (x = 2) %] Prints 2 # unless they are in parens
[% y = 3 %]
- [% z = x * (y - 1) %] Prints 4
+ [% x * (y - 1) %] Prints 4
=head1 VIRTUAL METHODS
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. In general anywhere a
-virtual method can be used a filter can be used also - and vice versa
-- 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.
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 %] 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 indent
-
- [% item.indent(3) %] Indent that number of spaces.
+=item eval
- [% item.indent("Foo: ") %] Add the string "Foo: " to the beginning of every line.
+ [% 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.
- [% 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') %] Print the string out in the specified format. Each line is
- processed separately.
+ [% 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 %] 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("(\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 remove - but is global and replaces with nothing.
+ [% 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.
+ [% 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.replace("\s+", " ") %] Globally replace all space with
- [% item.replace("foo", "bar", 0) Replace the first instance of foo with bar.
+ [% 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.
+ [% 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 => \&vmethod_split,
+=item split
[% item.split %] Returns an arrayref from the item split on " "
[% 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.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-casified string.
+ [% 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
-=over 4
-
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.
[% 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.
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.
[% 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
[% 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.
=back
-=head1 DIRECTIVES
+=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.
-This section contains the alphabetical list of DIRECTIVES available
-in the TT language. DIRECTIVES are the "functions" and control
-structures that implement the Template Toolkit mini-language. For
-further discussion and examples, please refer to the TT directives
-documentation.
+ [% 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
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
=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).
+
+The output also includes the current file and line number that the
+DUMP directive was called from.
-If the template is being processed in a web request, DUMP will html
-encode the DUMP automatically.
+See the DUMP configuration item for ways to customize and control
+the output available to the DUMP directive.
[% DUMP %] # dumps everything
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>
[% '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
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.
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).
The named tags are (duplicated from TT):
- template => ['[%', '%]'], # default
- metatext => ['%%', '%%'], # Text::MetaText
- star => ['[*', '*]'], # TT alternate
- php => ['<?', '?>'], # PHP
- asp => ['<%', '%>'], # ASP
- mason => ['<%', '>' ], # HTML::Mason
- html => ['<!--', '-->'], # HTML comments
+ 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>
# The LOAD_PERL directive should be set to 1
[% USE cet = CGI::Ex::Template %]
- [%~ cet.dump_parse('2 * 3').replace('\s+', ' ') %]
+ [%~ cet.dump_parse_expr('2 * 3').replace('\s+', ' ') %]
Would print:
- $VAR1 = [ \[ '*', '2', '3' ], 0 ];
+ $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.
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 %]
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 %]
(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
=item C<.>
-Binary. The dot operator. Allows for accessing sub-members, methods, or
+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);
=item C<|>
-Binary. The pipe operator. Similar to the dot operator. Allows for
+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.
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>
-Binary. X raised to the Y power. This isn't available in TT 2.15.
+Right associative binary. X raised to the Y power. This isn't available in TT 2.15.
[% 2 ** 3 %] => 8
=item C<!>
-Unary not. Negation of the value.
+Prefix not. Negation of the value.
-=item C<- unary_minus>
+=item C<->
-Unary minus. Returns the value multiplied by -1. The operator
-"unary_minus" is used internally by CGI::Ex::Template to provide for -
-to be listed in the precedence table twice.
+Prefix minus. Returns the value multiplied by -1.
[% a = 1 ; b = -a ; b %] => -1
=item C<*>
-Binary. Multiplication.
+Left associative binary. Multiplication.
=item C</ div DIV>
-Binary. Division. Note that / is floating point division, but div and
+Left associative binary. Division. Note that / is floating point division, but div and
DIV are integer division.
[% 10 / 4 %] => 2.5
=item C<% mod MOD>
-Binary. Modulus.
+Left associative binary. Modulus.
[% 15 % 8 %] => 7
=item C<+>
-Binary. Addition.
+Left associative binary. Addition.
=item C<->
-Binary. Minus.
+Left associative binary. Minus.
=item C<_ ~>
-Binary. String concatenation.
+Left associative binary. String concatenation.
[% "a" ~ "b" %] => ab
=item C<< < > <= >= >>
-Binary. Numerical comparators.
+Non associative binary. Numerical comparators.
=item C<lt gt le ge>
-Binary. String comparators.
+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.
-=item C<== eq>
+The HTML::Template syntaxes default V2EQUALS to 0 which means
+that it will test for numeric equality just as you would normally
+expect.
-Binary. Equality test. TT chose to use Perl's eq for both operators.
-There is no test for numeric equality.
+In either case - you should always use "eq" when you mean "eq".
+The V2EQUALS will most likely eventually default to 0.
-=item C<!= ne>
+=item C<ne>
-Binary. Non-equality test. TT chose to use Perl's ne for both
-operators. There is no test for numeric non-equality.
+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<&&>
-Multiple arity. And. All values must be true. If all values are true, the last
+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<||>
-Multiple arity. Or. The first true value is returned.
+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<..>
-Binary. Range creator. Returns an arrayref containing the values
+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
=item C<? :>
-Trinary. Can be nested with other ?: pairs.
+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. Sets the left-hand side to the value of the righthand side. In order
+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 --- 1
+ [% a = 1 %] --- [% a %] => --- 1 # is handled by SET
+ [% (a = 1) %] --- [% a %] => 1 --- 1
=item C<not NOT>
-Lower precedence version of the '!' operator.
+Prefix. Lower precedence version of the '!' operator.
=item C<and AND>
-Lower precedence version of the '&&' operator.
+Left associative. Lower precedence version of the '&&' operator.
=item C<or OR>
-Lower precedence version of the '||' operator.
+Right associative. Lower precedence version of the '||' operator.
-=item C<hash>
+=item C<{}>
-Multiple arity. This operator is not used in TT. It is used internally
+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<array>
+=item C<[]>
-Multiple arity. This operator is not used in TT. It is used internally
+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
Hello.
- [%- "Hi." -%]
+ [%= "Hi." =%]
Howdy.
Hello.
- [%- "Hi." -%]
+ [%~ "Hi." ~%]
Howdy.
Hello.Hi.Howdy.
-=head1 CONFIGURATION
+=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 => "-",
- );
+ my $obj = CGI::Ex::Template->new(
+ VARIABLES => \%hash_of_variables,
+ AUTO_RESET => 0,
+ TRIM => 1,
+ POST_CHOMP => "=",
+ PRE_CHOMP => "-",
+ );
=over 4
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.
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
- },
+ 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
Will have the value 42 compiled in.
Constants defined in this way can be chained as in [%
-constant.foo.bar.baz %] but may only interpolate values that are set
-before the compile process begins. This goes one step beyond TT in
-that any variable set in VARIABLES, or PRE_DEFINE, or passed to the
-process method are allowed - they are not in TT. Variables defined in
-the template are not available during the compile process.
-
- GOOD:
-
- CONSTANTS => {
- foo => {
- bar => {baz => 42},
- bim => 57,
- },
- bing => 'baz',
- bang => 'bim',
- },
- VARIABLES => {
- bam => 'bar',
- },
-
- In the template
-
- [% constants.foo.${constants.bang} %]
-
- Will correctly print 57.
-
- GOOD (non-tt behavior)
-
- [% constants.foo.$bam.${constants.bing} %]
-
- CGI::Ex::Template will print 42 because the value of bam is
- known at compile time. TT would print '' because the value of $bam
- is not yet defined in the TT engine.
-
- BAD:
-
- In the template:
-
- [% bam = 'somethingelse' %]
- [% constants.foo.$bam.${constants.bing} %]
-
- Will still print 42 because the value of bam used comes from
- variables defined before the template was compiled. TT will still print ''.
+constant.foo.bar.baz %].
=item CONSTANT_NAMESPACE
=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 ",".
+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.
=item DEFAULT
-The name of a default template file to use if the passed on is not found.
+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
my $str = q{
[% a = "Hello" %]
- 1([% a | filter1 %])
- 2([% a | filter2 %])
- 3([% a | filter3 %])
+ 1 ([% a | filter1 %])
+ 2 ([% a | filter2 %])
+ 3 ([% a | filter3 %])
};
my $obj = CGI::Ex::Template->new(FILTERS => $filters);
Would print:
- (11111)
- (22222)
- (33333)
+ 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
[% 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
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.
Default value is Template::Plugin. The base module namespace
that template plugins will be looked for. See the USE directive
-for more information.
+for more information. May be either a single namespace, or an arrayref
+of namespaces.
=item POST_CHOMP
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.
=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 get_variable.
+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
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.
-=head1 UNSUPPORTED TT CONFIGURATION
+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 ANYCASE
+=item type
-This will not be supported. You will have to use the full case directive names.
-(It was in the beta code but was removed prior to release).
+Can be one of filename, filehandle, arrayref, or scalarref. Indicates what type
+of input is in the "source" configuration item.
-=item WRAPPER
+=item source
-This will be supported - just not done yet.
+Stores where to read the input file. The type is specified in the "type"
+configuration item.
-=item ERROR
+=item filename
-This will be supported - just not done yet.
+Indicates a filename to read the template from. Same as putting the
+filename in the "source" item and setting "type" to "filename".
-=item V1DOLLAR
+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".
-This will not be supported.
+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 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 get_variable method.
+is contained in the list_filters method and the play_expr method.
Full support is offered for the FILTERS configuration item.
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
=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_variable method would return).
+(this is what the parse_expr method would return).
one [ 'one', 0 ]
one() [ 'one', [] ]
one.${two().three} [ 'one', 0, '.', ['two', [], '.', 'three', 0], 0]
2.34 2.34
"one" "one"
- "one"|length [ \"one", 0, '|', 'length', 0 ]
- "one $a two" [ \ [ '~', 'one ', ['a', 0], ' two' ], 0 ]
- [0, 1, 2] [ \ [ 'array', 0, 1, 2 ], 0 ]
- [0, 1, 2].size [ \ [ 'array', 0, 1, 2 ], 0, '.', 'size', 0 ]
- ['a', a, $a ] [ \ [ 'array', 'a', ['a', 0], [['a', 0], 0] ], 0]
- {a => 'b'} [ \ [ 'hash', 'a', 'b' ], 0 ]
- {a => 'b'}.size [ \ [ 'hash', 'a', 'b' ], 0, '.', 'size', 0 ]
- {$a => b} [ \ [ 'hash', ['a', 0], ['b', 0] ], 0 ]
- 1 + 2 [ \ [ '+', 1, 2 ], 0]
- a + b [ \ [ '+', ['a', 0], ['b', 0] ], 0 ]
- a * (b + c) [ \ [ '*', ['a', 0], [ \ ['+', ['b', 0], ['c', 0]], 0 ]], 0 ]
- (a + b) [ \ [ '+', ['a', 0], ['b', 0] ]], 0 ]
- (a + b) * c [ \ [ '*', [ \ [ '+', ['a', 0], ['b', 0] ], 0 ], ['c', 0] ], 0 ]
- a ? b : c [ \ [ '?', ['a', 0], ['b', 0], ['c', 0] ], 0 ]
- a || b || c [ \ [ '||', ['a', 0], [ \ [ '||', ['b', 0], ['c', 0] ], 0 ] ], 0 ]
- ! a [ \ [ '!', ['a', 0] ], 0 ]
+ 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 a reference to the arrayref - which
+ 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.
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("foo.bar + 2")."\n"'
+ 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('foo.bar + 2').replace('\s+', ' ') %]
+ [%~ cet.dump_parse_expr('foo.bar + 2').replace('\s+', ' ') %]
=head1 SEMI PUBLIC METHODS
=item C<dump_parse>
-This method allows for returning a Data::Dumper dump of a parsed variable. It is mainly used for testing.
+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>
Executes a parsed tree (returned from parse_tree)
-=item C<get_variable>
+=item C<play_expr>
-Turns a variable identity array into the parsed variable. This
-method is also responsible for playing operators and running virtual methods
-and filters. The method could more accurately be called play_expression.
+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>
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. Use vivify_args to translate to the actual values.
+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_variable>
+=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
=item C<undefined_any>
-Called during get_variable if a value is returned that is undefined. This could
+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
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.
-=item C<vivify_args>
-
-Turns an arrayref of arg identities parsed by parse_args and turns
-them into the actual values.
-
=back
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>
-
-TT2 Holdover that is used once for binmode setting during a TT2 test.
-
=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 than one line.
+Methods by these names implement filters that are more complex than one liners.
=item C<get_line_number_by_index>
=item C<play_operator>
-Used to execute any found operators
+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>
=item C<vmethod_*>
-Methods by these names implement virtual methods that are more than one line.
-
-=item C<weak_copy>
-
-Used to create a weak reference to self to avoid circular references. (this
-is needed by macros)
+Methods by these names implement virtual methods that are more complex than oneliners.
=back
Paul Seamons <paul at seamons dot com>
+=head1 LICENSE
+
+This module may be distributed under the same terms as Perl itself.
+
=cut
projects / chaz / p5-CGI-Ex / blobdiff