1Template::Alloy(3) User Contributed Perl Documentation Template::Alloy(3)
2
6 Template::Alloy - TT2/3, HT, HTE, Tmpl, and Velocity Engine
7
9 Template::Toolkit style usage
10 my $t = Template::Alloy->new(
11 INCLUDE_PATH => ['/path/to/templates'],
12 );
13 my $swap = {
15 key1 => 'val1',
16 key2 => 'val2',
17 code => sub { 42 },
18 hash => {a => 'b'},
19 };
20 # print to STDOUT
22 $t->process('my/template.tt', $swap)
23 || die $t->error;
24 # process into a variable
26 my $out = '';
27 $t->process('my/template.tt', $swap, \$out);
28 ### Alloy uses the same syntax and configuration as Template::Toolkit
30 HTML::Template::Expr style usage
32 my $t = Template::Alloy->new(
33 filename => 'my/template.ht',
34 path => ['/path/to/templates'],
35 );
36 my $swap = {
38 key1 => 'val1',
39 key2 => 'val2',
40 code => sub { 42 },
41 hash => {a => 'b'},
42 };
43 $t->param($swap);
45 # print to STDOUT (errors die)
47 $t->output(print_to => \*STDOUT);
48 # process into a variable
50 my $out = $t->output;
51 ### Alloy can also use the same syntax and configuration as HTML::Template
53 Text::Tmpl style usage
55 my $t = Template::Alloy->new;
56 my $swap = {
58 key1 => 'val1',
59 key2 => 'val2',
60 code => sub { 42 },
61 hash => {a => 'b'},
62 };
63 $t->set_delimiters('#[', ']#');
65 $t->set_strip(0);
66 $t->set_values($swap);
67 $t->set_dir('/path/to/templates');
68 my $out = $t->parse_file('my/template.tmpl');
70 my $str = "Foo #[echo $key1]# Bar";
72 my $out = $t->parse_string($str);
73 ### Alloy uses the same syntax and configuration as Text::Tmpl
76 Velocity (VTL) style usage
78 my $t = Template::Alloy->new;
79 my $swap = {
81 key1 => 'val1',
82 key2 => 'val2',
83 code => sub { 42 },
84 hash => {a => 'b'},
85 };
86 my $out = $t->merge('my/template.vtl', $swap);
88 my $str = "#set($foo 1 + 3) ($foo) ($bar) ($!baz)";
90 my $out = $t->merge(\$str, $swap);
91 Javascript style usage (requires Template::Alloy::JS)
93 my $t = Template::Alloy->new;
94 my $swap = {
96 key1 => 'val1',
97 key2 => 'val2',
98 code => sub { 42 },
99 hash => {a => 'b'},
100 };
101 my $out = '';
103 $t->process_js('my/template.jstem', $swap, \$out);
104 my $str = "[% var foo = 1 + 3; write('(' + foo + ') (' + get('key1') + ')'); %]";
106 my $out = '';
107 $t->process_js(\$str, $swap, \$out);
108
110 "An alloy is a homogeneous mixture of two or more elements"
111 (http://en.wikipedia.org/wiki/Alloy).
112 Template::Alloy represents the mixing of features and capabilities from
114 all of the major mini-language based template systems (support for non-
115 mini-language based systems will happen eventually). With
116 Template::Alloy you can use your favorite template interface and syntax
117 and get features from each of the other major template systems. And
118 Template::Alloy is fast - whether your using mod_perl, CGI, or running
119 from the commandline. There is even Template::Alloy::JS for getting a
120 little more speed when that is necessary.
121 Template::Alloy happened by accident (accidentally on purpose). The
123 Template::Alloy (Alloy hereafter) was originally a part of the CGI::Ex
124 suite that performed simple variable interpolation. It used TT2 style
125 variables in TT2 style tags "[% foo.bar %]". That was all the original
126 Template::Alloy did. This was fine and dandy for a couple of years.
127 In winter of 2005-2006 Alloy was revamped to add a few features. One
128 thing led to another and soon Alloy provided for most of the features
129 of TT2 as well as some from TT3. Template::Alloy now provides a full-
130 featured implementation of the Template::Toolkit language.
131 After a move to a new company that was using HTML::Template::Expr and
133 Text::Tmpl templates, support was investigated and interfaces for
134 HTML::Template, HTML::Template::Expr, Text::Tmpl, and Velocity (VTL)
135 were added. All of the various engines offer the same features - each
136 using a different syntax and interface.
137 More recently, the Template::Alloy::JS capabilities were introduced to
139 bring Javascript templates to the server side (along with an increase
140 in speed if ran in persistent environments).
141 Template::Toolkit brought the most to the table. HTML::Template
143 brought the LOOP directive. HTML::Template::Expr brought more vmethods
144 and using vmethods as top level functions. Text::Tmpl brought the
145 COMMENT directive and encouraged speed matching (Text::Tmpl is almost
146 entirely C based and is very fast). The Velocity engine brought
147 AUTO_EVAL and SHOW_UNDEFINED_INTERP.
148 Most of the standard Template::Toolkit documentation covering
150 directives, variables, configuration, plugins, filters, syntax, and
151 vmethods should apply to Alloy just fine (This pod tries to explain
152 everything - but there is too much). See Template::Alloy::TT for a
153 listing of the differences between Alloy and TT.
154 Most of the standard HTML::Template and HTML::Template::Expr
156 documentation covering methods, variables, expressions, and syntax will
157 apply to Alloy just fine as well.
158 Most of the standard Text::Tmpl documentation applies, as does the
160 documentation covering Velocity (VTL).
161 So should you use Template::Alloy ? Well, try it out. It may give you
163 no visible improvement. Or it could.
164
166 Template::Alloy uses a recursive regex based grammar (early versions
167 during the CGI::Ex::Template phase did not). This allows for the
168 embedding of opening and closing tags inside other tags (as in [% a =
169 "[% 1 + 2 %]" ; a|eval %]). The individual methods such as parse_expr
170 and play_expr may be used by external applications to add TT style
171 variable parsing to other applications.
172 The regex parser returns an AST (abstract syntax tree) of the text,
174 directives, variables, and expressions. All of the different template
175 syntax options compile to the same AST format. The AST is composed
176 only of scalars and arrayrefs and is suitable for sending to JavaScript
177 via JSON or sharing with other languages. The parse_tree method is
178 used for returning this AST.
179 Once at the AST stage, there are two modes of operation. Alloy can
181 either operate directly on the AST using the Play role, or it can
182 compile the AST to perl code via the Compile role, and then execute the
183 code. To use the perl code route, you must set the COMPILE_PERL flag
184 to 1. If you are running in a cached-in-memory environment such as
185 mod_perl, this is the fastest option. If you are running in a non-
186 cached-in-memory environment, then using the Play role to run the AST
187 is generally faster. The AST method is also more secure as cached AST
188 won't ever eval any "perl" (assuming PERL blocks are disabled - which
189 is the default).
190
192 Template::Alloy has split out its functionality into discrete roles.
193 In Template::Toolkit, this functionality is split into separate
194 classes. The roles in Template::Alloy simply add on more methods to
195 the main class. When Perl 6 arrives, these roles will be translated
196 into true Roles.
197 The following is a list of roles used by Template::Alloy.
199 Template::Alloy::Compile - Compile-to-perl role
201 Template::Alloy::HTE - HTML::Template::Expr role
202 Template::Alloy::Operator - Operator role
203 Template::Alloy::Parse - Parse-to-AST role
204 Template::Alloy::Play - Play-AST role
205 Template::Alloy::Stream - Stream output role
206 Template::Alloy::Tmpl - Text::Tmpl role
207 Template::Alloy::TT - Template::Toolkit role
208 Template::Alloy::Velocity - Velocity role
209 Template::Alloy::VMethod - Virtual methods role
210 Template::Alloy::JS - Javascript functionality - available separately
212 Template::Alloy automatically loads the roles when they are needed or
214 requested - but not sooner (with the exception of the Operator role and
215 the VMethod role which are always needed and always loaded). This is
216 good for a CGI environment. In mod_perl you may want to preload a role
217 to make the most of shared memory. You may do this by passing either
218 the role name or a method supplied by that role.
219 # import roles necessary for running TT
221 use Template::Alloy qw(Parse Play Compile TT);
222 # import roles based on methods
224 use Template::Alloy qw(parse_tree play_tree compile_tree process);
225 Note: importing roles by method names does not import them into that
227 namespace - it is autoloading the role and methods into the
228 Template::Alloy namespace. To help make this more clear you may use
229 the following syntax as well.
230 # import roles necessary for running TT
232 use Template::Alloy load => qw(Parse Play Compile TT);
233 # import roles based on methods
235 use Template::Alloy load => qw(process parse_tree play_tree compile_tree);
236 # import roles based on methods
238 use Template::Alloy
239 Parse => 1,
240 Play => 1,
241 Compile => 1,
242 TT => 1;
243 Even with all roles loaded Template::Alloy is still relatively small.
245 You can load all of the roles (except the JS role) by passing "all" to
246 the use statement.
247 use Template::Alloy 'all';
249 # or
251 use Template::Alloy load => 'all';
252 # or
254 use Template::Alloy all => 1;
255 As a final option, Template::Alloy also includes the ability to stand-
257 in for other template modules. It is able to do this because it
258 supports the majority of the interface of the other template systems.
259 You can do this in the following way:
260 use Template::Alloy qw(Text::Tmpl HTML::Template);
262 # or
264 use Template::Alloy load => qw(Text::Tmpl HTML::Template);
265 # or
267 use Template::Alloy
268 'Text::Tmpl' => 1,
269 'HTML::Template' => 1;
270 Note that the use statement will die if any of the passed module names
272 are already loaded and not subclasses of Template::Alloy. This will
273 avoid thinking that you are using Template::Alloy when you really
274 aren't. Using the 'all' option won't automatically do this - you must
275 mention the "stood-in" modules by name.
276 The following modules may be "stood-in" for:
278 Template
280 Text::Tmpl
281 HTML::Template
282 HTML::Template::Expr
283 This feature is intended to make using Template::Alloy with existing
285 code easier. Most cases should work just fine. Almost all syntax will
286 just work (except Alloy may make some things work that were previously
287 broken). However Template::Alloy doesn't support 100% of the interface
288 of any of the template systems. If you are using "features-on-the-
289 edge" then you may need to re-write portions of your code that interact
290 with the template system.
291
293 The following section lists most of the publicly available methods.
294 Some less commonly used public methods are listed later in this
295 document.
296 "new"
298 my $obj = Template::Alloy->new({
299 INCLUDE_PATH => ['/my/path/to/content', '/my/path/to/content2'],
300 });
301 Arguments may be passed as a hash or as a hashref. Returns a
303 Template::Alloy object.
304 There are currently no errors during Template::Alloy object
306 creation. If you are using the HTML::Template interface, this is
307 different behavior. The document is not parsed until the output or
308 process methods are called.
309 "process"
311 This is the TT interface for starting processing. Any errors that
312 result in the template processing being stopped will be stored and
313 available via the ->error method.
314 my $t = Template::Alloy->new;
316 $t->process($in, $swap, $out)
317 || die $t->error;
318 Process takes three arguments.
320 The $in argument can be any one of:
322 String containing the filename of the template to be processed.
324 The filename should be relative to INCLUDE_PATH. (See
325 INCLUDE_PATH, ABSOLUTE, and RELATIVE configuration items). In
326 memory caching and file side caching are available for this type.
327 A reference to a scalar containing the contents of the template to be processed.
329 A coderef that will be called to return the contents of the template.
331 An open filehandle that will return the contents of the template when read.
333 The $swap argument should be hashref containing key value pairs
335 that will be available to variables swapped into the template.
336 Values can be hashrefs, hashrefs of hashrefs and so on, arrayrefs,
337 arrayrefs of arrayrefs and so on, coderefs, objects, and simple
338 scalar values such as numbers and strings. See the section on
339 variables.
340 The $out argument can be any one of:
342 undef - meaning to print the completed template to STDOUT.
344 String containing a filename. The completed template will be placed in the file.
346 A reference to a string. The contents will be appended to the scalar reference.
348 A coderef. The coderef will be called with the contents as a single argument.
350 An object that can run the method "print". The contents will be passed as
352 a single argument to print.
353 An arrayref. The contents will be pushed onto the array.
355 An open filehandle. The contents will be printed to the open handle.
357 Additionally - the $out argument can be configured using the OUTPUT
359 configuration item.
360 The process method defaults to using the "cet" syntax which will
362 parse TT3 and most TT2 documents. To parse HT or HTE documents,
363 you must pass the SYNTAX configuration item to the "new" method.
364 All calls to process would then default to HTE syntax.
365 my $obj = Template::Alloy->new(SYNTAX => 'hte');
367 "process_simple"
369 Similar to the process method but with the following restrictions:
370 The $in parameter is limited to a filename or a reference a string
372 containing the contents.
373 The $out parameter may only be a reference to a scalar string that
375 output will be appended to.
376 Additionally, the following configuration variables will be
378 ignored: VARIABLES, PRE_DEFINE, BLOCKS, PRE_PROCESS, PROCESS,
379 POST_PROCESS, AUTO_RESET, OUTPUT.
380 "error"
382 Should something go wrong during a "process" command, the error
383 that occurred can be retrieved via the error method.
384 $obj->process('somefile.html', {a => 'b'}, \$string_ref)
386 || die $obj->error;
387 "output"
389 HTML::Template way to process a template. The output method
390 requires that a filename, filehandle, scalarref, or arrayref
391 argument was passed to the new method. All of the HT calling
392 conventions for new are supported. The key difference is that
393 Alloy will not actually process the template until the output
394 method is called.
395 my $obj = Template::Alloy->new(filename => 'myfile.html');
397 $obj->param(\%swap);
398 print $obj->output;
399 See the HTML::Template documentation for more information.
401 The output method defaults to using the "hte" syntax which will
403 parse HTE and HT documents. To parse TT3 or TT2 documents, you
404 must pass the SYNTAX configuration item to the "new" method. All
405 calls to process would then default to TT3 syntax.
406 my $obj = Template::Alloy->new(SYNTAX => 'tt3');
408 Any errors that occur during the output method will die with the
410 error as the die value.
411 "param"
413 HTML::Template way to get or set variable values that will be used
414 by the output method.
415 my $val = $obj->param('key'); # get one value
417 $obj->param(key => $val); # set one value
419 $obj->param(key => $val, key2 => $val2); # set multiple
421 $obj->param({key => $val, key2 => $val2}); # set multiple
423 See the HTML::Template documentation for more information.
425 Note: Alloy does not support the die_on_bad_params configuration.
427 This is because Alloy does not resolve variable names until the
428 output method is called.
429 "define_vmethod"
431 This method is available for defining extra Virtual methods or
432 filters. This method is similar to
433 Template::Stash::define_vmethod.
434 Template::Alloy->define_vmethod(
436 'text',
437 reverse => sub { my $item = shift; return scalar reverse $item },
438 );
439 "register_function"
441 This is the HTML::Template way of defining text vmethods. It is
442 the same as calling define_vmethod with "text" as the first
443 argument.
444 Template::Alloy->register_function(
446 reverse => sub { my $item = shift; return scalar reverse $item },
447 );
448 "define_directive"
450 This method can be used for adding new directives or overridding
451 existing ones.
452 Template::Alloy->define_directive(
454 MYDIR => {
455 parse_sub => sub {}, # parse additional items in the tag
456 play_sub => sub {
457 my ($self, $ref, $node, $out_ref) = @_;
458 $$out_ref .= "I always say the same thing!";
459 return;
460 },
461 is_block => 1, # is this block like
462 is_postop => 0, # not a post operative directive
463 no_interp => 1, # no interpolation in this block
464 continues => undef, # it doesn't "continue" any other directives
465 },
466 );
467 Now with a template like:
469 my $str = "([% MYDIR %]This is something[% END %])";
471 Template::Alloy->new->process(\$str);
472 You will get:
474 (I always say the same thing!)
476 We'll add more details in later revisions of this document.
478 "define_syntax"
480 This method can be used for adding another syntax to or overriding
481 existing ones in the list of choices available in Alloy. The
482 syntax can be chosen by the SYNTAX configuration item.
483 Template::Alloy->define_syntax(
485 my_uber_syntax => sub {
486 my $self = shift;
487 local $self->{'V2PIPE'} = 0;
488 local $self->{'V2EQUALS'} = 0;
489 local $self->{'PRE_CHOMP'} = 0;
490 local $self->{'POST_CHOMP'} = 0;
491 local $self->{'NO_INCLUDES'} = 0;
492 return $self->parse_tree_tt3(@_);
493 },
494 );
495 The subroutine that is used must return an opcode tree (AST) that
497 can be played by the execute_tree method.
498 "define_operator"
500 This method allows for adding new operators or overriding existing
501 ones.
502 Template::Alloy->define_operator({
504 type => 'right', # can be one of prefix, postfix, right, left, none, ternary, assign
505 precedence => 84, # relative precedence for resolving multiple operators without parens
506 symbols => ['foo', 'FOO'], # any mix of chars can be used for the operators
507 play_sub => sub {
508 my ($one, $two) = @_;
509 return "You've been foo'ed ($one, $two)";
510 },
511 });
512 You can then use it in a template as in the following:
514 my $str = "[% 'ralph' foo 1 + 2 * 3 %]";
516 Template::Alloy->new->process(\$str);
517 You will get:
519 You've been foo'ed (ralph, 7)
521 Future revisions of this document will include more samples. This
523 is an experimental feature and the API will probably change.
524 "dump_parse_tree"
526 This method allows for returning a Data::Dumper dump of a parsed
527 template. It is mainly used for testing.
528 "dump_parse_expr"
530 This method allows for returning a Data::Dumper dump of a parsed
531 variable. It is mainly used for testing.
532 "import"
534 All of the arguments that can be passed to "use" that are listed
535 above in the section dealing with ROLES, can be used with the
536 import method.
537 # import by role
539 Template::Alloy->import(qw(Compile Play Parse TT));
540 # import by method
542 Template::Alloy->import(qw(compile_tree play_tree parse_tree process));
543 # import by "stand-in" class
545 Template::Alloy->import('Text::Tmpl', 'HTML::Template::Expr');
546 As mentioned in the ROLE section - arguments passed to import are
548 not imported into current namespace. Roles and methods are only
549 imported into the Template::Alloy namespace.
550
552 This section discusses how to use variables and expressions in the TT
553 mini-language.
554 A variable is the most simple construct to insert into the TT mini
556 language. A variable name will look for the matching value inside
557 Template::Alloys internal stash of variables which is essentially a
558 hash reference. This stash is initially populated by either passing a
559 hashref as the second argument to the process method, or by setting the
560 "VARIABLES" or "PRE_DEFINE" configuration variables.
561 If you are using either the HT or the HTE syntax, the VAR, IF, UNLESS,
563 LOOP, and INCLUDE directives will accept a NAME attribute which may
564 only be a single level (non-chained) HTML::Template variable name, or
565 they may accept an EXPR attribute which may be any valid TT3 variable
566 or expression.
567 The following are some sample ways to access variables.
569 ### some sample variables
571 my %vars = (
572 one => '1.0',
573 foo => 'bar',
574 vname => 'one',
575 some_code => sub { "You passed me (".join(', ', @_).")" },
576 some_data => {
577 a => 'A',
578 bar => 3234,
579 c => [3, 1, 4, 1, 5, 9],
580 vname => 'one',
581 },
582 my_list => [20 .. 50],
583 cet => Template::Alloy->new,
584 );
585 ### pass the variables into the Alloy process
587 $cet->process($template_name, \%vars)
588 || die $cet->error;
589 ### pass the variables during object creation (will be available to every process call)
591 my $cet = Template::Alloy->new(VARIABLES => \%vars);
592 GETTING VARIABLES
594 Once you have variables defined, they can be used directly in the
595 template by using their name in the stash. Or by using the GET
596 directive.
597 [% foo %]
599 [% one %]
600 [% GET foo %]
601 Would print when processed:
603 bar
605 1.0
606 bar
607 To access members of a hashref or an arrayref, you can chain together
609 the names using a ".".
610 [% some_data.a %]
612 [% my_list.0] [% my_list.1 %] [% my_list.-1 %]
613 [% some_data.c.2 %]
614 Would print:
616 A
618 20 21 50
619 4
620 If the value of a variable is a code reference, it will be called. You
622 can add a set of parenthesis and arguments to pass arguments.
623 Arguments are variables and can be as complex as necessary.
624 [% some_code %]
626 [% some_code() %]
627 [% some_code(foo) %]
628 [% some_code(one, 2, 3) %]
629 Would print:
631 You passed me ().
633 You passed me ().
634 You passed me (bar).
635 You passed me (1.0, 2, 3).
636 If the value of a variable is an object, methods can be called using
638 the "." operator.
639 [% cet %]
641 [% cet.dump_parse_expr('1 + 2').replace('\s+', ' ') %]
643 Would print something like:
645 Template::Alloy=HASH(0x814dc28)
647 $VAR1 = [ [ undef, '+', '1', '2' ], 0 ];
649 Each type of data (string, array and hash) have virtual methods
651 associated with them. Virtual methods allow for access to functions
652 that are commonly used on those types of data. For the full list of
653 built in virtual methods, please see the section titled VIRTUAL METHODS
654 [% foo.length %]
656 [% my_list.size %]
657 [% some_data.c.join(" | ") %]
658 Would print:
660 3
662 31
663 3 | 1 | 4 | 5 | 9
664 It is also possible to "interpolate" variable names using a "$". This
666 allows for storing the name of a variable inside another variable. If
667 a variable name is a little more complex it can be embedded inside of
668 "${" and "}".
669 [% $vname %]
671 [% ${vname} %]
672 [% ${some_data.vname} %]
673 [% some_data.$foo %]
674 [% some_data.${foo} %]
675 Would print:
677 1.0
679 1.0
680 1.0
681 3234
682 3234
683 In Alloy it is also possible to embed any expression (non-directive) in
685 "${" and "}" and it is possible to use non-integers for array access.
686 (This is not available in TT2)
687 [% ['a'..'z'].${ 2.3 } %]
689 [% {ab => 'AB'}.${ 'a' ~ 'b' } %]
690 [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
691 Would print:
693 c
695 AB
696 RedBlueRedBlue
697 SETTING VARIABLES.
699 To define variables during processing, you can use the = operator. In
700 most cases this is the same as using the SET directive.
701 [% a = 234 %][% a %]
703 [% SET b = "Hello" %][% b %]
704 Would print:
706 234
708 Hello
709 It is also possible to create arrayrefs and hashrefs.
711 [% a = [1, 2, 3] %]
713 [% b = {key1 => 'val1', 'key2' => 'val2'} %]
714 [% a.1 %]
716 [% b.key1 %] [% b.key2 %]
717 Would print:
719 2
721 val1 val2
722 It is possible to set multiple values in the same SET directive.
724 [% SET a = 'A'
726 b = 'B'
727 c = 'C' %]
728 [% a %] [% b %] [% c %]
729 Would print:
731 A B C
733 It is also possible to unset variables, or to set members of nested
735 data structures.
736 [% a = 1 %]
738 [% SET a %]
739 [% b.0.c = 37 %]
741 ([% a %])
743 [% b.0.c %]
744 Would print
746 ()
748 37
749
751 The following are the types of literals (numbers and strings) and
752 constructors (hash and array constructs) allowed in Alloy. They can be
753 used as arguments to functions, in place of variables in directives,
754 and in place of variables in expressions. In Alloy it is also possible
755 to call virtual methods on literal values.
756 Integers and Numbers.
758 [% 23423 %] Prints an integer.
759 [% 3.14159 %] Prints a number.
760 [% pi = 3.14159 %] Sets the value of the variable.
761 [% 3.13159.length %] Prints 7 (the string length of the number)
762 Scientific notation is supported.
764 [% 314159e-5 + 0 %] Prints 3.14159.
766 [% .0000001.fmt('%.1e') %] Prints 1.0e-07
768 Hexadecimal input is also supported.
770 [% 0xff + 0 %] Prints 255
772 [% 48875.fmt('%x') %] Prints beeb
774 Single quoted strings.
776 Returns the string. No variable interpolation happens.
777 [% 'foobar' %] Prints "foobar".
779 [% '$foo\n' %] Prints "$foo\\n". # the \\n is a literal "\" and an "n"
780 [% 'That\'s nice' %] Prints "That's nice".
781 [% str = 'A string' %] Sets the value of str.
782 [% 'A string'.split %] Splits the string on ' ' and returns the list.
783 Note: virtual methods can only be used on literal strings in Alloy,
785 not in TT.
786 You may also embed the current tags in strings (Alloy only).
788 [% '[% 1 + 2 %]' | eval %] Prints "3"
790 Double quoted strings.
792 Returns the string. Variable interpolation happens.
793 [% "foobar" %] Prints "foobar".
795 [% "$foo" %] Prints "bar" (assuming the value of foo is bar).
796 [% "${foo}" %] Prints "bar" (assuming the value of foo is bar).
797 [% "foobar\n" %] Prints "foobar\n". # the \n is a newline.
798 [% str = "Hello" %] Sets the value of str.
799 [% "foo".replace('foo','bar') %] Prints "bar".
800 Note: virtual methods can only be used on literal strings in Alloy,
802 not in TT.
803 You may also embed the current tags in strings (Alloy only).
805 [% "[% 1 + 2 %]" | eval %] Prints "3"
807 Array Constructs.
809 [% [1, 2, 3] %] Prints something like ARRAY(0x8309e90).
810 [% array1 = [1 .. 3] %] Sets the value of array1.
811 [% array2 = [foo, 'a', []] %] Sets the value of array2.
812 [% [4, 5, 6].size %] Prints 3.
813 [% [7, 8, 9].reverse.0 %] Prints 9.
814 Note: virtual methods can only be used on array contructs in Alloy,
816 not in TT.
817 Quoted Array Constructs.
819 [% qw/1 2 3/ %] Prints something like ARRAY(0x8309e90).
820 [% array1 = qw{Foo Bar Baz} %] Sets the value of array1.
821 [% qw[4 5 6].size %] Prints 3.
822 [% qw(Red Blue).reverse.0 %] Prints Blue.
823 Note: this works in Alloy and is planned for TT3.
825 Hash Constructs.
827 [% {foo => 'bar'} %] Prints something like HASH(0x8305880)
828 [% hash = {foo => 'bar', c => {}} %] Sets the value of hash.
829 [% {a => 'A', b => 'B'}.size %] Prints 2.
830 [% {'a' => 'A', 'b' => 'B'}.size %] Prints 2.
831 [% name = "Tom" %]
832 [% {Tom => 'You are Tom',
833 Kay => 'You are Kay'}.$name %] Prints You are Tom
834 Note: virtual methods can only be used on hash contructs in Alloy,
836 not in TT.
837 Regex Constructs.
839 [% /foo/ %] Prints (?-xism:foo)
840 [% a = /(foo)/i %][% "FOO".match(a).0 %] Prints FOO
841 Note: this works in Alloy and is planned for TT3.
843
845 Virtual methods (vmethods) are a TT feature that allow for operating on
846 the swapped template variables.
847 This document shows some samples of using vmethods. For a full listing
849 of available virtual methods, see Template::Alloy::VMethod.
850
852 Expressions are one or more variables or literals joined together with
853 operators. An expression can be used anywhere a variable can be used
854 with the exception of the variable name in the SET directive, and the
855 filename of PROCESS, INCLUDE, WRAPPER, and INSERT.
856 For a full listing of operators, see Template::Alloy::Operator.
858 The following section shows some samples of expressions. For a full
860 list of available operators, please see the section titled OPERATORS.
861 [% 1 + 2 %] Prints 3
863 [% 1 + 2 * 3 %] Prints 7
864 [% (1 + 2) * 3 %] Prints 9
865 [% x = 2 %] # assignments don't return anything
867 [% (x = 2) %] Prints 2 # unless they are in parens
868 [% y = 3 %]
869 [% x * (y - 1) %] Prints 4
870
872 This section contains the alphabetical list of DIRECTIVES available in
873 Alloy. DIRECTIVES are the "functions" and control structures that work
874 in the various mini-languages. For further discussion and examples
875 beyond what is listed below, please refer to the TT directives
876 documentation or to the appropriate documentation for the particular
877 directive.
878 The examples given in this section are done using the Template::Toolkit
880 syntax, but can be done in any of the various syntax options. See
881 Template::Alloy::TT, Template::Alloy::HTE, Template::Alloy::Tmpl, and
882 Template::Alloy::Velocity.
883 [% IF 1 %]One[% END %]
885 [% FOREACH a = [1 .. 3] %]
886 a = [% a %]
887 [% END %]
888 [% SET a = 1 %][% SET a = 2 %][% GET a %]
890 In TT multiple directives can be inside the same set of '[%' and '%]'
892 tags as long as they are separated by space or semi-colons (;) (The
893 Alloy version of Tmpl allows multiple also - but none of the other
894 syntax options do). Any block directive that can also be used as a
895 post-operative directive (such as IF, WHILE, FOREACH, UNLESS, FILTER,
896 and WRAPPER) must be separated from preceding directives with a semi-
897 colon if it is being used as a block directive. It is more safe to
898 always use a semi-colon. Note: separating by space is only available
899 in Alloy but is a planned TT3 feature.
900 [% SET a = 1 ; SET a = 2 ; GET a %]
902 [% SET a = 1
903 SET a = 2
904 GET a
905 %]
906 [% GET 1
908 IF 0 # is a post-operative
909 GET 2 %] # prints 2
910 [% GET 1;
912 IF 0 # it is block based
913 GET 2
914 END
915 %] # prints 1
916 The following is the list of directives.
918 "BLOCK"
920 Saves a block of text under a name for later use in PROCESS,
921 INCLUDE, and WRAPPER directives. Blocks may be placed anywhere
922 within the template being processed including after where they are
923 used.
924 [% BLOCK foo %]Some text[% END %]
926 [% PROCESS foo %]
927 Would print
929 Some text
931 [% INCLUDE foo %]
933 [% BLOCK foo %]Some text[% END %]
934 Would print
936 Some text
938 Anonymous BLOCKS can be used for capturing.
940 [% a = BLOCK %]Some text[% END %][% a %]
942 Would print
944 Some text
946 Anonymous BLOCKS can be used with macros.
948 "BREAK"
950 Alias for LAST. Used for exiting FOREACH and WHILE loops.
951 "CALL"
953 Calls the variable (and any underlying coderefs) as in the GET
954 method, but always returns an empty string.
955 "CASE"
957 Used with the SWITCH directive. See the "SWITCH" directive.
958 "CATCH"
960 Used with the TRY directive. See the "TRY" directive.
961 "CLEAR"
963 Clears any of the content currently generated in the innermost
964 block or template. This can be useful when used in conjunction
965 with the TRY statement to clear generated content if an error
966 occurs later.
967 "COMMENT"
969 Will comment out any text found between open and close tags. Note,
970 that the intermediate items are still parsed and END tags must
971 align - but the parsed content will be discarded.
972 [% COMMENT %]
974 This text won't be shown.
975 [% IF 1 %]And this won't either.[% END %]
976 [% END %]
977 "CONFIG"
979 Allow for changing the value of some compile time and runtime
980 configuration options.
981 [% CONFIG
983 ANYCASE => 1
984 PRE_CHOMP => '-'
985 %]
986 The following compile time configuration options may be set:
988 ANYCASE
990 AUTO_EVAL
991 AUTO_FILTER
992 CACHE_STR_REFS
993 ENCODING
994 INTERPOLATE
995 POST_CHOMP
996 PRE_CHOMP
997 SEMICOLONS
998 SHOW_UNDEFINED_INTERP
999 SYNTAX
1000 V1DOLLAR
1001 V2EQUALS
1002 V2PIPE
1003 The following runtime configuration options may be set:
1005 ADD_LOCAL_PATH
1007 CALL_CONTEXT
1008 DUMP
1009 VMETHOD_FUNCTIONS
1010 STRICT (can only be enabled, cannot be disabled)
1011 If non-named parameters as passed, they will show the current
1013 configuration:
1014 [% CONFIG ANYCASE, PRE_CHOMP %]
1016 CONFIG ANYCASE = undef
1018 CONFIG PRE_CHOMP = undef
1019 "DEBUG"
1021 Used to reset the DEBUG_FORMAT configuration variable, or to turn
1022 DEBUG statements on or off. This only has effect if the DEBUG_DIRS
1023 or DEBUG_ALL flags were passed to the DEBUG configuration variable.
1024 [% DEBUG format '($file) (line $line) ($text)' %]
1026 [% DEBUG on %]
1027 [% DEBUG off %]
1028 "DEFAULT"
1030 Similar to SET, but only sets the value if a previous value was not
1031 defined or was zero length.
1032 [% DEFAULT foo = 'bar' %][% foo %] => 'bar'
1034 [% foo = 'baz' %][% DEFAULT foo = 'bar' %][% foo %] => 'baz'
1036 "DUMP"
1038 DUMP inserts a Data::Dumper printout of the variable or expression.
1039 If no argument is passed it will dump the entire contents of the
1040 current variable stash (with private keys removed).
1041 The output also includes the current file and line number that the
1043 DUMP directive was called from.
1044 See the DUMP configuration item for ways to customize and control
1046 the output available to the DUMP directive.
1047 [% DUMP %] # dumps everything
1049 [% DUMP 1 + 2 %]
1051 "ELSE"
1053 Used with the IF directive. See the "IF" directive.
1054 "ELSIF"
1056 Used with the IF directive. See the "IF" directive.
1057 "END"
1059 Used to end a block directive.
1060 "EVAL"
1062 Same as the EVALUATE directive.
1063 "EVALUATE"
1065 Introduced by the Velocity templating language. Parses and
1066 processes the contents of the passed item. This is similar to the
1067 eval filter, but Velocity needs a directive. Named arguments may
1068 be used for re-configuring the parser. Any of the items that can
1069 be passed to the CONFIG directive may be passed here.
1070 [% EVALUATE "[% 1 + 3 %]" %]
1072 [% foo = "bar" %]
1074 [% EVALUATE "<TMPL_VAR foo>" SYNTAX => 'ht' %]
1075 "FILTER"
1077 Used to apply different treatments to blocks of text. It may
1078 operate as a BLOCK directive or as a post operative directive.
1079 Alloy supports all of the filters in Template::Filters. The lines
1080 between scalar virtual methods and filters is blurred (or non-
1081 existent) in Alloy. Anything that is a scalar virtual method may
1082 be used as a FILTER.
1083 TODO - enumerate the at least 7 ways to pass and use filters.
1085 '|' Alias for the FILTER directive. Note that | is similar to the '.'
1087 in Template::Alloy. Therefore a pipe cannot be used directly after
1088 a variable name in some situations (the pipe will act only on that
1089 variable). This is the behavior employed by TT3. To get the TT2
1090 behavior for a PIPE, use the V2PIPE configuration item.
1091 "FINAL"
1093 Used with the TRY directive. See the "TRY" directive.
1094 "FOR"
1096 Alias for FOREACH
1097 "FOREACH"
1099 Allows for iterating over the contents of any arrayref. If the
1100 variable is not an arrayref, it is automatically promoted to one.
1101 [% FOREACH i IN [1 .. 3] %]
1103 The variable i = [% i %]
1104 [%~ END %]
1105 [% a = [1 .. 3] %]
1107 [% FOREACH j IN a %]
1108 The variable j = [% j %]
1109 [%~ END %]
1110 Would print:
1112 The variable i = 1
1114 The variable i = 2
1115 The variable i = 3
1116 The variable j = 1
1118 The variable j = 2
1119 The variable j = 3
1120 You can also use the "=" instead of "IN" or "in".
1122 [% FOREACH i = [1 .. 3] %]
1124 The variable i = [% i %]
1125 [%~ END %]
1126 Same as before.
1128 Setting into a variable is optional.
1130 [% a = [1 .. 3] %]
1132 [% FOREACH a %] Hi [% END %]
1133 Would print:
1135 hi hi hi
1137 If the item being iterated is a hashref and the FOREACH does not
1139 set into a variable, then values of the hashref are copied into the
1140 variable stash.
1141 [% FOREACH [{a => 1}, {a => 2}] %]
1143 Key a = [% a %]
1144 [%~ END %]
1145 Would print:
1147 Key a = 1
1149 Key a = 2
1150 The FOREACH process uses the Template::Alloy::Iterator class to
1152 handle iterations (It is compatible with Template::Iterator).
1153 During the FOREACH loop an object blessed into the iterator class
1154 is stored in the variable "loop".
1155 The loop variable provides the following information during a
1157 FOREACH:
1158 index - the current index
1160 max - the max index of the list
1161 size - the number of items in the list
1162 count - index + 1
1163 number - index + 1
1164 first - true if on the first item
1165 last - true if on the last item
1166 next - return the next item in the list
1167 prev - return the previous item in the list
1168 odd - return 1 if the current count is odd, 0 otherwise
1169 even - return 1 if the current count is even, 0 otherwise
1170 parity - return "odd" if the current count is odd, "even" otherwise
1171 The following:
1173 [% FOREACH [1 .. 3] %] [% loop.count %]/[% loop.size %] [% END %]
1175 Would print:
1177 1/3 2/3 3/3
1179 The iterator is also available using a plugin. This allows for
1181 access to multiple "loop" variables in a nested FOREACH directive.
1182 [%~ USE outer_loop = Iterator(["a", "b"]) %]
1184 [%~ FOREACH i = outer_loop %]
1185 [%~ FOREACH j = ["X", "Y"] %]
1186 [% outer_loop.count %]-[% loop.count %] = ([% i %] and [% j %])
1187 [%~ END %]
1188 [%~ END %]
1189 Would print:
1191 1-1 = (a and X)
1193 1-2 = (a and Y)
1194 2-1 = (b and X)
1195 2-2 = (b and Y)
1196 FOREACH may also be used as a post operative directive.
1198 [% "$i" FOREACH i = [1 .. 5] %] => 12345
1200 "GET"
1202 Return the value of a variable or expression.
1203 [% GET a %]
1205 The GET keyword may be omitted.
1207 [% a %]
1209 [% 7 + 2 - 3 %] => 6
1211 See the section on VARIABLES.
1213 "IF (IF / ELSIF / ELSE)"
1215 Allows for conditional testing. Expects an expression as its only
1216 argument. If the expression is true, the contents of its block are
1217 processed. If false, the processor looks for an ELSIF block. If
1218 an ELSIF's expression is true then it is processed. Finally it
1219 looks for an ELSE block which is processed if none of the IF or
1220 ELSIF's expressions were true.
1221 [% IF a == b %]A equaled B[% END %]
1223 [% IF a == b -%]
1225 A equaled B
1226 [%- ELSIF a == c -%]
1227 A equaled C
1228 [%- ELSE -%]
1229 Couldn't determine that A equaled anything.
1230 [%- END %]
1231 IF may also be used as a post operative directive.
1233 [% 'A equaled B' IF a == b %]
1235 Note: If you are using HTML::Template style documents, the TMPL_IF
1237 tag parses using the limited HTML::Template parsing rules.
1238 However, you may use EXPR="" to embed a TT3 style expression.
1239 "INCLUDE"
1241 Parse the contents of a file or block and insert them. Variables
1242 defined or modifications made to existing variables are discarded
1243 after a template is included.
1244 [% INCLUDE path/to/template.html %]
1246 [% INCLUDE "path/to/template.html" %]
1248 [% file = "path/to/template.html" %]
1250 [% INCLUDE $file %]
1251 [% BLOCK foo %]This is foo[% END %]
1253 [% INCLUDE foo %]
1254 Arguments may also be passed to the template:
1256 [% INCLUDE "path/to/template.html" a = "An arg" b = "Another arg" %]
1258 Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1260 RELATIVE configuration items are set.
1261 Multiple filenames can be passed by separating them with a plus, a
1263 space, or commas (TT2 doesn't support the comma). Any supplied
1264 arguments will be used on all templates.
1265 [% INCLUDE "path/to/template.html",
1267 "path/to/template2.html" a = "An arg" b = "Another arg" %]
1268 On Perl 5.6 on some platforms there may be some issues with the
1270 variable localization. There is no problem on 5.8 and greater.
1271 "INSERT"
1273 Insert the contents of a file without template parsing.
1274 Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1276 RELATIVE configuration items are set.
1277 Multiple filenames can be passed by separating them with a plus, a
1279 space, or commas (TT2 doesn't support the comma).
1280 [% INSERT "path/to/template.html",
1282 "path/to/template2.html" %]
1283 "JS"
1285 Only available if the COMPILE_JS configuration item is true
1286 (default is false). This requires the Template::Alloy::JS module
1287 to be installed.
1288 Allow eval'ing the block of text as javascript. The block will be
1290 parsed and then eval'ed.
1291 [% a = "BimBam" %]
1293 [%~ JS %]
1294 write('The variable a was "' + get('a') + '"');
1295 set('b', "FooBar");
1296 [% END %]
1297 [% b %]
1298 Would print:
1300 The variable a was "BimBam"
1302 FooBar
1303 "LAST"
1305 Used to exit out of a WHILE or FOREACH loop.
1306 "LOOP"
1308 This directive operates similar to the HTML::Template loop
1309 directive. The LOOP directive expects a single variable name.
1310 This variable name should point to an arrayref of hashrefs. The
1311 keys of each hashref will be added to the variable stash when it is
1312 iterated.
1313 [% var a = [{b => 1}, {b => 2}, {b => 3}] %]
1315 [% LOOP a %] ([% b %]) [% END %]
1317 Would print:
1319 (1) (2) (3)
1321 If Alloy is in HT mode and GLOBAL_VARS is false, the contents of
1323 the hashref will be the only items available during the loop
1324 iteration.
1325 If LOOP_CONTEXT_VARS is true, and $QR_PRIVATE is false (default
1327 when called through the output method), then the variables
1328 __first__, __last__,
1329 __inner__, __odd__, and __counter__ will be set. See the
1330 HTML::Template loop_context_vars configuration item for more
1331 information.
1332 "MACRO"
1334 Takes a directive and turns it into a variable that can take
1335 arguments.
1336 [% MACRO foo(i, j) BLOCK %]You passed me [% i %] and [% j %].[% END %]
1338 [%~ foo("a", "b") %]
1340 [% foo(1, 2) %]
1341 Would print:
1343 You passed me a and b.
1345 You passed me 1 and 2.
1346 Another example:
1348 [% MACRO bar(max) FOREACH i = [1 .. max] %]([% i %])[% END %]
1350 [%~ bar(4) %]
1352 Would print:
1354 (1)(2)(3)(4)
1356 Starting with version 1.012 of Template::Alloy there is also a
1358 macro operator.
1359 [% foo = ->(i,j){ "You passed me $i and $j" } %]
1361 [% bar = ->(max){ FOREACH i = [1 .. max]; i ; END } %]
1363 See the Template::Alloy::Operator documentation for more examples.
1365 "META"
1367 Used to define variables that will be available via either the
1368 template or component namespace.
1369 Once defined, they cannot be overwritten.
1371 [% template.foobar %]
1373 [%~ META foobar = 'baz' %]
1374 [%~ META foobar = 'bing' %]
1375 Would print:
1377 baz
1379 "NEXT"
1381 Used to go to the next iteration of a WHILE or FOREACH loop.
1382 "PERL"
1384 Only available if the EVAL_PERL configuration item is true (default
1385 is false).
1386 Allow eval'ing the block of text as perl. The block will be parsed
1388 and then eval'ed.
1389 [% a = "BimBam" %]
1391 [%~ PERL %]
1392 my $a = "[% a %]";
1393 print "The variable \$a was \"$a\"";
1394 $stash->set('b', "FooBar");
1395 [% END %]
1396 [% b %]
1397 Would print:
1399 The variable $a was "BimBam"
1401 FooBar
1402 During execution, anything printed to STDOUT will be inserted into
1404 the template. Also, the $stash and $context variables are set and
1405 are references to objects that mimic the interface provided by
1406 Template::Context and Template::Stash. These are provided for
1407 compatibility only. $self contains the current Template::Alloy
1408 object.
1409 "PROCESS"
1411 Parse the contents of a file or block and insert them. Unlike
1412 INCLUDE, no variable localization happens so variables defined or
1413 modifications made to existing variables remain after the template
1414 is processed.
1415 [% PROCESS path/to/template.html %]
1417 [% PROCESS "path/to/template.html" %]
1419 [% file = "path/to/template.html" %]
1421 [% PROCESS $file %]
1422 [% BLOCK foo %]This is foo[% END %]
1424 [% PROCESS foo %]
1425 Arguments may also be passed to the template:
1427 [% PROCESS "path/to/template.html" a = "An arg" b = "Another arg" %]
1429 Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1431 RELATIVE configuration items are set.
1432 Multiple filenames can be passed by separating them with a plus, a
1434 space, or commas (TT2 doesn't support the comma). Any supplied
1435 arguments will be used on all templates.
1436 [% PROCESS "path/to/template.html",
1438 "path/to/template2.html" a = "An arg" b = "Another arg" %]
1439 "RAWPERL"
1441 Only available if the EVAL_PERL configuration item is true (default
1442 is false). Similar to the PERL directive, but you will need to
1443 append to the $output variable rather than just calling PRINT.
1444 "RETURN"
1446 Used to exit the innermost block or template and continue
1447 processing in the surrounding block or template.
1448 There are two changes from TT2 behavior. First, In Alloy, a RETURN
1450 during a MACRO call will only exit the MACRO. Second, the RETURN
1451 directive takes an optional variable name or expression, if passed,
1452 the MACRO will return this value instead of the normal text from
1453 the MACRO. The process_simple method will also return this value.
1454 You can also use the item, list, and hash return vmethods.
1456 [% RETURN %] # just exits
1458 [% RETURN "foo" %] # return value is foo
1459 [% "foo".return %] # same thing
1460 "SET"
1462 Used to set variables.
1463 [% SET a = 1 %][% a %] => "1"
1465 [% a = 1 %][% a %] => "1"
1466 [% b = 1 %][% SET a = b %][% a %] => "1"
1467 [% a = 1 %][% SET a %][% a %] => ""
1468 [% SET a = [1, 2, 3] %][% a.1 %] => "2"
1469 [% SET a = {b => 'c'} %][% a.b %] => "c"
1470 "STOP"
1472 Used to exit the entire process method (out of all blocks and
1473 templates). No content will be processed beyond this point.
1474 "SWITCH"
1476 Allow for SWITCH and CASE functionality.
1477 [% a = "hi" %]
1479 [% b = "bar" %]
1480 [% SWITCH a %]
1481 [% CASE "foo" %]a was foo
1482 [% CASE b %]a was bar
1483 [% CASE ["hi", "hello"] %]You said hi or hello
1484 [% CASE DEFAULT %]I don't know what you said
1485 [% END %]
1486 Would print:
1488 You said hi or hello
1490 "TAGS"
1492 Change the type of enclosing braces used to delineate template
1493 tags. This remains in effect until the end of the enclosing block
1494 or template or until the next TAGS directive. Either a named set
1495 of tags must be supplied, or two tags themselves must be supplied.
1496 [% TAGS html %]
1498 [% TAGS <!-- --> %]
1500 The named tags are (duplicated from TT):
1502 asp => ['<%', '%>' ], # ASP
1504 default => ['\[%', '%\]' ], # default
1505 html => ['<!--', '-->' ], # HTML comments
1506 mason => ['<%', '>' ], # HTML::Mason
1507 metatext => ['%%', '%%' ], # Text::MetaText
1508 php => ['<\?', '\?>' ], # PHP
1509 star => ['\[\*', '\*\]' ], # TT alternate
1510 template => ['\[%', '%\]' ], # Normal Template Toolkit
1511 template1 => ['[\[%]%', '%[%\]]'], # allow TT1 style
1512 tt2 => ['\[%', '%\]' ], # TT2
1513 If custom tags are supplied, by default they are escaped using
1515 quotemeta. You may also pass explicitly quoted strings, or regular
1516 expressions as arguments as well (if your regex begins with a ', ",
1517 or / you must quote it.
1518 [% TAGS [<] [>] %] matches "[<] tag [>]"
1520 [% TAGS '[<]' '[>]' %] matches "[<] tag [>]"
1522 [% TAGS "[<]" "[>]" %] matches "[<] tag [>]"
1524 [% TAGS /[<]/ /[>]/ %] matches "< tag >"
1526 [% TAGS ** ** %] matches "** tag **"
1528 [% TAGS /**/ /**/ %] Throws an exception.
1530 You should be sure that the start tag does not include grouping
1532 parens or INTERPOLATE will not function properly.
1533 "THROW"
1535 Allows for throwing an exception. If the exception is not caught
1536 via the TRY DIRECTIVE, the template will abort processing of the
1537 directive.
1538 [% THROW mytypes.sometime 'Something happened' arg1 => val1 %]
1540 See the TRY directive for examples of usage.
1542 "TRY"
1544 The TRY block directive will catch exceptions that are thrown while
1545 processing its block (It cannot catch parse errors unless they are
1546 in included files or evaltt'ed strings. The TRY block will then
1547 look for a CATCH block that will be processed. While it is being
1548 processed, the "error" variable will be set with the thrown
1549 exception as the value. After the TRY block - the FINAL block will
1550 be ran whether or not an error was thrown (unless a CATCH block
1551 throws an error).
1552 Note: Parse errors cannot be caught unless they are in an eval
1554 FILTER, or are in a separate template being INCLUDEd or PROCESSed.
1555 [% TRY %]
1557 Nothing bad happened.
1558 [% CATCH %]
1559 Caught the error.
1560 [% FINAL %]
1561 This section runs no matter what happens.
1562 [% END %]
1563 Would print:
1565 Nothing bad happened.
1567 This section runs no matter what happens.
1568 Another example:
1570 [% TRY %]
1572 [% THROW "Something happened" %]
1573 [% CATCH %]
1574 Error: [% error %]
1575 Error.type: [% error.type %]
1576 Error.info: [% error.info %]
1577 [% FINAL %]
1578 This section runs no matter what happens.
1579 [% END %]
1580 Would print:
1582 Error: undef error - Something happened
1584 Error.type: undef
1585 Error.info: Something happened
1586 This section runs no matter what happens.
1587 You can give the error a type and more information including named
1589 arguments. This information replaces the "info" property of the
1590 exception.
1591 [% TRY %]
1593 [% THROW foo.bar "Something happened" "grrrr" foo => 'bar' %]
1594 [% CATCH %]
1595 Error: [% error %]
1596 Error.type: [% error.type %]
1597 Error.info: [% error.info %]
1598 Error.info.0: [% error.info.0 %]
1599 Error.info.1: [% error.info.1 %]
1600 Error.info.args.0: [% error.info.args.0 %]
1601 Error.info.foo: [% error.info.foo %]
1602 [% END %]
1603 Would print something like:
1605 Error: foo.bar error - HASH(0x82a395c)
1607 Error.type: foo.bar
1608 Error.info: HASH(0x82a395c)
1609 Error.info.0: Something happened
1610 Error.info.1: grrrr
1611 Error.info.args.0: Something happened
1612 Error.info.foo: bar
1613 You can also give the CATCH block a type to catch. And you can
1615 nest TRY blocks. If types are specified, Alloy will try and find
1616 the closest matching type. Also, an error object can be re-thrown
1617 using $error as the argument to THROW.
1618 [% TRY %]
1620 [% TRY %]
1621 [% THROW foo.bar "Something happened" %]
1622 [% CATCH bar %]
1623 Caught bar.
1624 [% CATCH DEFAULT %]
1625 Caught default - but re-threw.
1626 [% THROW $error %]
1627 [% END %]
1628 [% CATCH foo %]
1629 Caught foo.
1630 [% CATCH foo.bar %]
1631 Caught foo.bar.
1632 [% CATCH %]
1633 Caught anything else.
1634 [% END %]
1635 Would print:
1637 Caught default - but re-threw.
1639 Caught foo.bar.
1641 "UNLESS"
1643 Same as IF but condition is negated.
1644 [% UNLESS 0 %]hi[% END %] => hi
1646 Can also be a post operative directive.
1648 "USE"
1650 Allows for loading a Template::Toolkit style plugin.
1651 [% USE iter = Iterator(['foo', 'bar']) %]
1653 [%~ iter.get_first %]
1654 [% iter.size %]
1655 Would print:
1657 foo
1659 2
1660 Note that it is possible to send arguments to the new object
1662 constructor. It is also possible to omit the variable name being
1663 assigned. In that case the name of the plugin becomes the
1664 variable.
1665 [% USE Iterator(['foo', 'bar', 'baz']) %]
1667 [%~ Iterator.get_first %]
1668 [% Iterator.size %]
1669 Would print:
1671 foo
1673 3
1674 Plugins that are loaded are looked up for in the namespace listed
1676 in the PLUGIN_BASE directive which defaults to Template::Plugin.
1677 So in the previous example, if Template::Toolkit was installed, the
1678 iter object would loaded by the class Template::Plugin::Iterator.
1679 In Alloy, an effective way to disable plugins is to set the
1680 PLUGIN_BASE to a non-existent base such as "_" (In TT it will still
1681 fall back to look in Template::Plugin).
1682 Note: The iterator plugin will fall back and use
1684 Template::Alloy::Iterator if Template::Toolkit is not installed.
1685 No other plugins come installed with Template::Alloy.
1686 The names of the Plugin being loaded from PLUGIN_BASE are case
1688 insensitive. However, using case insensitive names is bad as it
1689 requires scanning the @INC directories for any module matching the
1690 PLUGIN_BASE and caching the result (OK - not that bad).
1691 If the plugin is not found and the LOAD_PERL directive is set, then
1693 Alloy will try and load a module by that name (note: this type of
1694 lookup is case sensitive and will not scan the @INC dirs for a
1695 matching file).
1696 # The LOAD_PERL directive should be set to 1
1698 [% USE ta = Template::Alloy %]
1699 [%~ ta.dump_parse_expr('2 * 3') %]
1700 Would print:
1702 [[undef, '*', 2, 3], 0];
1704 See the PLUGIN_BASE, and PLUGINS configuration items.
1706 See the documentation for Template::Manual::Plugins.
1708 "VIEW"
1710 Implement a TT style view. For more information, please see the
1711 Template::View documentation. This DIRECTIVE will correctly parse
1712 the arguments and then pass them along to a newly created
1713 Template::View object. It will fail if Template::View can not be
1714 found.
1715 "WHILE"
1717 Will process a block of code while a condition is true.
1718 [% WHILE i < 3 %]
1720 [%~ i = i + 1 %]
1721 i = [% i %]
1722 [%~ END %]
1723 Would print:
1725 i = 1
1727 i = 2
1728 i = 3
1729 You could also do:
1731 [% i = 4 %]
1733 [% WHILE (i = i - 1) %]
1734 i = [% i %]
1735 [%~ END %]
1736 Would print:
1738 i = 3
1740 i = 2
1741 i = 1
1742 Note that (f = f - 1) is a valid expression that returns the value
1744 of the assignment. The parenthesis are not optional.
1745 WHILE has a built in limit of 1000 iterations. This is controlled
1747 by the global variable $WHILE_MAX in Template::Alloy.
1748 WHILE may also be used as a post operative directive.
1750 [% "$i" WHILE (i = i + 1) < 7 %] => 123456
1752 "WRAPPER"
1754 Block directive. Processes contents of its block and then passes
1755 them in the [% content %] variable to the block or filename listed
1756 in the WRAPPER tag.
1757 [% WRAPPER foo b = 23 %]
1759 My content to be processed ([% b %]).[% a = 2 %]
1760 [% END %]
1761 [% BLOCK foo %]
1763 A header ([% a %]).
1764 [% content %]
1765 A footer ([% a %]).
1766 [% END %]
1767 This would print.
1769 A header (2).
1771 My content to be processed (23).
1772 A footer (2).
1773 The WRAPPER directive may also be used as a post operative
1775 directive.
1776 [% BLOCK baz %]([% content %])[% END -%]
1778 [% "foobar" WRAPPER baz %]
1779 Would print
1781 (foobar)');
1783 Multiple filenames can be passed by separating them with a plus, a
1785 space, or commas (TT2 doesn't support the comma). Any supplied
1786 arguments will be used on all templates. Wrappers are processed in
1787 reverse order, so that the first wrapper listed will surround each
1788 subsequent wrapper listed. Variables from inner wrappers are
1789 available to the next wrapper that surrounds it.
1790 [% WRAPPER "path/to/outer.html",
1792 "path/to/inner.html" a = "An arg" b = "Another arg" %]
1793
1795 HTML::Template templates use directives that look similar to the
1796 following:
1797 <TMPL_VAR NAME="foo">
1799 <TMPL_IF NAME="bar">
1801 BAR
1802 </TMPL_IF>
1803 The normal set of HTML::Template directives are TMPL_VAR, TMPL_IF,
1805 TMPL_ELSE, TMPL_UNLESS, TMPL_INCLUDE, and TMPL_LOOP. These tags should
1806 have either a NAME attribute, an EXPR attribute, or a bare variable
1807 name that is used to specify the value to be operated. If a NAME is
1808 specified, it may only be a single level value (as opposed to a TT
1809 chained variable). In the case of the TMPL_INCLUDE directive, the NAME
1810 is the file to be included.
1811 In Alloy, the EXPR attribute can be used with any of these types to
1813 specify TT compatible variable or expression that will be used for the
1814 value.
1815 <TMPL_VAR NAME="foo"> Prints the value contained in foo
1817 <TMPL_VAR foo> Prints the value contained in foo
1818 <TMPL_VAR EXPR="foo"> Prints the value contained in foo
1819 <TMPL_VAR NAME="foo.bar.baz"> Prints the value contained in {'foo.bar.baz'}
1821 <TMPL_VAR EXPR="foo.bar.baz"> Prints the value contained in {foo}->{bar}->{baz}
1822 <TMPL_IF foo> Prints FOO if foo is true
1824 FOO
1825 </TMPL_IF
1826 <TMPL_UNLESS foo> Prints FOO unless foo is true
1828 FOO
1829 </TMPL_UNLESS
1830 <TMPL_INCLUDE NAME="foo.ht"> Includes the template in "foo.ht"
1832 <TMPL_LOOP foo> Iterates on the arrayref foo
1834 <TMPL_VAR name>
1835 </TMPL_LOOP>
1836 Template::Alloy makes all of the other TT3 directives available in
1838 addition to the normal set of HTML::Template directives. For example,
1839 the following is valid in Alloy.
1840 <TMPL_MACRO bar(n) BLOCK>You said <TMPL_VAR n></TMPL_MACRO>
1842 <TMPL_GET bar("hello")>
1843 The TMPL_VAR tag may also include an optional ESCAPE attribute. This
1845 specifies how the value of the tag should be escaped prior to
1846 substituting into the template.
1847 Escape value | Type of escape
1849 ---------------------------------
1850 HTML, 1 | HTML encoding
1851 URL | URL encoding
1852 JS | basic javascript encoding (\n, \r, and \")
1853 NONE, 0 | No encoding (default).
1854 The TMPL_VAR tag may also include an optional DEFAULT attribute that
1856 contains a string that will be used if the variable returns false.
1857 <TMPL_VAR foo DEFAULT="Foo was false">
1859
1861 Chomping refers to the handling of whitespace immediately before and
1862 immediately after template tags. By default, nothing happens to this
1863 whitespace. Modifiers can be placed just inside the opening and just
1864 before the closing tags to control this behavior.
1865 Additionally, the PRE_CHOMP and POST_CHOMP configuration variables can
1867 be set and will globally control all chomping behavior for tags that do
1868 not have their own chomp modifier. PRE_CHOMP and POST_CHOMP can be set
1869 to any of the following values:
1870 none: 0 + Template::Constants::CHOMP_NONE
1872 one: 1 - Template::Constants::CHOMP_ONE
1873 collapse: 2 = Template::Constants::CHOMP_COLLAPSE
1874 greedy: 3 ~ Template::Constants::CHOMP_GREEDY
1875 CHOMP_NONE
1877 Don't do any chomping. The "+" sign is used to indicate
1878 CHOMP_NONE.
1879 Hello.
1881 [%+ "Hi." +%]
1883 Howdy.
1885 Would print:
1887 Hello.
1889 Hi.
1891 Howdy.
1893 CHOMP_ONE (formerly known as CHOMP_ALL)
1895 Delete any whitespace up to the adjacent newline. The "-" is used
1896 to indicate CHOMP_ONE.
1897 Hello.
1899 [%- "Hi." -%]
1901 Howdy.
1903 Would print:
1905 Hello.
1907 Hi.
1908 Howdy.
1909 CHOMP_COLLAPSE
1911 Collapse adjacent whitespace to a single space. The "=" is used to
1912 indicate CHOMP_COLLAPSE.
1913 Hello.
1915 [%= "Hi." =%]
1917 Howdy.
1919 Would print:
1921 Hello. Hi. Howdy.
1923 CHOMP_GREEDY
1925 Remove all adjacent whitespace. The "~" is used to indicate
1926 CHOMP_GREEDY.
1927 Hello.
1929 [%~ "Hi." ~%]
1931 Howdy.
1933 Would print:
1935 Hello.Hi.Howdy.
1937
1939 The following configuration variables are supported (in alphabetical
1940 order). Note: for further discussion you can refer to the TT config
1941 documentation.
1942 Items may be passed in upper or lower case. If lower case names are
1944 passed they will be resolved to uppercase during the "new" method.
1945 All of the variables in this section can be passed to the "new"
1947 constructor.
1948 my $obj = Template::Alloy->new(
1950 VARIABLES => \%hash_of_variables,
1951 AUTO_RESET => 0,
1952 TRIM => 1,
1953 POST_CHOMP => "=",
1954 PRE_CHOMP => "-",
1955 );
1956 ABSOLUTE
1958 Boolean. Default false. Are absolute paths allowed for included
1959 files.
1960 ADD_LOCAL_PATH
1962 If true, allows calls include_filename to temporarily add the
1963 directory of the current template being processed to the
1964 INCLUDE_PATHS arrayref. This allows templates to refer to files in
1965 the local template directory without specifying the local directory
1966 as part of the filename. Default is 0. If set to a negative
1967 value, the current directory will be added to the end of the
1968 current INCLUDE_PATHS.
1969 This property may also be set in the template using the CONFIG
1971 directive.
1972 [% CONFIG ADD_LOCAL_PATH => 1 %]
1974 ANYCASE
1976 Allow directive matching to be case insensitive.
1977 [% get 23 %] prints 23 with ANYCASE => 1
1979 AUTO_RESET
1981 Boolean. Default 1. Clear blocks that were set during the process
1982 method.
1983 AUTO_EVAL
1985 Boolean. Default 0 (default 1 in Velocity syntax). If set to
1986 true, double quoted strings will automatically be passed to the
1987 eval filter. This configuration option may also be passed to the
1988 CONFIG directive.
1989 AUTO_FILTER
1991 Can be the name of any filter. Default undef. Any variable
1992 returned by a GET directive (including implicit GET) will be passed
1993 to the named filter. This configuration option may also be passed
1994 to the CONFIG directive.
1995 # with AUTO_FILTER => 'html'
1997 [% f = "&"; GET f %] prints &
1999 [% f = "&"; f %] prints & (implicit GET)
2000 If a variable already has another filter applied the AUTO_FILTER is
2002 not applied. The "none" scalar virtual method has been added to
2003 allow for using variables without reapplying filters.
2004 # with AUTO_FILTER => 'html'
2006 [% f = "&"; f | none %] prints &
2008 [% f = "&"; g = f; g %] prints &
2009 [% f = "&"; g = f; g | none %] prints & (because g = f is a SET directive)
2010 [% f = "&"; g = GET f; g | none %] prints & (because the actual GET directive was called)
2011 BLOCKS
2013 Only available via when using the process interface.
2014 A hashref of blocks that can be used by the process method.
2016 BLOCKS => {
2018 block_1 => sub { ... }, # coderef that returns a block
2019 block_2 => 'A String', # simple string
2020 },
2021 Note that a Template::Document cannot be supplied as a value (TT
2023 supports this). However, it is possible to supply a value that is
2024 equal to the hashref returned by the load_template method.
2025 CACHE_SIZE
2027 Number of compiled templates to keep in memory. Default undef.
2028 Undefined means to allow all templates to cache. A value of 0 will
2029 force no caching. The cache mechanism will clear templates that
2030 have not been used recently.
2031 CACHE_STR_REFS
2033 Default 1. If set, any string refs will have an MD5 sum taken that
2034 will then be used for caching the document - both in memory and on
2035 the file system (if configured). This will give a significant
2036 speed boost. Note that this affects strings passed to the EVALUATE
2037 directive or eval filters as well. It may be set using the CONFIG
2038 directive.
2039 CALL_CONTEXT (Not in TT)
2041 Can be one of 'item', 'list', or 'smart'. The default type is
2042 'smart'. The CALL_CONTEXT configuration specifies in what Perl
2043 context coderefs and methods used in the processed templates will
2044 be called. TT historically has avoided the distinction of item
2045 (scalar) vs list context. To avoid worrying about this, TT
2046 introduced 'smart' context. The "@()" and "$()" context specifiers
2047 make it easier to use CALL_CONTEXT in some situations.
2048 The following table shows the relationship between the various
2050 contexts:
2051 return values smart context list context item context
2053 ------------- ------------- ------------ ------------
2054 A 'foo' 'foo' ['foo'] 'foo'
2055 B undef undef [undef] undef
2056 C (no return value) undef [] undef
2057 D (7) 7 [7] 7
2058 E (7,8,9) [7,8,9] [7,8,9] 9
2059 F @a = (7) 7 [7] 1
2060 G @a = (7,8,9) [7,8,9] [7,8,9] 3
2061 H ({b=>"c"}) {b=>"c"} [{b=>"c"}] {b=>"c"}
2062 I ([1]) [1] [[1]] [1]
2063 J ([1],[2]) [[1],[2]] [[1],[2]] [2]
2064 K [7,8,9] [7,8,9] [[7,8,9]] [7,8,9]
2065 L (undef, "foo") die "foo" [undef, "foo"] "foo"
2066 M wantarray?1:0 1 [1] 0
2067 Cases F, H, I and M are common sticking points of the smart context
2069 in TT2. Note that list context always returns an arrayref from a
2070 method or function call. Smart context can give confusing results
2071 sometimes, especially the I and J cases. Case L for smart match is
2072 very surprising.
2073 The list and item context provide another feature for method calls.
2075 In smart context, TT will look for a hash key in the object by the
2076 same name as the method, if a method by that name doesn't exist.
2077 In item and list context Alloy will die if a method by that name
2078 cannot be found.
2079 The CALL_CONTEXT configuration item can be passed to new or it may
2081 also be set during runtime using the CONFIG directive. The
2082 following method call would be in list context:
2083 [% CONFIG CALL_CONTEXT => 'list';
2085 results = my_obj.get_results;
2086 CONFIG CALL_CONTEXT => 'smart'
2087 %]
2088 Note that we needed to restore CALL_CONTEXT to the default 'smart'
2090 value. Template::Alloy has added the "@()" (list) and the "$()"
2091 (item) context specifiers. The previous example could be written
2092 as:
2093 [% results = @( my_obj.get_results ) %]
2095 To call that same method in item (scalar) context you would do the
2097 following:
2098 [% results = $( my_obj.get_results ) %]
2100 The "@()" and "$()" operators are based on the Perl 6 counterpart.
2102 COMPILE_DIR
2104 Base directory to store compiled templates. Default undef.
2105 Compiled templates will only be stored if one of COMPILE_DIR and
2106 COMPILE_EXT is set.
2107 If set, the AST of parsed documents will be cached. If
2109 COMPILE_PERL is set, the compiled perl code will also be stored.
2110 COMPILE_EXT
2112 Extension to add to stored compiled template filenames. Default
2113 undef.
2114 If set, the AST of parsed documents will be cached. If
2116 COMPILE_PERL is set, the compiled perl code will also be stored.
2117 COMPILE_JS
2119 Default false.
2120 Requires installation of Template::Alloy::JS. When enabled, the
2122 parsed templates will be translated into Javascript and executed
2123 using the V8 javascript engine. If compile_dir is also set, this
2124 compiled javascript will be cached to disk.
2125 If your templates are short, there is little benefit to using this
2127 other than you can then use the JS directive. If your templates
2128 are long or you are running in a cached environment, this will
2129 speed up your templates.
2130 Certain limitations exist when COMPILE_JS is set, most notably the
2132 USE and VIEW directives are not supported, and method calls on
2133 objects passed to the template do not work (code refs passed in do
2134 work however). These limitations are due to the nature of
2135 JavaScript::V8 bind and Perl/JavaScript OO differences.
2136 COMPILE_PERL
2138 Default false.
2139 If set to 1 or 2, will translate the normal AST into a perl 5 code
2141 document. This document can then be executed directly, cached in
2142 memory, or cached on the file system depending upon the
2143 configuration items set.
2144 If set to 1, a perl code document will always be generated.
2146 If set to 2, a perl code document will only be generated if an AST
2148 has already been cached for the document. This should give a speed
2149 benefit and avoid extra compilation unless the document has been
2150 used more than once.
2151 If Alloy is running in a cached environment such as mod_perl, then
2153 using compile_perl can offer some speed benefit and makes Alloy
2154 faster than Text::Tmpl and as fast as HTML::Template::Compiled (but
2155 Alloy has more features).
2156 If you are not running in a cached environment, such as from
2158 commandline, or from CGI, it is generally faster to only run from
2159 the AST (with COMPILE_PERL => 0).
2160 CONSTANTS
2162 Hashref. Used to define variables that will be "folded" into the
2163 compiled template. Variables defined here cannot be overridden.
2164 CONSTANTS => {my_constant => 42},
2166 A template containing:
2168 [% constants.my_constant %]
2170 Will have the value 42 compiled in.
2172 Constants defined in this way can be chained as in [%
2174 constant.foo.bar.baz %].
2175 CONSTANT_NAMESPACE
2177 Allow for setting the top level of values passed in CONSTANTS.
2178 Default value is 'constants'.
2179 DEBUG
2181 Takes a list of constants |'ed together which enables different
2182 debugging modes. Alternately the lowercase names may be used
2183 (multiple values joined by a ",").
2184 The only supported TT values are:
2186 DEBUG_UNDEF (2) - debug when an undefined value is used (now easier to use STRICT)
2187 DEBUG_DIRS (8) - debug when a directive is used.
2188 DEBUG_ALL (2047) - turn on all debugging.
2189 Either of the following would turn on undef and directive debugging:
2191 DEBUG => 'undef, dirs', # preferred
2193 DEBUG => 2 | 8,
2194 DEBUG => DEBUG_UNDEF | DEBUG_DIRS, # constants from Template::Constants
2195 DEBUG_FORMAT
2197 Change the format of messages inserted when DEBUG has DEBUG_DIRS
2198 set on. This essentially the same thing as setting the format
2199 using the DEBUG directive.
2200 DEFAULT
2202 The name of a default template file to use if the passed one is not
2203 found.
2204 DELIMITER
2206 String to use to split INCLUDE_PATH with. Default is :. It is
2207 more straight forward to just send INCLUDE_PATH an arrayref of
2208 paths.
2209 DUMP
2211 Configures the behavior of the DUMP tag. May be set to 0, a
2212 hashref, or another true value. Default is true.
2213 If set to 0, all DUMP directives will do nothing. This is useful
2215 if you would like to turn off the DUMP directives under some
2216 environments.
2217 IF set to a true value (or undefined) then DUMP directives will
2219 operate.
2220 If set to a hashref, the values of the hash can be used to
2222 configure the operation of the DUMP directives. The following are
2223 the values that can be set in this hash.
2224 EntireStash
2226 Default 1. If set to 0, then the DUMP directive will not print
2227 the entire contents of the stash when a DUMP directive is
2228 called without arguments.
2229 handler
2231 Defaults to an internal coderef. If set to a coderef, the DUMP
2232 directive will pass the arguments to be dumped and expects a
2233 string with the dumped data. This gives complete control over
2234 the dump process.
2235 Note 1: The default handler makes sure that values matching the
2237 private variable regex are not included. If you install your
2238 own handler, you will need to take care of these variables if
2239 you intend for them to not be shown.
2240 Note 2: If you would like the name of the variable to be
2242 dumped, include the string '$VAR1' and the DUMP directive will
2243 interpolate the value. For example, to dump all output as YAML
2244 - you could do the following:
2245 DUMP => {
2247 handler => sub {
2248 require YAML;
2249 return "\$VAR1 =\n".YAML::Dump(shift);
2250 },
2251 }
2252 header
2254 Default 1. Controls whether a header is printed for each DUMP
2255 directive. The header contains the file and line number the
2256 DUMP directive was called from. If set to 0 the headers are
2257 disabled.
2258 html
2260 Defaults to 1 if $ENV{'REQUEST_METHOD'} is set - 0 otherwise.
2261 If set to 1, then the output of the DUMP directive is passed to
2262 the html filter and encased in "pre" tags. If set to 0 no html
2263 encoding takes place.
2264 Sortkeys, Useqq, Ident, Pad, etc
2266 Any of the Data::Dumper configuration items may be passed.
2267 ENCODING
2269 Default undef. If set, and if Perl version is greater than or
2270 equal to 5.7.3 (when Encode.pm was first included), then
2271 Encode::decode will be called every time a template file is
2272 processed and will be passed the value of ENCODING and text from
2273 the template.
2274 This item can also be set using [% CONFIG ENCODING => encoding %]
2276 before calling INCLUDE or PROCESS directives to change encodings on
2277 the fly.
2278 END_TAG
2280 Set a string to use as the closing delimiter for TT. Default is
2281 "%]".
2282 ERROR
2284 Used as a fall back when the processing of a template fails. May
2285 either be a single filename that will be used in all cases, or may
2286 be a hashref of options where the keynames represent error types
2287 that will be handled by the filename in their value. A key named
2288 default will be used if no other matching keyname can be found.
2289 The selection process is similar to that of the TRY/CATCH/THROW
2290 directives (see those directives for more information).
2291 my $t = Template::Alloy->new({
2293 ERROR => 'general/catch_all_errors.html',
2294 });
2295 my $t = Template::Alloy->new({
2297 ERROR => {
2298 default => 'general/catch_all_errors.html',
2299 foo => 'catch_all_general_foo_errors.html',
2300 'foo.bar' => 'catch_foo_bar_errors.html',
2301 },
2302 });
2303 Note that the ERROR handler will only be used for errors during the
2305 processing of the main document. It will not catch errors that
2306 occur in templates found in the PRE_PROCESS, POST_PROCESS, and
2307 WRAPPER configuration items.
2308 ERRORS
2310 Same as the ERROR configuration item. Both may be used
2311 interchangeably.
2312 EVAL_PERL
2314 Boolean. Default false. If set to a true value, PERL and RAWPERL
2315 blocks will be allowed to run. This is a potential security hole,
2316 as arbitrary perl can be included in the template. If
2317 Template::Toolkit is installed, a true EVAL_PERL value also allows
2318 the perl and evalperl filters to be used.
2319 FILTERS
2321 Allow for passing in TT style filters.
2322 my $filters = {
2324 filter1 => sub { my $str = shift; $s =~ s/./1/gs; $s },
2325 filter2 => [sub { my $str = shift; $s =~ s/./2/gs; $s }, 0],
2326 filter3 => [sub { my ($context, @args) = @_; return sub { my $s = shift; $s =~ s/./3/gs; $s } }, 1],
2327 };
2328 my $str = q{
2330 [% a = "Hello" %]
2331 1 ([% a | filter1 %])
2332 2 ([% a | filter2 %])
2333 3 ([% a | filter3 %])
2334 };
2335 my $obj = Template::Alloy->new(FILTERS => $filters);
2337 $obj->process(\$str) || die $obj->error;
2338 Would print:
2340 1 (11111)
2342 2 (22222)
2343 3 (33333)
2344 Filters passed in as an arrayref should contain a coderef and a
2346 value indicating if they are dynamic or static (true meaning
2347 dynamic). The dynamic filters are passed the pseudo context object
2348 and any arguments and should return a coderef that will be called
2349 as the filter. The filter coderef is then passed the string.
2350 GLOBAL_CACHE
2352 Default 0. If true, documents will be cached in
2353 $Template::Alloy::GLOBAL_CACHE. It may also be passed a hashref,
2354 in which case the documents will be cached in the passed hashref.
2355 The TT, Tmpl, and velocity will automatically cache documents in
2357 the object. The HTML::Template interface uses a new object each
2358 time. Setting the HTML::Template's CACHE configuration is the same
2359 as setting GLOBAL_CACHE.
2360 INCLUDE_PATH
2362 A string or an arrayref or coderef that returns an arrayref that
2363 contains directories to look for files included by processed
2364 templates. Defaults to "." (the current directory).
2365 INCLUDE_PATHS
2367 Non-TT item. Same as INCLUDE_PATH but only takes an arrayref. If
2368 not specified then INCLUDE_PATH is turned into an arrayref and
2369 stored in INCLUDE_PATHS. Overrides INCLUDE_PATH.
2370 INTERPOLATE
2372 Boolean. Specifies whether variables in text portions of the
2373 template will be interpolated. For example, the $variable and
2374 ${var.value} would be substituted with the appropriate values from
2375 the variable cache (if INTERPOLATE is on).
2376 [% IF 1 %]The variable $variable had a value ${var.value}[% END %]
2378 LOAD_PERL
2380 Indicates if the USE directive can fall back and try and load a
2381 perl module if the indicated module was not found in the
2382 PLUGIN_BASE path. See the USE directive. This configuration has
2383 no bearing on the COMPILE_PERL directive used to indicate using
2384 compiled perl documents.
2385 MAX_EVAL_RECURSE (Alloy only)
2387 Will use $Template::Alloy::MAX_EVAL_RECURSE if not present.
2388 Default is 50. Prevents runaway on the following:
2389 [% f = "[% f|eval %]" %][% f|eval %]
2391 MAX_MACRO_RECURSE (Alloy only)
2393 Will use $Template::Alloy::MAX_MACRO_RECURSE if not present.
2394 Default is 50. Prevents runaway on the following:
2395 [% MACRO f BLOCK %][% f %][% END %][% f %]
2397 NAMESPACE
2399 No Template::Namespace::Constants support. Hashref of hashrefs
2400 representing constants that will be folded into the template at
2401 compile time.
2402 Template::Alloy->new(NAMESPACE => {constants => {
2404 foo => 'bar',
2405 }});
2406 Is the same as
2408 Template::Alloy->new(CONSTANTS => {
2410 foo => 'bar',
2411 });
2412 Any number of hashes can be added to the NAMESPACE hash.
2414 NEGATIVE_STAT_TTL (Not in TT)
2416 Defaults to STAT_TTL which defaults to $STAT_TTL which defaults to
2417 1.
2418 Similar to STAT_TTL - but represents the time-to-live seconds until
2420 a document that was not found is checked again against the system
2421 for modifications. Setting this number higher will allow for fewer
2422 file system accesses. Setting it to a negative number will allow
2423 for the file system to be checked every hit.
2424 NO_INCLUDES
2426 Default false. If true, calls to INCLUDE, PROCESS, WRAPPER and
2427 INSERT will fail. This option is also available when using the
2428 process method.
2429 OUTPUT
2431 Alternate way of passing in the output location for processed
2432 templates. If process is not passed an output argument, it will
2433 look for this value.
2434 See the process method for a listing of possible values.
2436 OUTPUT_PATH
2438 Base path for files written out via the process method or via the
2439 redirect and file filters. See the redirect virtual method and the
2440 process method for more information.
2441 PLUGINS
2443 A hashref of mappings of plugin modules.
2444 PLUGINS => {
2446 Iterator => 'Template::Plugin::Iterator',
2447 DBI => 'MyDBI',
2448 },
2449 See the USE directive for more information.
2451 PLUGIN_BASE
2453 Default value is Template::Plugin. The base module namespace that
2454 template plugins will be looked for. See the USE directive for
2455 more information. May be either a single namespace, or an arrayref
2456 of namespaces.
2457 POST_CHOMP
2459 Set the type of chomping at the ending of a tag. See the section
2460 on chomping for more information.
2461 POST_PROCESS
2463 Only available via when using the process interface.
2464 A list of templates to be processed and appended to the content
2466 after the main template. During this processing the "template"
2467 namespace will contain the name of the main file being processed.
2468 This is useful for adding a global footer to all templates.
2470 PRE_CHOMP
2472 Set the type of chomping at the beginning of a tag. See the
2473 section on chomping for more information.
2474 PRE_DEFINE
2476 Same as the VARIABLES configuration item.
2477 PRE_PROCESS
2479 Only available via when using the process interface.
2480 A list of templates to be processed before and pre-pended to the
2482 content before the main template. During this processing the
2483 "template" namespace will contain the name of the main file being
2484 processed.
2485 This is useful for adding a global header to all templates.
2487 PROCESS
2489 Only available via when using the process interface.
2490 Specify a file to use as the template rather than the one passed in
2492 to the ->process method.
2493 RECURSION
2495 Boolean. Default false. Indicates that INCLUDED or PROCESSED
2496 files can refer to each other in a circular manner. Be careful
2497 about recursion.
2498 RELATIVE
2500 Boolean. Default false. If true, allows filenames to be specified
2501 that are relative to the currently running process.
2502 SEMICOLONS
2504 Boolean. Default false. If true, then the syntax will require
2505 that semi-colons separate multiple directives in the same tag.
2506 This is useful for keeping the syntax a little more clean as well
2507 as trouble shooting some errors.
2508 SHOW_UNDEFINED_INTERP (Not in TT)
2510 Default false (default true in Velocity). If INTERPOLATE is true,
2511 interpolated dollar variables that return undef will be removed.
2512 With SHOW_UNDEFINED_INTERP set, undef values will leave the
2513 variable there.
2514 [% CONFIG INTERPOLATE => 1 %]
2516 [% SET foo = 1 %][% SET bar %]
2517 ($foo)($bar) ($!foo)($!bar)
2518 Would print:
2520 (1)() (1)()
2522 But the following:
2524 [% CONFIG INTERPOLATE => 1, SHOW_UNDEFINED_INTERP => 1 %]
2526 [% SET foo = 1 %][% SET bar %]
2527 ($foo)($bar) ($!foo)($!bar)
2528 Would print:
2530 (1)($bar) (1)()
2532 Note that you can use an exclamation point directly after the
2534 dollar to make the variable silent. This is similar to how
2535 Velocity works.
2536 START_TAG
2538 Set a string or regular expression to use as the opening delimiter
2539 for TT. Default is "[%". You should be sure that the tag does not
2540 include grouping parens or INTERPOLATE will not function properly.
2541 STASH
2543 Template::Alloy manages its own stash of variables. You can pass a
2544 Template::Stash or Template::Stash::XS object, but Template::Alloy
2545 will copy all of values out of the object into its own stash.
2546 Template::Alloy won't use any of the methods of the passed STASH
2547 object. The STASH option is only available when using the process
2548 method.
2549 STAT_TTL
2551 Defaults to $STAT_TTL which defaults to 1. Represents time-to-live
2552 seconds until a cached in memory document is compared to the file
2553 system for modifications. Setting this number higher will allow
2554 for fewer file system accesses. Setting it to a negative number
2555 will allow for the file system to be checked every hit.
2556 STREAM
2558 Defaults to false. If set to true, generated template content will
2559 be printed to the currently selected filehandle (default is STDOUT)
2560 as soon as it is ready - there will be no buffering of the output.
2561 The Stream role uses the Play role's directives
2563 (non-compiled_perl).
2564 All directives and configuration work, except for the following
2566 exceptions:
2567 CLEAR directive
2569 Because the output is not buffered - the CLEAR directive would
2570 have no effect. The CLEAR directive will throw an error when
2571 STREAM is on.
2572 TRIM configuration
2574 Because the output is not buffered - trim operations cannot be
2575 played on the output buffers.
2576 WRAPPER configuration/directive
2578 The WRAPPER configuration and directive items effectively turn
2579 off STREAM since the WRAPPERS are generated in reverse order
2580 and because the content is inserted into the middle of the
2581 WRAPPERS. WRAPPERS will still work, they just won't stream.
2582 VARIOUS errors
2584 Because the template is streaming, items that cause errors my
2585 result in partially printed pages - since the error would occur
2586 part way through the print.
2587 All output is printed directly to the currently selected filehandle
2589 (defaults to STDOUT) via the CORE::print function. Any output
2590 parameter passed to process or process_simple will be ignored.
2591 If you would like the output to go to another handle, you will need
2593 to select that handle, process the template, and re-select STDOUT.
2594 STRICT
2596 Defaults to false. If set to true, any undefined variable that is
2597 encountered will cause the processing of the template to abort.
2598 This can be caught with a TRY block. This can be useful for making
2599 sure that the template only attempts to use variables that were
2600 correctly initialized similar in spirit to Perl's "use strict."
2601 When this occurs the strict_throw method is called.
2603 See the STRICT_THROW configuration for additional options.
2605 Similar functionality could be implemented using UNDEFINED_ANY.
2607 The STRICT configuration item can be passed to new or it may also
2609 be set during runtime using the CONFIG directive. Once set though
2610 it cannot be disabled for the duration of the current template and
2611 sub components. For example you could call [% CONFIG STRICT => 1
2612 %] in header.tt and strict mode would be enabled for the header.tt
2613 and any sub templates processed by header.tt.
2614 STRICT_THROW (not in TT)
2616 Default undef. Can be set to a subroutine which will be called
2617 when STRICT is set and an undefined variable is processed. It will
2618 be passed the error type, error message, and a hashref of template
2619 information containing the current component being processed, the
2620 current outer template being processed, the identity reference for
2621 the variable, and the stringified name of the identity. This
2622 override can be used for filtering allowable elements.
2623 my $ta = Template::Alloy->new({
2625 STRICT => 1,
2626 STRICT_THROW => sub {
2627 my ($ta, $err_type, $msg, $args) = @_;
2628 return if $args->{'component'} eq 'header.tt'
2630 && $args->{'template'} eq 'main.html'
2631 && $args->{'name'} eq 'foo.bar(1)'; # stringified identity name
2632 $ta->throw($err_type, $msg); # all other undefined variables die
2634 },
2635 });
2636 SYNTAX (not in TT)
2638 Defaults to "cet". Indicates the syntax that will be used for
2639 parsing included templates or eval'ed strings. You can use the
2640 CONFIG directive to change the SYNTAX on the fly (it will not
2641 affect the syntax of the document currently being parsed).
2642 The syntax may be passed in upper or lower case.
2644 The available choices are:
2646 alloy - Template::Alloy style - the same as TT3
2648 tt3 - Template::Toolkit ver3 - same as Alloy
2649 tt2 - Template::Toolkit ver2 - almost the same as TT3
2650 tt1 - Template::Toolkit ver1 - almost the same as TT2
2651 ht - HTML::Template - same as HTML::Template::Expr without EXPR
2652 hte - HTML::Template::Expr
2653 js - JavaScript style - requires compile_js to be set.
2654 jsr - JavaScript Raw style - requires compile_js to be set.
2655 Passing in a different syntax allows for the process method to use
2657 a non-TT syntax and for the output method to use a non-HT syntax.
2658 The following is a sample of HTML::Template interface usage parsing
2660 a Template::Toolkit style document.
2661 my $obj = Template::Alloy->new(filename => 'my/template.tt'
2663 syntax => 'cet');
2664 $obj->param(\%swap);
2665 print $obj->output;
2666 The following is a sample of Template::Toolkit interface usage
2668 parsing a HTML::Template::Expr style document.
2669 my $obj = Template::Alloy->new(SYNTAX => 'hte');
2671 $obj->process('my/template.ht', \%swap);
2672 You can use the define_syntax method to add another custom syntax
2674 to the list of available options.
2675 TAG_STYLE
2677 Allow for setting the type of tag delimiters to use for parsing the
2678 TT. See the TAGS directive for a listing of the available types.
2679 TRIM
2681 Remove leading and trailing whitespace from blocks and templates.
2682 This operation is performed after all enclosed template tags have
2683 been executed.
2684 UNDEFINED_ANY
2686 This is not a TT configuration option. This option expects to be a
2687 code ref that will be called if a variable is undefined during a
2688 call to play_expr. It is passed the variable identity array as a
2689 single argument. This is most similar to the "undefined" method of
2690 Template::Stash. It allows for the "auto-defining" of a variable
2691 for use in the template. It is suggested that UNDEFINED_GET be
2692 used instead as UNDEFINED_ANY is a little to general in defining
2693 variables.
2694 You can also sub class the module and override the undefined_any
2696 method.
2697 UNDEFINED_GET
2699 This is not a TT configuration option. This option expects to be a
2700 code ref that will be called if a variable is undefined during a
2701 call to GET. It is passed the variable identity array as a single
2702 argument. This is more useful than UNDEFINED_ANY in that it is
2703 only called during a GET directive rather than in embedded
2704 expressions (such as [% a || b || c %]).
2705 You can also sub class the module and override the undefined_get
2707 method.
2708 V1DOLLAR
2710 This allows for some compatibility with TT1 templates. The only
2711 real behavior change is that [% $foo %] becomes the same as [% foo
2712 %]. The following is a basic table of changes invoked by using
2713 V1DOLLAR.
2714 With V1DOLLAR Equivalent Without V1DOLLAR (Normal default)
2716 "[% foo %]" "[% foo %]"
2717 "[% $foo %]" "[% foo %]"
2718 "[% ${foo} %]" "[% ${foo} %]"
2719 "[% foo.$bar %]" "[% foo.bar %]"
2720 "[% ${foo.bar} %]" "[% ${foo.bar} %]"
2721 "[% ${foo.$bar} %]" "[% ${foo.bar} %]"
2722 "Text: $foo" "Text: $foo"
2723 "Text: ${foo}" "Text: ${foo}"
2724 "Text: ${$foo}" "Text: ${foo}"
2725 V2EQUALS
2727 Default 1 in the TT syntax, defaults to 0 in the HTML::Template
2728 syntax.
2729 If set to 1 then "==" is an alias for "eq" and "!= is an alias for
2731 "ne".
2732 [% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
2734 [% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]
2735 Prints
2737 0
2739 1
2740 V2PIPE
2742 Restores the behavior of the pipe operator to be compatible with
2743 TT2.
2744 With V2PIPE = 1
2746 [%- BLOCK a %]b is [% b %]
2748 [% END %]
2749 [%- PROCESS a b => 237 | repeat(2) %]
2750 # output of block "a" with b set to 237 is passed to the repeat(2) filter
2752 b is 237
2754 b is 237
2755 With V2PIPE = 0 (default)
2757 [%- BLOCK a %]b is [% b %]
2759 [% END %]
2760 [% PROCESS a b => 237 | repeat(2) %]
2761 # b set to 237 repeated twice, and b passed to block "a"
2763 b is 237237
2765 VARIABLES
2767 A hashref of variables to initialize the template stash with.
2768 These variables are available for use in any of the executed
2769 templates. See the section on VARIABLES for the types of
2770 information that can be passed in.
2771 VMETHOD_FUNCTIONS
2773 Defaults to 1. All scalar virtual methods are available as top
2774 level functions as well. This is not true of TT2. In
2775 Template::Alloy the following are equivalent:
2776 [% "abc".length %]
2778 [% length("abc") %]
2779 You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.
2781 WRAPPER
2783 Only available via when using the process interface.
2784 Operates similar to the WRAPPER directive. The option can be given
2786 a single filename, or an arrayref of filenames that will be used to
2787 wrap the processed content. If an arrayref is passed the filenames
2788 are processed in reverse order, so that the first filename
2789 specified will end up being on the outside (surrounding all other
2790 wrappers).
2791 my $t = Template::Alloy->new(
2793 WRAPPER => ['my/wrappers/outer.html', 'my/wrappers/inner.html'],
2794 );
2795 Content generated by the PRE_PROCESS and POST_PROCESS will come
2797 before and after (respectively) the content generated by the
2798 WRAPPER configuration item.
2799 See the WRAPPER directive for more examples of how wrappers are
2801 constructed.
2802
2804 The following HTML::Template and HTML::Template::Expr configuration
2805 variables are supported (in HTML::Template documentation order). Note:
2806 for further discussion you can refer to the HT documentation. Many of
2807 the variables mentioned in the TT CONFIGURATION section apply here as
2808 well. Unless noted, these items only apply when using the output
2809 method.
2810 Items may be passed in upper or lower case. All passed items are
2812 resolved to upper case.
2813 These variables should be passed to the "new" constructor.
2815 my $obj = Template::Alloy->new(
2817 type => 'filename',
2818 source => 'my/template.ht',
2819 die_on_bad_params => 1,
2820 loop_context_vars => 1,
2821 global_vars => 1
2822 post_chomp => "=",
2823 pre_chomp => "-",
2824 );
2825 TYPE
2827 Can be one of filename, filehandle, arrayref, or scalarref.
2828 Indicates what type of input is in the "source" configuration item.
2829 SOURCE
2831 Stores where to read the input file. The type is specified in the
2832 "type" configuration item.
2833 FILENAME
2835 Indicates a filename to read the template from. Same as putting
2836 the filename in the "source" item and setting "type" to "filename".
2837 Must be set to enable caching.
2839 FILEHANDLE
2841 Should contain an open filehandle to read the template from. Same
2842 as putting the filehandle in the "source" item and setting "type"
2843 to "filehandle".
2844 Will not be cached.
2846 ARRAYREF
2848 Should contain an arrayref whose values are the lines of the
2849 template. Same as putting the arrayref in the "source" item and
2850 setting "type" to "arrayref".
2851 Will not be cached.
2853 SCALARREF
2855 Should contain an reference to a scalar that contains the template.
2856 Same as putting the scalar ref in the "source" item and setting
2857 "type" to "scalarref".
2858 Will not be cached.
2860 CACHE
2862 If set to one, then Alloy will use a global, in-memory document
2863 cache to store compiled templates in between calls. This is
2864 generally only useful in a mod_perl environment. The document is
2865 checked for a different modification time at each request.
2866 BLIND_CACHE
2868 Same as with cache enabled, but will not check if the document has
2869 been modified.
2870 FILE_CACHE
2872 If set to 1, will cache the compiled document on the file system.
2873 If true, file_cache_dir must be set.
2874 FILE_CACHE_DIR
2876 The directory where to store cached documents when file_cache is
2877 true. This is similar to the TT compile_dir option.
2878 DOUBLE_FILE_CACHE
2880 Uses a combination of file_cache and cache.
2881 PATH
2883 Same as INCLUDE_PATH when using the process method.
2884 ASSOCIATE
2886 May be a single CGI object or an arrayref of objects. The params
2887 from these objects will be added to the params during the output
2888 call.
2889 CASE_SENSITIVE
2891 Allow passed variables set through the param method, or the
2892 associate configuration to be used case sensitively. Default is
2893 off. It is highly suggested that this be set to 1.
2894 LOOP_CONTEXT_VARS
2896 Default false. When true, calls to the loop directive will create
2897 the following variables that give information about the current
2898 iteration of the loop:
2899 __first__ - True on first iteration only
2901 __last__ - True on last iteration only
2902 __inner__ - True on any iteration that isn't first or last
2903 __odd__ - True on odd iterations
2904 __counter__ - The iteration count
2905 These variables are also available to LOOPs run under TT syntax if
2907 loop_context_vars is set and if QR_PRIVATE is set to 0.
2908 GLOBAL_VARS.
2910 Default true in HTE mode. Default false in HT. Allows top level
2911 variables to be used in LOOPs. When false, only variables defined
2912 in the current LOOP iteration hashref will be available.
2913 DEFAULT_ESCAPE
2915 Controls the type of escape used on named variables in TMPL_VAR
2916 directives. Can be one of HTML, URL, or JS. The values of
2917 TMPL_VAR directives will be encoded with this type unless they
2918 specify their own type via an ESCAPE attribute.
2919 You may alternately use the AUTO_FILTER directive which can be any
2921 of the item vmethod filters (you must use lower case when
2922 specifying the AUTO_FILTER directive). The AUTO_FILTER directive
2923 will also be applied to TMPL_VAR EXPR and TMPL_GET items while
2924 DEFAULT_ESCAPE only applies to TMPL_VAR NAME items.
2925 NO_TT
2927 Default false in 'hte' syntax. Default true in 'ht' syntax. If
2928 true, no extended TT directives will be allowed.
2929 The output method uses 'hte' syntax by default.
2931
2933 The following list of methods are other interesting methods of Alloy
2934 that may be re-implemented by subclasses of Alloy.
2935 "exception"
2937 Creates an exception object blessed into the package listed in
2938 Template::Alloy::Exception.
2939 "execute_tree"
2941 Executes a parsed tree (returned from parse_tree)
2942 "play_expr"
2944 Play the parsed expression. Turns a variable identity array into
2945 the parsed variable. This method is also responsible for playing
2946 operators and running virtual methods and filters. The variable
2947 identity array may also contain literal values, or operator
2948 identity arrays.
2949 "include_filename"
2951 Takes a file path, and resolves it into the full filename using
2952 paths from INCLUDE_PATH or INCLUDE_PATHS.
2953 "_insert"
2955 Resolves the file passed, and then returns its contents.
2956 "list_filters"
2958 Dynamically loads the filters list from Template::Filters when a
2959 filter is used that does not have a native implementation in Alloy.
2960 "load_template"
2962 Given a filename or a string reference will return a "document"
2963 hashref hash that contains the parsed tree.
2964 my $doc = $self->load_template($file); # errors die
2966 This method handles the in-memory caching of the document.
2968 "load_tree"
2970 Given the "document" hashref, will either load the parsed AST from
2971 file (if configured to do so), or will load the content, parse the
2972 content using the Parse role, and will return the tree. File based
2973 caching of the parsed AST happens here.
2974 "load_perl"
2976 Only used if COMPILE_PERL is true (default is false).
2977 Given the "document" hashref, will either load the compiled perl
2979 from file (if configured to do so), or will load the AST using
2980 "load_tree", will compile a new perl code document using the
2981 Compile role, and will return the perl code. File based caching of
2982 the compiled perl happens here.
2983 "parse_tree"
2985 Parses the passed string ref with the appropriate template syntax.
2986 See Template::Alloy::Parse for more details.
2988 "parse_expr"
2990 Parses the passed string ref for a variable or expression.
2991 See Template::Alloy::Parse for more details.
2993 "parse_args"
2995 See Template::Alloy::Parse for more details.
2996 "set_variable"
2998 Used to set a variable. Expects a variable identity array and the
2999 value to set. It will autovifiy as necessary.
3000 "strict_throw"
3002 Called during processing of template when STRICT configuration is
3003 set and an uninitialized variable is met. Arguments are the
3004 variable identity reference. Will call STRICT_THROW configuration
3005 item if set, otherwise will call throw with a useful message.
3006 "throw"
3008 Creates an exception object from the arguments and dies.
3009 "undefined_any"
3011 Called during play_expr if a value is returned that is undefined.
3012 This could be used to magically create variables on the fly. This
3013 is similar to Template::Stash::undefined. It is suggested that
3014 undefined_get be used instead. Default behavior returns undef.
3015 You may also pass a coderef via the UNDEFINED_ANY configuration
3016 variable. Also, you can try using the DEBUG => 'undef',
3017 configuration option which will throw an error on undefined
3018 variables.
3019 "undefined_get"
3021 Called when a variable is undefined during a GET directive. This
3022 is useful to see if a value that is about to get inserted into the
3023 text is undefined. undefined_any is a little too general for most
3024 cases. Also, you may pass a coderef via the UNDEFINED_GET
3025 configuration variable.
3026
3028 The following is a brief list of other methods used by Alloy.
3029 Generally, these shouldn't be overwritten by subclasses.
3030 "ast_string"
3032 Returns perl code representation of a variable.
3033 "context"
3035 Used to create a "pseudo" context object that allows for
3036 portability of TT plugins, filters, and perl blocks that need a
3037 context object. Uses the Template::Alloy::Context class.
3038 "debug_node"
3040 Used to get debug info on a directive if DEBUG_DIRS is set.
3041 "get_line_number_by_index"
3043 Used to turn string index position into line number
3044 "interpolate_node"
3046 Used for parsing text nodes for dollar variables when interpolate
3047 is on.
3048 "play_operator"
3050 Provided by the Operator role. Allows for playing an operator AST.
3051 See Template::Alloy::Operator for more details.
3053 "apply_precedence"
3055 Provided by the Parse role. Allows for parsed operator array to be
3056 translated to a tree based upon operator precedence.
3057 "_process"
3059 Called by process and the PROCESS, INCLUDE and other directives.
3060 "slurp"
3062 Reads contents of passed filename - throws file exception on error.
3063 "split_paths"
3065 Used to split INCLUDE_PATH or other directives if an arrayref is
3066 not passed.
3067 "tt_var_string"
3069 Returns a template toolkit representation of a variable.
3070 "_vars"
3072 Return a reference to the current stash of variables. This is
3073 currently only used by the pseudo context object and may disappear
3074 at some point.
3075
3077 Thanks to Andy Wardley for creating Template::Toolkit.
3078 Thanks to Sam Tregar for creating HTML::Template.
3080 Thanks to David Lowe for creating Text::Tmpl.
3082 Thanks to the Apache Velocity guys.
3084 Thanks to Ben Grimm for a patch to allow passing a parsed document to
3086 the ->process method.
3087 Thanks to David Warring for finding a parse error in HTE syntax.
3089 Thanks to Carl Franks for adding the base ENCODING support.
3091
3093 Paul Seamons <paul@seamons.com>
3094
3096 This module may be distributed under the same terms as Perl itself.
3097perl v5.36.0 2023-01-20 Template::Alloy(3)