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