there will continue to be code sharing between the two projects. (Acutally
I will try and keep applicable fixes in sync with TT).
+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.
+
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
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.
+ is around 3.5 times faster.
If you load a new Template object and pass a string ref, CET
- is around 3.5 times faster.
+ is around 3 times faster.
If you load a new Template object and use CACHE_EXT, CET
is around 1.5 times faster.
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.
+ then CET is about as fast. But if you use CGI::Ex::Template::XS,
+ the CETX is faster still (about twice as fast as CET).
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.
+fast or faster. This was last updated at version 2.10 of CET and
+2.18 of TT.
So should you use CGI::Ex::Template ? Well, try it out. It may
give you no visible improvement. Or it could.
[% (a ~ b).length %]
- [% "hi".repeat(3) %]
+ [% "hi".repeat(3) %] # = hihihi
- [% {a => b}.size %]
+ [% {a => b}.size %] # = 1
=item The "${" and "}" variable interpolators can contain expressions,
not just variables.
[% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
# = RedBlueRedBlue
+=item Tags can be nested.
+
+ [% f = "[% (1 + 2) %]" %][% f|eval %] # = 3
+
=item Arrays can be accessed with non-integer numbers.
[% [0..10].${ 2.3 } %] # = 3
| Hash.keys
| List.join(", ") %] # = a, b
-=item Added "as" scalar, list, and hash virtual methods.
+=item Added "fmt" scalar, list, and hash virtual methods.
- [% list.as("%s", ", ") %]
+ [% list.fmt("%s", ", ") %]
- [% hash.as("%s => %s", "\n") %]
+ [% hash.fmt("%s => %s", "\n") %]
=item Whitespace is less meaningful. (TT3)
[% a = 1.2e-20 %]
- [% 123.as('%.3e') %] # = 1.230e+02
+ [% 123.fmt('%.3e') %] # = 1.230e+02
=item Allow for hexidecimal input. (TT3)
[% a = 0xff0000 %][% a %] # = 16711680
- [% a = 0xff2 / 0xd; a.as('%x') %] # = 13a
+ [% a = 0xff2 / 0xd; a.fmt('%x') %] # = 13a
=item FOREACH variables can be nested.
=item CET does not generate Perl code.
-It generates an "opcode" tree.
+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
=item There is no grammar.
-CET has its own built in recursive grammar system.
+CET has its own built-in recursive regex based grammar system.
=item There is no VIEW directive.
-
-=item There are no references.
-
-There was in initial beta tests, but it was decided to remove the little used feature.
-
-It makes it the same as
-
- [% obj.method("foo") %]
-
-This is removed in CET.
-
=item The DEBUG directive is more limited.
It only understands DEBUG_DIRS (8) and DEBUG_UNDEF (2).
=item When debug dirs is on, directives on different lines separated by colons show the line they
are on rather than a general line range.
-=item 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.
-
=back
=head1 VARIABLES
[% 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 (string, array and hash) have virtual methods
associated with them. Virtual methods allow for access to functions
[% 314159e-5 + 0 %] Prints 3.14159.
- [% .0000001.as('%.1e') %] Prints 1.0e-07
+ [% .0000001.fmt('%.1e') %] Prints 1.0e-07
Hexidecimal input is also supported.
[% 0xff + 0 %] Prints 255
- [% 48875.as('%x') %] Prints beeb
+ [% 48875.fmt('%x') %] Prints beeb
=item Single quoted strings.
Note: virtual methods can only be used on literal strings in CET, not in TT.
+You may also embed the current tags in strings (CET only).
+
+ [% '[% 1 + 2 %]' | eval %] Prints "3"
+
=item Double quoted strings.
Returns the string. Variable interpolation happens.
Note: virtual methods can only be used on literal strings in CET, not in TT.
+You may also embed the current tags in strings (CET only).
+
+ [% "[% 1 + 2 %]" | eval %] Prints "3"
+
=item Array Constructs.
[% [1, 2, 3] %] Prints something like ARRAY(0x8309e90).
=item '0'
- [% item = 'foo' %][% item.0 %] Returns self. Allows for scalars to mask as arrays.
-
-=item as
-
- [% item.as('%d') %]
-
-Similar to format. Returns a string formatted with the passed pattern. Default pattern is %s.
+ [% item = 'foo' %][% item.0 %] Returns self. Allows for scalars to mask as arrays (scalars
+ already will, but this allows for more direct access).
=item chunk
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.
+
=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 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.replace("\s+", " ") %] Globally replace all space with
- [% item.replace("foo", "bar", 0) Replace only 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.
=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.
=item size
=over 4
-=item as
+=item fmt
- [% mylist.as('%s', ', ') %]
+ [% 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.
=over 4
-=item as
+=item fmt
- [% myhash.as('%s => %s', "\n") %]
+ [% 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.
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
+ template1 => ['[\[%]%', '%[%\]]'], # allow TT1 style
+
+If custom tags are supplied, by default they are escaped using
+quotemeta. If a third argument is given and is equal to "unquoted",
+then no quoting takes place on the new tags.
+
+ [% TAGS [<] [>] %] matches "[<] tag [>]"
+
+ [% TAGS [<] [>] unquoted %] matches "< tag >"
+
+ [% TAGS ** ** %] matches "** tag **"
+
+ [% TAGS ** ** unquoted %] 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.
=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
=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<->
=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>
-Binary. Equality test. TT chose to use Perl's eq for both operators.
+Non associative binary. Equality test. TT chose to use Perl's eq for both operators.
There is no test for numeric equality.
=item C<!= ne>
-Binary. Non-equality test. TT chose to use Perl's ne for both
+Non associative binary. Non-equality test. TT chose to use Perl's ne for both
operators. There is no test for numeric non-equality.
=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<? :>
-Ternary. 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. Sets the left hand side
+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 was handled by SET
+ [% 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 # is was handled by SET
+ [% 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.
Hello.
- [%- "Hi." -%]
+ [%= "Hi." =%]
Howdy.
Hello.
- [%- "Hi." -%]
+ [%~ "Hi." ~%]
Howdy.
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
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
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
=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 VARIABLES
A hashref of variables to initialize the template stash with. These
=over 4
-=item ANYCASE
-
-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).
-
=item WRAPPER
This will be supported - just not done yet.
This will be supported - just not done yet.
-=item V1DOLLAR
-
-This will not be supported.
-
=item LOAD_TEMPLATES
CGI::Ex::Template has its own mechanism for loading and storing
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.
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 ]
+ "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 ]
+ 1 + 2 [ [ undef, '+', 1, 2 ], 0]
+ a + b [ [ undef, '+', ['a', 0], ['b', 0] ], 0 ]
+ a * (b + c) [ [ undef, '*', ['a', 0], [ [undef, '+', ['b', 0], ['c', 0]], 0 ]], 0 ]
+ (a + b) [ [ undef, '+', ['a', 0], ['b', 0] ]], 0 ]
+ (a + b) * c [ [ undef, '*', [ [undef, '+', ['a', 0], ['b', 0] ], 0 ], ['c', 0] ], 0 ]
+ 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. To get the actual values, you must call get_variable on each value.
+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
=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>
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)
-
=back
projects / chaz / p5-CGI-Ex / blobdiff