1Template::Alloy(3)    User Contributed Perl Documentation   Template::Alloy(3)
2
3
4

NAME

6       Template::Alloy - TT2/3, HT, HTE, Tmpl, and Velocity Engine
7

SYNOPSIS

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
92   Javascript style usage (requires Template::Alloy::JS)
93           my $t = Template::Alloy->new;
94
95           my $swap = {
96               key1 => 'val1',
97               key2 => 'val2',
98               code => sub { 42 },
99               hash => {a => 'b'},
100           };
101
102           my $out = '';
103           $t->process_js('my/template.jstem', $swap, \$out);
104
105           my $str = "[% var foo = 1 + 3; write('(' + foo + ') (' + get('key1') + ')'); %]";
106           my $out = '';
107           $t->process_js(\$str, $swap, \$out);
108

DESCRIPTION

110       "An alloy is a homogeneous mixture of two or more elements"
111       (http://en.wikipedia.org/wiki/Alloy).
112
113       Template::Alloy represents the mixing of features and capabilities from
114       all of the major mini-language based template systems (support for non-
115       mini-language based systems will happen eventually).  With
116       Template::Alloy you can use your favorite template interface and syntax
117       and get features from each of the other major template systems.  And
118       Template::Alloy is fast - whether your using mod_perl, CGI, or running
119       from the commandline.  There is even Template::Alloy::JS for getting a
120       little more speed when that is necessary.
121
122       Template::Alloy happened by accident (accidentally on purpose).  The
123       Template::Alloy (Alloy hereafter) was originally a part of the CGI::Ex
124       suite that performed simple variable interpolation.  It used TT2 style
125       variables in TT2 style tags "[% foo.bar %]".  That was all the original
126       Template::Alloy did.  This was fine and dandy for a couple of years.
127       In winter of 2005-2006 Alloy was revamped to add a few features.  One
128       thing led to another and soon Alloy provided for most of the features
129       of TT2 as well as some from TT3.  Template::Alloy now provides a full-
130       featured implementation of the Template::Toolkit language.
131
132       After a move to a new company that was using HTML::Template::Expr and
133       Text::Tmpl templates, support was investigated and interfaces for
134       HTML::Template, HTML::Template::Expr, Text::Tmpl, and Velocity (VTL)
135       were added.  All of the various engines offer the same features - each
136       using a different syntax and interface.
137
138       More recently, the Template::Alloy::JS capabilities were introduced to
139       bring Javascript templates to the server side (along with an increase
140       in speed if ran in persistent environments).
141
142       Template::Toolkit brought the most to the table.  HTML::Template
143       brought the LOOP directive.  HTML::Template::Expr brought more vmethods
144       and using vmethods as top level functions.  Text::Tmpl brought the
145       COMMENT directive and encouraged speed matching (Text::Tmpl is almost
146       entirely C based and is very fast).  The Velocity engine brought
147       AUTO_EVAL and SHOW_UNDEFINED_INTERP.
148
149       Most of the standard Template::Toolkit documentation covering
150       directives, variables, configuration, plugins, filters, syntax, and
151       vmethods should apply to Alloy just fine (This pod tries to explain
152       everything - but there is too much).  See Template::Alloy::TT for a
153       listing of the differences between Alloy and TT.
154
155       Most of the standard HTML::Template and HTML::Template::Expr
156       documentation covering methods, variables, expressions, and syntax will
157       apply to Alloy just fine as well.
158
159       Most of the standard Text::Tmpl documentation applies, as does the
160       documentation covering Velocity (VTL).
161
162       So should you use Template::Alloy ?  Well, try it out.  It may give you
163       no visible improvement.  Or it could.
164

BACKEND

166       Template::Alloy uses a recursive regex based grammar (early versions
167       during the CGI::Ex::Template phase did not).  This allows for the
168       embedding of opening and closing tags inside other tags (as in [% a =
169       "[% 1 + 2 %]" ; a|eval %]).  The individual methods such as parse_expr
170       and play_expr may be used by external applications to add TT style
171       variable parsing to other applications.
172
173       The regex parser returns an AST (abstract syntax tree) of the text,
174       directives, variables, and expressions.  All of the different template
175       syntax options compile to the same AST format.  The AST is composed
176       only of scalars and arrayrefs and is suitable for sending to JavaScript
177       via JSON or sharing with other languages.  The parse_tree method is
178       used for returning this AST.
179
180       Once at the AST stage, there are two modes of operation.  Alloy can
181       either operate directly on the AST using the Play role, or it can
182       compile the AST to perl code via the Compile role, and then execute the
183       code.  To use the perl code route, you must set the COMPILE_PERL flag
184       to 1.  If you are running in a cached-in-memory environment such as
185       mod_perl, this is the fastest option.  If you are running in a non-
186       cached-in-memory environment, then using the Play role to run the AST
187       is generally faster.  The AST method is also more secure as cached AST
188       won't ever eval any "perl" (assuming PERL blocks are disabled - which
189       is the default).
190

ROLES

192       Template::Alloy has split out its functionality into discrete roles.
193       In Template::Toolkit, this functionality is split into separate
194       classes.  The roles in Template::Alloy simply add on more methods to
195       the main class.  When Perl 6 arrives, these roles will be translated
196       into true Roles.
197
198       The following is a list of roles used by Template::Alloy.
199
200           Template::Alloy::Compile  - Compile-to-perl role
201           Template::Alloy::HTE      - HTML::Template::Expr role
202           Template::Alloy::Operator - Operator role
203           Template::Alloy::Parse    - Parse-to-AST role
204           Template::Alloy::Play     - Play-AST role
205           Template::Alloy::Stream   - Stream output role
206           Template::Alloy::Tmpl     - Text::Tmpl role
207           Template::Alloy::TT       - Template::Toolkit role
208           Template::Alloy::Velocity - Velocity role
209           Template::Alloy::VMethod  - Virtual methods role
210
211           Template::Alloy::JS       - Javascript functionality - available separately
212
213       Template::Alloy automatically loads the roles when they are needed or
214       requested - but not sooner (with the exception of the Operator role and
215       the VMethod role which are always needed and always loaded).  This is
216       good for a CGI environment.  In mod_perl you may want to preload a role
217       to make the most of shared memory.  You may do this by passing either
218       the role name or a method supplied by that role.
219
220           # import roles necessary for running TT
221           use Template::Alloy qw(Parse Play Compile TT);
222
223           # import roles based on methods
224           use Template::Alloy qw(parse_tree play_tree compile_tree process);
225
226       Note: importing roles by method names does not import them into that
227       namespace - it is autoloading the role and methods into the
228       Template::Alloy namespace.  To help make this more clear you may use
229       the following syntax as well.
230
231           # import roles necessary for running TT
232           use Template::Alloy load => qw(Parse Play Compile TT);
233
234           # import roles based on methods
235           use Template::Alloy load => qw(process parse_tree play_tree compile_tree);
236
237           # import roles based on methods
238           use Template::Alloy
239               Parse => 1,
240               Play => 1,
241               Compile => 1,
242               TT => 1;
243
244       Even with all roles loaded Template::Alloy is still relatively small.
245       You can load all of the roles (except the JS role) by passing "all" to
246       the use statement.
247
248           use Template::Alloy 'all';
249
250           # or
251           use Template::Alloy load => 'all';
252
253           # or
254           use Template::Alloy all => 1;
255
256       As a final option, Template::Alloy also includes the ability to stand-
257       in for other template modules.  It is able to do this because it
258       supports the majority of the interface of the other template systems.
259       You can do this in the following way:
260
261           use Template::Alloy qw(Text::Tmpl HTML::Template);
262
263           # or
264           use Template::Alloy load => qw(Text::Tmpl HTML::Template);
265
266           # or
267           use Template::Alloy
268               'Text::Tmpl'     => 1,
269               'HTML::Template' => 1;
270
271       Note that the use statement will die if any of the passed module names
272       are already loaded and not subclasses of Template::Alloy.  This will
273       avoid thinking that you are using Template::Alloy when you really
274       aren't.  Using the 'all' option won't automatically do this - you must
275       mention the "stood-in" modules by name.
276
277       The following modules may be "stood-in" for:
278
279           Template
280           Text::Tmpl
281           HTML::Template
282           HTML::Template::Expr
283
284       This feature is intended to make using Template::Alloy with existing
285       code easier.  Most cases should work just fine.  Almost all syntax will
286       just work (except Alloy may make some things work that were previously
287       broken).  However Template::Alloy doesn't support 100% of the interface
288       of any of the template systems.  If you are using "features-on-the-
289       edge" then you may need to re-write portions of your code that interact
290       with the template system.
291

PUBLIC METHODS

293       The following section lists most of the publicly available methods.
294       Some less commonly used public methods are listed later in this
295       document.
296
297       "new"
298               my $obj = Template::Alloy->new({
299                   INCLUDE_PATH => ['/my/path/to/content', '/my/path/to/content2'],
300               });
301
302           Arguments may be passed as a hash or as a hashref.  Returns a
303           Template::Alloy object.
304
305           There are currently no errors during Template::Alloy object
306           creation.  If you are using the HTML::Template interface, this is
307           different behavior.  The document is not parsed until the output or
308           process methods are called.
309
310       "process"
311           This is the TT interface for starting processing.  Any errors that
312           result in the template processing being stopped will be stored and
313           available via the ->error method.
314
315               my $t = Template::Alloy->new;
316               $t->process($in, $swap, $out)
317                   || die $t->error;
318
319           Process takes three arguments.
320
321           The $in argument can be any one of:
322
323               String containing the filename of the template to be processed.
324               The filename should be relative to INCLUDE_PATH.  (See
325               INCLUDE_PATH, ABSOLUTE, and RELATIVE configuration items).  In
326               memory caching and file side caching are available for this type.
327
328               A reference to a scalar containing the contents of the template to be processed.
329
330               A coderef that will be called to return the contents of the template.
331
332               An open filehandle that will return the contents of the template when read.
333
334           The $swap argument should be hashref containing key value pairs
335           that will be available to variables swapped into the template.
336           Values can be hashrefs, hashrefs of hashrefs and so on, arrayrefs,
337           arrayrefs of arrayrefs and so on, coderefs, objects, and simple
338           scalar values such as numbers and strings.  See the section on
339           variables.
340
341           The $out argument can be any one of:
342
343               undef - meaning to print the completed template to STDOUT.
344
345               String containing a filename.  The completed template will be placed in the file.
346
347               A reference to a string.  The contents will be appended to the scalar reference.
348
349               A coderef.  The coderef will be called with the contents as a single argument.
350
351               An object that can run the method "print".  The contents will be passed as
352               a single argument to print.
353
354               An arrayref.  The contents will be pushed onto the array.
355
356               An open filehandle.  The contents will be printed to the open handle.
357
358           Additionally - the $out argument can be configured using the OUTPUT
359           configuration item.
360
361           The process method defaults to using the "cet" syntax which will
362           parse TT3 and most TT2 documents.  To parse HT or HTE documents,
363           you must pass the SYNTAX configuration item to the "new" method.
364           All calls to process would then default to HTE syntax.
365
366               my $obj = Template::Alloy->new(SYNTAX => 'hte');
367
368       "process_simple"
369           Similar to the process method but with the following restrictions:
370
371           The $in parameter is limited to a filename or a reference a string
372           containing the contents.
373
374           The $out parameter may only be a reference to a scalar string that
375           output will be appended to.
376
377           Additionally, the following configuration variables will be
378           ignored: VARIABLES, PRE_DEFINE, BLOCKS, PRE_PROCESS, PROCESS,
379           POST_PROCESS, AUTO_RESET, OUTPUT.
380
381       "error"
382           Should something go wrong during a "process" command, the error
383           that occurred can be retrieved via the error method.
384
385               $obj->process('somefile.html', {a => 'b'}, \$string_ref)
386                   || die $obj->error;
387
388       "output"
389           HTML::Template way to process a template.  The output method
390           requires that a filename, filehandle, scalarref, or arrayref
391           argument was passed to the new method.  All of the HT calling
392           conventions for new are supported.  The key difference is that
393           Alloy will not actually process the template until the output
394           method is called.
395
396               my $obj = Template::Alloy->new(filename => 'myfile.html');
397               $obj->param(\%swap);
398               print $obj->output;
399
400           See the HTML::Template documentation for more information.
401
402           The output method defaults to using the "hte" syntax which will
403           parse HTE and HT documents.  To parse TT3 or TT2 documents, you
404           must pass the SYNTAX configuration item to the "new" method.  All
405           calls to process would then default to TT3 syntax.
406
407               my $obj = Template::Alloy->new(SYNTAX => 'tt3');
408
409           Any errors that occur during the output method will die with the
410           error as the die value.
411
412       "param"
413           HTML::Template way to get or set variable values that will be used
414           by the output method.
415
416               my $val = $obj->param('key'); # get one value
417
418               $obj->param(key => $val);     # set one value
419
420               $obj->param(key => $val, key2 => $val2);   # set multiple
421
422               $obj->param({key => $val, key2 => $val2}); # set multiple
423
424           See the HTML::Template documentation for more information.
425
426           Note: Alloy does not support the die_on_bad_params configuration.
427           This is because Alloy does not resolve variable names until the
428           output method is called.
429
430       "define_vmethod"
431           This method is available for defining extra Virtual methods or
432           filters.  This method is similar to
433           Template::Stash::define_vmethod.
434
435               Template::Alloy->define_vmethod(
436                   'text',
437                   reverse => sub { my $item = shift; return scalar reverse $item },
438               );
439
440       "register_function"
441           This is the HTML::Template way of defining text vmethods.  It is
442           the same as calling define_vmethod with "text" as the first
443           argument.
444
445               Template::Alloy->register_function(
446                   reverse => sub { my $item = shift; return scalar reverse $item },
447               );
448
449       "define_directive"
450           This method can be used for adding new directives or overridding
451           existing ones.
452
453              Template::Alloy->define_directive(
454                  MYDIR => {
455                      parse_sub => sub {}, # parse additional items in the tag
456                      play_sub  => sub {
457                          my ($self, $ref, $node, $out_ref) = @_;
458                          $$out_ref .= "I always say the same thing!";
459                          return;
460                      },
461                      is_block  => 1,  # is this block like
462                      is_postop => 0,  # not a post operative directive
463                      no_interp => 1,  # no interpolation in this block
464                      continues => undef, # it doesn't "continue" any other directives
465                  },
466              );
467
468           Now with a template like:
469
470              my $str = "([% MYDIR %]This is something[% END %])";
471              Template::Alloy->new->process(\$str);
472
473           You will get:
474
475              (I always say the same thing!)
476
477           We'll add more details in later revisions of this document.
478
479       "define_syntax"
480           This method can be used for adding another syntax to or overriding
481           existing ones in the list of choices available in Alloy.  The
482           syntax can be chosen by the SYNTAX configuration item.
483
484               Template::Alloy->define_syntax(
485                   my_uber_syntax => sub {
486                       my $self = shift;
487                       local $self->{'V2PIPE'}      = 0;
488                       local $self->{'V2EQUALS'}    = 0;
489                       local $self->{'PRE_CHOMP'}   = 0;
490                       local $self->{'POST_CHOMP'}  = 0;
491                       local $self->{'NO_INCLUDES'} = 0;
492                       return $self->parse_tree_tt3(@_);
493                   },
494               );
495
496           The subroutine that is used must return an opcode tree (AST) that
497           can be played by the execute_tree method.
498
499       "define_operator"
500           This method allows for adding new operators or overriding existing
501           ones.
502
503               Template::Alloy->define_operator({
504                   type       => 'right', # can be one of prefix, postfix, right, left, none, ternary, assign
505                   precedence => 84,      # relative precedence for resolving multiple operators without parens
506                   symbols    => ['foo', 'FOO'], # any mix of chars can be used for the operators
507                   play_sub   => sub {
508                       my ($one, $two) = @_;
509                       return "You've been foo'ed ($one, $two)";
510                   },
511               });
512
513           You can then use it in a template as in the following:
514
515              my $str = "[% 'ralph' foo 1 + 2 * 3 %]";
516              Template::Alloy->new->process(\$str);
517
518           You will get:
519
520              You've been foo'ed (ralph, 7)
521
522           Future revisions of this document will include more samples.  This
523           is an experimental feature and the API will probably change.
524
525       "dump_parse_tree"
526           This method allows for returning a Data::Dumper dump of a parsed
527           template.  It is mainly used for testing.
528
529       "dump_parse_expr"
530           This method allows for returning a Data::Dumper dump of a parsed
531           variable.  It is mainly used for testing.
532
533       "import"
534           All of the arguments that can be passed to "use" that are listed
535           above in the section dealing with ROLES, can be used with the
536           import method.
537
538               # import by role
539               Template::Alloy->import(qw(Compile Play Parse TT));
540
541               # import by method
542               Template::Alloy->import(qw(compile_tree play_tree parse_tree process));
543
544               # import by "stand-in" class
545               Template::Alloy->import('Text::Tmpl', 'HTML::Template::Expr');
546
547           As mentioned in the ROLE section - arguments passed to import are
548           not imported into current namespace.  Roles and methods are only
549           imported into the Template::Alloy namespace.
550

VARIABLES

552       This section discusses how to use variables and expressions in the TT
553       mini-language.
554
555       A variable is the most simple construct to insert into the TT mini
556       language.  A variable name will look for the matching value inside
557       Template::Alloys internal stash of variables which is essentially a
558       hash reference.  This stash is initially populated by either passing a
559       hashref as the second argument to the process method, or by setting the
560       "VARIABLES" or "PRE_DEFINE" configuration variables.
561
562       If you are using either the HT or the HTE syntax, the VAR, IF, UNLESS,
563       LOOP, and INCLUDE directives will accept a NAME attribute which may
564       only be a single level (non-chained) HTML::Template variable name, or
565       they may accept an EXPR attribute which may be any valid TT3 variable
566       or expression.
567
568       The following are some sample ways to access variables.
569
570           ### some sample variables
571           my %vars = (
572               one       => '1.0',
573               foo       => 'bar',
574               vname     => 'one',
575               some_code => sub { "You passed me (".join(', ', @_).")" },
576               some_data => {
577                   a     => 'A',
578                   bar   => 3234,
579                   c     => [3, 1, 4, 1, 5, 9],
580                   vname => 'one',
581               },
582               my_list   => [20 .. 50],
583               cet       => Template::Alloy->new,
584           );
585
586           ### pass the variables into the Alloy process
587           $cet->process($template_name, \%vars)
588                || die $cet->error;
589
590           ### pass the variables during object creation (will be available to every process call)
591           my $cet = Template::Alloy->new(VARIABLES => \%vars);
592
593   GETTING VARIABLES
594       Once you have variables defined, they can be used directly in the
595       template by using their name in the stash.  Or by using the GET
596       directive.
597
598           [% foo %]
599           [% one %]
600           [% GET foo %]
601
602       Would print when processed:
603
604           bar
605           1.0
606           bar
607
608       To access members of a hashref or an arrayref, you can chain together
609       the names using a ".".
610
611           [% some_data.a %]
612           [% my_list.0] [% my_list.1 %] [% my_list.-1 %]
613           [% some_data.c.2 %]
614
615       Would print:
616
617           A
618           20 21 50
619           4
620
621       If the value of a variable is a code reference, it will be called.  You
622       can add a set of parenthesis and arguments to pass arguments.
623       Arguments are variables and can be as complex as necessary.
624
625           [% some_code %]
626           [% some_code() %]
627           [% some_code(foo) %]
628           [% some_code(one, 2, 3) %]
629
630       Would print:
631
632           You passed me ().
633           You passed me ().
634           You passed me (bar).
635           You passed me (1.0, 2, 3).
636
637       If the value of a variable is an object, methods can be called using
638       the "." operator.
639
640           [% cet %]
641
642           [% cet.dump_parse_expr('1 + 2').replace('\s+', ' ') %]
643
644       Would print something like:
645
646           Template::Alloy=HASH(0x814dc28)
647
648           $VAR1 = [ [ undef, '+', '1', '2' ], 0 ];
649
650       Each type of data (string, array and hash) have virtual methods
651       associated with them.  Virtual methods allow for access to functions
652       that are commonly used on those types of data.  For the full list of
653       built in virtual methods, please see the section titled VIRTUAL METHODS
654
655           [% foo.length %]
656           [% my_list.size %]
657           [% some_data.c.join(" | ") %]
658
659       Would print:
660
661           3
662           31
663           3 | 1 | 4 | 5 | 9
664
665       It is also possible to "interpolate" variable names using a "$".  This
666       allows for storing the name of a variable inside another variable.  If
667       a variable name is a little more complex it can be embedded inside of
668       "${" and "}".
669
670           [% $vname %]
671           [% ${vname} %]
672           [% ${some_data.vname} %]
673           [% some_data.$foo %]
674           [% some_data.${foo} %]
675
676       Would print:
677
678           1.0
679           1.0
680           1.0
681           3234
682           3234
683
684       In Alloy it is also possible to embed any expression (non-directive) in
685       "${" and "}" and it is possible to use non-integers for array access.
686       (This is not available in TT2)
687
688           [% ['a'..'z'].${ 2.3 } %]
689           [% {ab => 'AB'}.${ 'a' ~ 'b' } %]
690           [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
691
692       Would print:
693
694           c
695           AB
696           RedBlueRedBlue
697
698   SETTING VARIABLES.
699       To define variables during processing, you can use the = operator.  In
700       most cases this is the same as using the SET directive.
701
702           [% a = 234 %][% a %]
703           [% SET b = "Hello" %][% b %]
704
705       Would print:
706
707           234
708           Hello
709
710       It is also possible to create arrayrefs and hashrefs.
711
712           [% a = [1, 2, 3] %]
713           [% b = {key1 => 'val1', 'key2' => 'val2'} %]
714
715           [% a.1 %]
716           [% b.key1 %] [% b.key2 %]
717
718       Would print:
719
720           2
721           val1 val2
722
723       It is possible to set multiple values in the same SET directive.
724
725           [% SET a = 'A'
726                  b = 'B'
727                  c = 'C' %]
728           [% a %]    [% b %]    [% c %]
729
730       Would print:
731
732           A    B    C
733
734       It is also possible to unset variables, or to set members of nested
735       data structures.
736
737           [% a = 1 %]
738           [% SET a %]
739
740           [% b.0.c = 37 %]
741
742           ([% a %])
743           [% b.0.c %]
744
745       Would print
746
747           ()
748           37
749

LITERALS AND CONSTRUCTORS

751       The following are the types of literals (numbers and strings) and
752       constructors (hash and array constructs) allowed in Alloy.  They can be
753       used as arguments to functions, in place of variables in directives,
754       and in place of variables in expressions.  In Alloy it is also possible
755       to call virtual methods on literal values.
756
757       Integers and Numbers.
758               [% 23423   %]        Prints an integer.
759               [% 3.14159 %]        Prints a number.
760               [% pi = 3.14159 %]   Sets the value of the variable.
761               [% 3.13159.length %] Prints 7 (the string length of the number)
762
763           Scientific notation is supported.
764
765               [% 314159e-5 + 0 %]      Prints 3.14159.
766
767               [% .0000001.fmt('%.1e') %]  Prints 1.0e-07
768
769           Hexadecimal input is also supported.
770
771               [% 0xff + 0 %]    Prints 255
772
773               [% 48875.fmt('%x') %]  Prints beeb
774
775       Single quoted strings.
776           Returns the string.  No variable interpolation happens.
777
778               [% 'foobar' %]          Prints "foobar".
779               [% '$foo\n' %]          Prints "$foo\\n".  # the \\n is a literal "\" and an "n"
780               [% 'That\'s nice' %]    Prints "That's nice".
781               [% str = 'A string' %]  Sets the value of str.
782               [% 'A string'.split %]  Splits the string on ' ' and returns the list.
783
784           Note: virtual methods can only be used on literal strings in Alloy,
785           not in TT.
786
787           You may also embed the current tags in strings (Alloy only).
788
789               [% '[% 1 + 2 %]' | eval %]  Prints "3"
790
791       Double quoted strings.
792           Returns the string.  Variable interpolation happens.
793
794               [% "foobar" %]                   Prints "foobar".
795               [% "$foo"   %]                   Prints "bar" (assuming the value of foo is bar).
796               [% "${foo}" %]                   Prints "bar" (assuming the value of foo is bar).
797               [% "foobar\n" %]                 Prints "foobar\n".  # the \n is a newline.
798               [% str = "Hello" %]              Sets the value of str.
799               [% "foo".replace('foo','bar') %] Prints "bar".
800
801           Note: virtual methods can only be used on literal strings in Alloy,
802           not in TT.
803
804           You may also embed the current tags in strings (Alloy only).
805
806               [% "[% 1 + 2 %]" | eval %]  Prints "3"
807
808       Array Constructs.
809               [% [1, 2, 3] %]               Prints something like ARRAY(0x8309e90).
810               [% array1 = [1 .. 3] %]       Sets the value of array1.
811               [% array2 = [foo, 'a', []] %] Sets the value of array2.
812               [% [4, 5, 6].size %]          Prints 3.
813               [% [7, 8, 9].reverse.0 %]     Prints 9.
814
815           Note: virtual methods can only be used on array contructs in Alloy,
816           not in TT.
817
818       Quoted Array Constructs.
819               [% qw/1 2 3/ %]                Prints something like ARRAY(0x8309e90).
820               [% array1 = qw{Foo Bar Baz} %] Sets the value of array1.
821               [% qw[4 5 6].size %]           Prints 3.
822               [% qw(Red Blue).reverse.0 %]   Prints Blue.
823
824           Note: this works in Alloy and is planned for TT3.
825
826       Hash Constructs.
827               [% {foo => 'bar'} %]                 Prints something like HASH(0x8305880)
828               [% hash = {foo => 'bar', c => {}} %] Sets the value of hash.
829               [% {a => 'A', b => 'B'}.size %]      Prints 2.
830               [% {'a' => 'A', 'b' => 'B'}.size %]  Prints 2.
831               [% name = "Tom" %]
832               [% {Tom => 'You are Tom',
833                   Kay => 'You are Kay'}.$name %]   Prints You are Tom
834
835           Note: virtual methods can only be used on hash contructs in Alloy,
836           not in TT.
837
838       Regex Constructs.
839               [% /foo/ %]                              Prints (?-xism:foo)
840               [% a = /(foo)/i %][% "FOO".match(a).0 %] Prints FOO
841
842           Note: this works in Alloy and is planned for TT3.
843

VIRTUAL METHODS

845       Virtual methods (vmethods) are a TT feature that allow for operating on
846       the swapped template variables.
847
848       This document shows some samples of using vmethods.  For a full listing
849       of available virtual methods, see Template::Alloy::VMethod.
850

EXPRESSIONS

852       Expressions are one or more variables or literals joined together with
853       operators.  An expression can be used anywhere a variable can be used
854       with the exception of the variable name in the SET directive, and the
855       filename of PROCESS, INCLUDE, WRAPPER, and INSERT.
856
857       For a full listing of operators, see Template::Alloy::Operator.
858
859       The following section shows some samples of expressions.  For a full
860       list of available operators, please see the section titled OPERATORS.
861
862           [% 1 + 2 %]           Prints 3
863           [% 1 + 2 * 3 %]       Prints 7
864           [% (1 + 2) * 3 %]     Prints 9
865
866           [% x = 2 %]                      # assignments don't return anything
867           [% (x = 2) %]         Prints 2   # unless they are in parens
868           [% y = 3 %]
869           [% x * (y - 1) %]     Prints 4
870

DIRECTIVES

872       This section contains the alphabetical list of DIRECTIVES available in
873       Alloy.  DIRECTIVES are the "functions" and control structures that work
874       in the various mini-languages.  For further discussion and examples
875       beyond what is listed below, please refer to the TT directives
876       documentation or to the appropriate documentation for the particular
877       directive.
878
879       The examples given in this section are done using the Template::Toolkit
880       syntax, but can be done in any of the various syntax options.  See
881       Template::Alloy::TT, Template::Alloy::HTE, Template::Alloy::Tmpl, and
882       Template::Alloy::Velocity.
883
884           [% IF 1 %]One[% END %]
885           [% FOREACH a = [1 .. 3] %]
886               a = [% a %]
887           [% END %]
888
889           [% SET a = 1 %][% SET a = 2 %][% GET a %]
890
891       In TT multiple directives can be inside the same set of '[%' and '%]'
892       tags as long as they are separated by space or semi-colons (;) (The
893       Alloy version of Tmpl allows multiple also - but none of the other
894       syntax options do).  Any block directive that can also be used as a
895       post-operative directive (such as IF, WHILE, FOREACH, UNLESS, FILTER,
896       and WRAPPER) must be separated from preceding directives with a semi-
897       colon if it is being used as a block directive.  It is more safe to
898       always use a semi-colon.  Note: separating by space is only available
899       in Alloy but is a planned TT3 feature.
900
901           [% SET a = 1 ; SET a = 2 ; GET a %]
902           [% SET a = 1
903              SET a = 2
904              GET a
905            %]
906
907           [% GET 1
908                IF 0   # is a post-operative
909              GET 2 %] # prints 2
910
911           [% GET 1;
912              IF 0     # it is block based
913                GET 2
914              END
915            %]         # prints 1
916
917       The following is the list of directives.
918
919       "BLOCK"
920           Saves a block of text under a name for later use in PROCESS,
921           INCLUDE, and WRAPPER directives.  Blocks may be placed anywhere
922           within the template being processed including after where they are
923           used.
924
925               [% BLOCK foo %]Some text[% END %]
926               [% PROCESS foo %]
927
928               Would print
929
930               Some text
931
932               [% INCLUDE foo %]
933               [% BLOCK foo %]Some text[% END %]
934
935               Would print
936
937               Some text
938
939           Anonymous BLOCKS can be used for capturing.
940
941               [% a = BLOCK %]Some text[% END %][% a %]
942
943               Would print
944
945               Some text
946
947           Anonymous BLOCKS can be used with macros.
948
949       "BREAK"
950           Alias for LAST.  Used for exiting FOREACH and WHILE loops.
951
952       "CALL"
953           Calls the variable (and any underlying coderefs) as in the GET
954           method, but always returns an empty string.
955
956       "CASE"
957           Used with the SWITCH directive.  See the "SWITCH" directive.
958
959       "CATCH"
960           Used with the TRY directive.  See the "TRY" directive.
961
962       "CLEAR"
963           Clears any of the content currently generated in the innermost
964           block or template.  This can be useful when used in conjunction
965           with the TRY statement to clear generated content if an error
966           occurs later.
967
968       "COMMENT"
969           Will comment out any text found between open and close tags.  Note,
970           that the intermediate items are still parsed and END tags must
971           align - but the parsed content will be discarded.
972
973               [% COMMENT %]
974                  This text won't be shown.
975                  [% IF 1 %]And this won't either.[% END %]
976               [% END %]
977
978       "CONFIG"
979           Allow for changing the value of some compile time and runtime
980           configuration options.
981
982               [% CONFIG
983                   ANYCASE   => 1
984                   PRE_CHOMP => '-'
985               %]
986
987           The following compile time configuration options may be set:
988
989               ANYCASE
990               AUTO_EVAL
991               AUTO_FILTER
992               CACHE_STR_REFS
993               ENCODING
994               INTERPOLATE
995               POST_CHOMP
996               PRE_CHOMP
997               SEMICOLONS
998               SHOW_UNDEFINED_INTERP
999               SYNTAX
1000               V1DOLLAR
1001               V2EQUALS
1002               V2PIPE
1003
1004           The following runtime configuration options may be set:
1005
1006               ADD_LOCAL_PATH
1007               CALL_CONTEXT
1008               DUMP
1009               VMETHOD_FUNCTIONS
1010               STRICT (can only be enabled, cannot be disabled)
1011
1012           If non-named parameters as passed, they will show the current
1013           configuration:
1014
1015              [% CONFIG ANYCASE, PRE_CHOMP %]
1016
1017              CONFIG ANYCASE = undef
1018              CONFIG PRE_CHOMP = undef
1019
1020       "DEBUG"
1021           Used to reset the DEBUG_FORMAT configuration variable, or to turn
1022           DEBUG statements on or off.  This only has effect if the DEBUG_DIRS
1023           or DEBUG_ALL flags were passed to the DEBUG configuration variable.
1024
1025               [% DEBUG format '($file) (line $line) ($text)' %]
1026               [% DEBUG on %]
1027               [% DEBUG off %]
1028
1029       "DEFAULT"
1030           Similar to SET, but only sets the value if a previous value was not
1031           defined or was zero length.
1032
1033               [% DEFAULT foo = 'bar' %][% foo %] => 'bar'
1034
1035               [% foo = 'baz' %][% DEFAULT foo = 'bar' %][% foo %] => 'baz'
1036
1037       "DUMP"
1038           DUMP inserts a Data::Dumper printout of the variable or expression.
1039           If no argument is passed it will dump the entire contents of the
1040           current variable stash (with private keys removed).
1041
1042           The output also includes the current file and line number that the
1043           DUMP directive was called from.
1044
1045           See the DUMP configuration item for ways to customize and control
1046           the output available to the DUMP directive.
1047
1048               [% DUMP %] # dumps everything
1049
1050               [% DUMP 1 + 2 %]
1051
1052       "ELSE"
1053           Used with the IF directive.  See the "IF" directive.
1054
1055       "ELSIF"
1056           Used with the IF directive.  See the "IF" directive.
1057
1058       "END"
1059           Used to end a block directive.
1060
1061       "EVAL"
1062           Same as the EVALUATE directive.
1063
1064       "EVALUATE"
1065           Introduced by the Velocity templating language.  Parses and
1066           processes the contents of the passed item.  This is similar to the
1067           eval filter, but Velocity needs a directive.  Named arguments may
1068           be used for re-configuring the parser.  Any of the items that can
1069           be passed to the CONFIG directive may be passed here.
1070
1071               [% EVALUATE "[% 1 + 3 %]" %]
1072
1073               [% foo = "bar" %]
1074               [% EVALUATE "<TMPL_VAR foo>" SYNTAX => 'ht' %]
1075
1076       "FILTER"
1077           Used to apply different treatments to blocks of text.  It may
1078           operate as a BLOCK directive or as a post operative directive.
1079           Alloy supports all of the filters in Template::Filters.  The lines
1080           between scalar virtual methods and filters is blurred (or non-
1081           existent) in Alloy.  Anything that is a scalar virtual method may
1082           be used as a FILTER.
1083
1084           TODO - enumerate the at least 7 ways to pass and use filters.
1085
1086       '|' Alias for the FILTER directive.  Note that | is similar to the '.'
1087           in Template::Alloy.  Therefore a pipe cannot be used directly after
1088           a variable name in some situations (the pipe will act only on that
1089           variable).  This is the behavior employed by TT3.  To get the TT2
1090           behavior for a PIPE, use the V2PIPE configuration item.
1091
1092       "FINAL"
1093           Used with the TRY directive.  See the "TRY" directive.
1094
1095       "FOR"
1096           Alias for FOREACH
1097
1098       "FOREACH"
1099           Allows for iterating over the contents of any arrayref.  If the
1100           variable is not an arrayref, it is automatically promoted to one.
1101
1102               [% FOREACH i IN [1 .. 3] %]
1103                   The variable i = [% i %]
1104               [%~ END %]
1105
1106               [% a = [1 .. 3] %]
1107               [% FOREACH j IN a %]
1108                   The variable j = [% j %]
1109               [%~ END %]
1110
1111           Would print:
1112
1113                   The variable i = 1
1114                   The variable i = 2
1115                   The variable i = 3
1116
1117                   The variable j = 1
1118                   The variable j = 2
1119                   The variable j = 3
1120
1121           You can also use the "=" instead of "IN" or "in".
1122
1123               [% FOREACH i = [1 .. 3] %]
1124                   The variable i = [% i %]
1125               [%~ END %]
1126
1127               Same as before.
1128
1129           Setting into a variable is optional.
1130
1131               [% a = [1 .. 3] %]
1132               [% FOREACH a %] Hi [% END %]
1133
1134           Would print:
1135
1136                hi  hi  hi
1137
1138           If the item being iterated is a hashref and the FOREACH does not
1139           set into a variable, then values of the hashref are copied into the
1140           variable stash.
1141
1142               [% FOREACH [{a => 1}, {a => 2}] %]
1143                   Key a = [% a %]
1144               [%~ END %]
1145
1146           Would print:
1147
1148                   Key a = 1
1149                   Key a = 2
1150
1151           The FOREACH process uses the Template::Alloy::Iterator class to
1152           handle iterations (It is compatible with Template::Iterator).
1153           During the FOREACH loop an object blessed into the iterator class
1154           is stored in the variable "loop".
1155
1156           The loop variable provides the following information during a
1157           FOREACH:
1158
1159               index  - the current index
1160               max    - the max index of the list
1161               size   - the number of items in the list
1162               count  - index + 1
1163               number - index + 1
1164               first  - true if on the first item
1165               last   - true if on the last item
1166               next   - return the next item in the list
1167               prev   - return the previous item in the list
1168               odd    - return 1 if the current count is odd, 0 otherwise
1169               even   - return 1 if the current count is even, 0 otherwise
1170               parity - return "odd" if the current count is odd, "even" otherwise
1171
1172           The following:
1173
1174               [% FOREACH [1 .. 3] %] [% loop.count %]/[% loop.size %] [% END %]
1175
1176           Would print:
1177
1178                1/3  2/3  3/3
1179
1180           The iterator is also available using a plugin.  This allows for
1181           access to multiple "loop" variables in a nested FOREACH directive.
1182
1183               [%~ USE outer_loop = Iterator(["a", "b"]) %]
1184               [%~ FOREACH i = outer_loop %]
1185                   [%~ FOREACH j = ["X", "Y"] %]
1186                      [% outer_loop.count %]-[% loop.count %] = ([% i %] and [% j %])
1187                   [%~ END %]
1188               [%~ END %]
1189
1190           Would print:
1191
1192                      1-1 = (a and X)
1193                      1-2 = (a and Y)
1194                      2-1 = (b and X)
1195                      2-2 = (b and Y)
1196
1197           FOREACH may also be used as a post operative directive.
1198
1199               [% "$i" FOREACH i = [1 .. 5] %] => 12345
1200
1201       "GET"
1202           Return the value of a variable or expression.
1203
1204               [% GET a %]
1205
1206           The GET keyword may be omitted.
1207
1208               [% a %]
1209
1210               [% 7 + 2 - 3 %] => 6
1211
1212           See the section on VARIABLES.
1213
1214       "IF (IF / ELSIF / ELSE)"
1215           Allows for conditional testing.  Expects an expression as its only
1216           argument.  If the expression is true, the contents of its block are
1217           processed.  If false, the processor looks for an ELSIF block.  If
1218           an ELSIF's expression is true then it is processed.  Finally it
1219           looks for an ELSE block which is processed if none of the IF or
1220           ELSIF's expressions were true.
1221
1222               [% IF a == b %]A equaled B[% END %]
1223
1224               [% IF a == b -%]
1225                   A equaled B
1226               [%- ELSIF a == c -%]
1227                   A equaled C
1228               [%- ELSE -%]
1229                   Couldn't determine that A equaled anything.
1230               [%- END %]
1231
1232           IF may also be used as a post operative directive.
1233
1234               [% 'A equaled B' IF a == b %]
1235
1236           Note: If you are using HTML::Template style documents, the TMPL_IF
1237           tag parses using the limited HTML::Template parsing rules.
1238           However, you may use EXPR="" to embed a TT3 style expression.
1239
1240       "INCLUDE"
1241           Parse the contents of a file or block and insert them.  Variables
1242           defined or modifications made to existing variables are discarded
1243           after a template is included.
1244
1245               [% INCLUDE path/to/template.html %]
1246
1247               [% INCLUDE "path/to/template.html" %]
1248
1249               [% file = "path/to/template.html" %]
1250               [% INCLUDE $file %]
1251
1252               [% BLOCK foo %]This is foo[% END %]
1253               [% INCLUDE foo %]
1254
1255           Arguments may also be passed to the template:
1256
1257               [% INCLUDE "path/to/template.html" a = "An arg" b = "Another arg" %]
1258
1259           Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1260           RELATIVE configuration items are set.
1261
1262           Multiple filenames can be passed by separating them with a plus, a
1263           space, or commas (TT2 doesn't support the comma).  Any supplied
1264           arguments will be used on all templates.
1265
1266               [% INCLUDE "path/to/template.html",
1267                          "path/to/template2.html" a = "An arg" b = "Another arg" %]
1268
1269           On Perl 5.6 on some platforms there may be some issues with the
1270           variable localization.  There is no problem on 5.8 and greater.
1271
1272       "INSERT"
1273           Insert the contents of a file without template parsing.
1274
1275           Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1276           RELATIVE configuration items are set.
1277
1278           Multiple filenames can be passed by separating them with a plus, a
1279           space, or commas (TT2 doesn't support the comma).
1280
1281               [% INSERT "path/to/template.html",
1282                         "path/to/template2.html" %]
1283
1284       "JS"
1285           Only available if the COMPILE_JS configuration item is true
1286           (default is false).  This requires the Template::Alloy::JS module
1287           to be installed.
1288
1289           Allow eval'ing the block of text as javascript.  The block will be
1290           parsed and then eval'ed.
1291
1292               [% a = "BimBam" %]
1293               [%~ JS %]
1294                   write('The variable a was "' + get('a') + '"');
1295                   set('b', "FooBar");
1296               [% END %]
1297               [% b %]
1298
1299           Would print:
1300
1301               The variable a was "BimBam"
1302               FooBar
1303
1304       "LAST"
1305           Used to exit out of a WHILE or FOREACH loop.
1306
1307       "LOOP"
1308           This directive operates similar to the HTML::Template loop
1309           directive.  The LOOP directive expects a single variable name.
1310           This variable name should point to an arrayref of hashrefs.  The
1311           keys of each hashref will be added to the variable stash when it is
1312           iterated.
1313
1314               [% var a = [{b => 1}, {b => 2}, {b => 3}] %]
1315
1316               [% LOOP a %] ([% b %]) [% END %]
1317
1318           Would print:
1319
1320                (1)  (2)  (3)
1321
1322           If Alloy is in HT mode and GLOBAL_VARS is false, the contents of
1323           the hashref will be the only items available during the loop
1324           iteration.
1325
1326           If LOOP_CONTEXT_VARS is true, and $QR_PRIVATE is false (default
1327           when called through the output method), then the variables
1328           __first__, __last__,
1329            __inner__, __odd__, and __counter__ will be set.  See the
1330           HTML::Template loop_context_vars configuration item for more
1331           information.
1332
1333       "MACRO"
1334           Takes a directive and turns it into a variable that can take
1335           arguments.
1336
1337               [% MACRO foo(i, j) BLOCK %]You passed me [% i %] and [% j %].[% END %]
1338
1339               [%~ foo("a", "b") %]
1340               [% foo(1, 2) %]
1341
1342           Would print:
1343
1344               You passed me a and b.
1345               You passed me 1 and 2.
1346
1347           Another example:
1348
1349               [% MACRO bar(max) FOREACH i = [1 .. max] %]([% i %])[% END %]
1350
1351               [%~ bar(4) %]
1352
1353           Would print:
1354
1355               (1)(2)(3)(4)
1356
1357           Starting with version 1.012 of Template::Alloy there is also a
1358           macro operator.
1359
1360               [% foo = ->(i,j){ "You passed me $i and $j" } %]
1361
1362               [% bar = ->(max){ FOREACH i = [1 .. max]; i ; END } %]
1363
1364           See the Template::Alloy::Operator documentation for more examples.
1365
1366       "META"
1367           Used to define variables that will be available via either the
1368           template or component namespace.
1369
1370           Once defined, they cannot be overwritten.
1371
1372               [% template.foobar %]
1373               [%~ META foobar = 'baz' %]
1374               [%~ META foobar = 'bing' %]
1375
1376           Would print:
1377
1378               baz
1379
1380       "NEXT"
1381           Used to go to the next iteration of a WHILE or FOREACH loop.
1382
1383       "PERL"
1384           Only available if the EVAL_PERL configuration item is true (default
1385           is false).
1386
1387           Allow eval'ing the block of text as perl.  The block will be parsed
1388           and then eval'ed.
1389
1390               [% a = "BimBam" %]
1391               [%~ PERL %]
1392                   my $a = "[% a %]";
1393                   print "The variable \$a was \"$a\"";
1394                   $stash->set('b', "FooBar");
1395               [% END %]
1396               [% b %]
1397
1398           Would print:
1399
1400               The variable $a was "BimBam"
1401               FooBar
1402
1403           During execution, anything printed to STDOUT will be inserted into
1404           the template.  Also, the $stash and $context variables are set and
1405           are references to objects that mimic the interface provided by
1406           Template::Context and Template::Stash.  These are provided for
1407           compatibility only.  $self contains the current Template::Alloy
1408           object.
1409
1410       "PROCESS"
1411           Parse the contents of a file or block and insert them.  Unlike
1412           INCLUDE, no variable localization happens so variables defined or
1413           modifications made to existing variables remain after the template
1414           is processed.
1415
1416               [% PROCESS path/to/template.html %]
1417
1418               [% PROCESS "path/to/template.html" %]
1419
1420               [% file = "path/to/template.html" %]
1421               [% PROCESS $file %]
1422
1423               [% BLOCK foo %]This is foo[% END %]
1424               [% PROCESS foo %]
1425
1426           Arguments may also be passed to the template:
1427
1428               [% PROCESS "path/to/template.html" a = "An arg" b = "Another arg" %]
1429
1430           Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or
1431           RELATIVE configuration items are set.
1432
1433           Multiple filenames can be passed by separating them with a plus, a
1434           space, or commas (TT2 doesn't support the comma).  Any supplied
1435           arguments will be used on all templates.
1436
1437               [% PROCESS "path/to/template.html",
1438                          "path/to/template2.html" a = "An arg" b = "Another arg" %]
1439
1440       "RAWPERL"
1441           Only available if the EVAL_PERL configuration item is true (default
1442           is false).  Similar to the PERL directive, but you will need to
1443           append to the $output variable rather than just calling PRINT.
1444
1445       "RETURN"
1446           Used to exit the innermost block or template and continue
1447           processing in the surrounding block or template.
1448
1449           There are two changes from TT2 behavior.  First, In Alloy, a RETURN
1450           during a MACRO call will only exit the MACRO.  Second, the RETURN
1451           directive takes an optional variable name or expression, if passed,
1452           the MACRO will return this value instead of the normal text from
1453           the MACRO.  The process_simple method will also return this value.
1454
1455           You can also use the item, list, and hash return vmethods.
1456
1457               [% RETURN %]       # just exits
1458               [% RETURN "foo" %] # return value is foo
1459               [% "foo".return %] # same thing
1460
1461       "SET"
1462           Used to set variables.
1463
1464              [% SET a = 1 %][% a %]             => "1"
1465              [% a = 1 %][% a %]                 => "1"
1466              [% b = 1 %][% SET a = b %][% a %]  => "1"
1467              [% a = 1 %][% SET a %][% a %]      => ""
1468              [% SET a = [1, 2, 3] %][% a.1 %]   => "2"
1469              [% SET a = {b => 'c'} %][% a.b %]  => "c"
1470
1471       "STOP"
1472           Used to exit the entire process method (out of all blocks and
1473           templates).  No content will be processed beyond this point.
1474
1475       "SWITCH"
1476           Allow for SWITCH and CASE functionality.
1477
1478              [% a = "hi" %]
1479              [% b = "bar" %]
1480              [% SWITCH a %]
1481                  [% CASE "foo"           %]a was foo
1482                  [% CASE b               %]a was bar
1483                  [% CASE ["hi", "hello"] %]You said hi or hello
1484                  [% CASE DEFAULT         %]I don't know what you said
1485              [% END %]
1486
1487           Would print:
1488
1489              You said hi or hello
1490
1491       "TAGS"
1492           Change the type of enclosing braces used to delineate template
1493           tags.  This remains in effect until the end of the enclosing block
1494           or template or until the next TAGS directive.  Either a named set
1495           of tags must be supplied, or two tags themselves must be supplied.
1496
1497               [% TAGS html %]
1498
1499               [% TAGS <!-- --> %]
1500
1501           The named tags are (duplicated from TT):
1502
1503               asp       => ['<%',     '%>'    ], # ASP
1504               default   => ['\[%',    '%\]'   ], # default
1505               html      => ['<!--',   '-->'   ], # HTML comments
1506               mason     => ['<%',     '>'     ], # HTML::Mason
1507               metatext  => ['%%',     '%%'    ], # Text::MetaText
1508               php       => ['<\?',    '\?>'   ], # PHP
1509               star      => ['\[\*',   '\*\]'  ], # TT alternate
1510               template  => ['\[%',    '%\]'   ], # Normal Template Toolkit
1511               template1 => ['[\[%]%', '%[%\]]'], # allow TT1 style
1512               tt2       => ['\[%',    '%\]'   ], # TT2
1513
1514           If custom tags are supplied, by default they are escaped using
1515           quotemeta.  You may also pass explicitly quoted strings, or regular
1516           expressions as arguments as well (if your regex begins with a ', ",
1517           or / you must quote it.
1518
1519               [% TAGS [<] [>] %]          matches "[<] tag [>]"
1520
1521               [% TAGS '[<]' '[>]' %]      matches "[<] tag [>]"
1522
1523               [% TAGS "[<]" "[>]" %]      matches "[<] tag [>]"
1524
1525               [% TAGS /[<]/ /[>]/ %]      matches "< tag >"
1526
1527               [% TAGS ** ** %]            matches "** tag **"
1528
1529               [% TAGS /**/ /**/ %]        Throws an exception.
1530
1531           You should be sure that the start tag does not include grouping
1532           parens or INTERPOLATE will not function properly.
1533
1534       "THROW"
1535           Allows for throwing an exception.  If the exception is not caught
1536           via the TRY DIRECTIVE, the template will abort processing of the
1537           directive.
1538
1539               [% THROW mytypes.sometime 'Something happened' arg1 => val1 %]
1540
1541           See the TRY directive for examples of usage.
1542
1543       "TRY"
1544           The TRY block directive will catch exceptions that are thrown while
1545           processing its block (It cannot catch parse errors unless they are
1546           in included files or evaltt'ed strings.   The TRY block will then
1547           look for a CATCH block that will be processed.  While it is being
1548           processed, the "error" variable will be set with the thrown
1549           exception as the value.  After the TRY block - the FINAL block will
1550           be ran whether or not an error was thrown (unless a CATCH block
1551           throws an error).
1552
1553           Note: Parse errors cannot be caught unless they are in an eval
1554           FILTER, or are in a separate template being INCLUDEd or PROCESSed.
1555
1556               [% TRY %]
1557               Nothing bad happened.
1558               [% CATCH %]
1559               Caught the error.
1560               [% FINAL %]
1561               This section runs no matter what happens.
1562               [% END %]
1563
1564           Would print:
1565
1566               Nothing bad happened.
1567               This section runs no matter what happens.
1568
1569           Another example:
1570
1571               [% TRY %]
1572               [% THROW "Something happened" %]
1573               [% CATCH %]
1574                 Error:               [% error %]
1575                 Error.type:          [% error.type %]
1576                 Error.info:          [% error.info %]
1577               [% FINAL %]
1578                 This section runs no matter what happens.
1579               [% END %]
1580
1581           Would print:
1582
1583                 Error:               undef error - Something happened
1584                 Error.type:          undef
1585                 Error.info:          Something happened
1586                 This section runs no matter what happens.
1587
1588           You can give the error a type and more information including named
1589           arguments.  This information replaces the "info" property of the
1590           exception.
1591
1592               [% TRY %]
1593               [% THROW foo.bar "Something happened" "grrrr" foo => 'bar' %]
1594               [% CATCH %]
1595                 Error:               [% error %]
1596                 Error.type:          [% error.type %]
1597                 Error.info:          [% error.info %]
1598                 Error.info.0:        [% error.info.0 %]
1599                 Error.info.1:        [% error.info.1 %]
1600                 Error.info.args.0:   [% error.info.args.0 %]
1601                 Error.info.foo:      [% error.info.foo %]
1602               [% END %]
1603
1604           Would print something like:
1605
1606                 Error:               foo.bar error - HASH(0x82a395c)
1607                 Error.type:          foo.bar
1608                 Error.info:          HASH(0x82a395c)
1609                 Error.info.0:        Something happened
1610                 Error.info.1:        grrrr
1611                 Error.info.args.0:   Something happened
1612                 Error.info.foo:      bar
1613
1614           You can also give the CATCH block a type to catch.  And you can
1615           nest TRY blocks.  If types are specified, Alloy will try and find
1616           the closest matching type.  Also, an error object can be re-thrown
1617           using $error as the argument to THROW.
1618
1619               [% TRY %]
1620                 [% TRY %]
1621                   [% THROW foo.bar "Something happened" %]
1622                 [% CATCH bar %]
1623                   Caught bar.
1624                 [% CATCH DEFAULT %]
1625                   Caught default - but re-threw.
1626                   [% THROW $error %]
1627                 [% END %]
1628               [% CATCH foo %]
1629                 Caught foo.
1630               [% CATCH foo.bar %]
1631                 Caught foo.bar.
1632               [% CATCH %]
1633                 Caught anything else.
1634               [% END %]
1635
1636           Would print:
1637
1638                   Caught default - but re-threw.
1639
1640                 Caught foo.bar.
1641
1642       "UNLESS"
1643           Same as IF but condition is negated.
1644
1645               [% UNLESS 0 %]hi[% END %]  => hi
1646
1647           Can also be a post operative directive.
1648
1649       "USE"
1650           Allows for loading a Template::Toolkit style plugin.
1651
1652               [% USE iter = Iterator(['foo', 'bar']) %]
1653               [%~ iter.get_first %]
1654               [% iter.size %]
1655
1656           Would print:
1657
1658               foo
1659               2
1660
1661           Note that it is possible to send arguments to the new object
1662           constructor.  It is also possible to omit the variable name being
1663           assigned.  In that case the name of the plugin becomes the
1664           variable.
1665
1666               [% USE Iterator(['foo', 'bar', 'baz']) %]
1667               [%~ Iterator.get_first %]
1668               [% Iterator.size %]
1669
1670           Would print:
1671
1672               foo
1673               3
1674
1675           Plugins that are loaded are looked up for in the namespace listed
1676           in the PLUGIN_BASE directive which defaults to Template::Plugin.
1677           So in the previous example, if Template::Toolkit was installed, the
1678           iter object would loaded by the class Template::Plugin::Iterator.
1679           In Alloy, an effective way to disable plugins is to set the
1680           PLUGIN_BASE to a non-existent base such as "_" (In TT it will still
1681           fall back to look in Template::Plugin).
1682
1683           Note: The iterator plugin will fall back and use
1684           Template::Alloy::Iterator if Template::Toolkit is not installed.
1685           No other plugins come installed with Template::Alloy.
1686
1687           The names of the Plugin being loaded from PLUGIN_BASE are case
1688           insensitive.  However, using case insensitive names is bad as it
1689           requires scanning the @INC directories for any module matching the
1690           PLUGIN_BASE and caching the result (OK - not that bad).
1691
1692           If the plugin is not found and the LOAD_PERL directive is set, then
1693           Alloy will try and load a module by that name (note: this type of
1694           lookup is case sensitive and will not scan the @INC dirs for a
1695           matching file).
1696
1697               # The LOAD_PERL directive should be set to 1
1698               [% USE ta = Template::Alloy %]
1699               [%~ ta.dump_parse_expr('2 * 3') %]
1700
1701           Would print:
1702
1703               [[undef, '*', 2, 3], 0];
1704
1705           See the PLUGIN_BASE, and PLUGINS configuration items.
1706
1707           See the documentation for Template::Manual::Plugins.
1708
1709       "VIEW"
1710           Implement a TT style view.  For more information, please see the
1711           Template::View documentation.  This DIRECTIVE will correctly parse
1712           the arguments and then pass them along to a newly created
1713           Template::View object.  It will fail if Template::View can not be
1714           found.
1715
1716       "WHILE"
1717           Will process a block of code while a condition is true.
1718
1719               [% WHILE i < 3 %]
1720                   [%~ i = i + 1 %]
1721                   i = [% i %]
1722               [%~ END %]
1723
1724           Would print:
1725
1726                   i = 1
1727                   i = 2
1728                   i = 3
1729
1730           You could also do:
1731
1732               [% i = 4 %]
1733               [% WHILE (i = i - 1) %]
1734                   i = [% i %]
1735               [%~ END %]
1736
1737           Would print:
1738
1739                   i = 3
1740                   i = 2
1741                   i = 1
1742
1743           Note that (f = f - 1) is a valid expression that returns the value
1744           of the assignment.  The parenthesis are not optional.
1745
1746           WHILE has a built in limit of 1000 iterations.  This is controlled
1747           by the global variable $WHILE_MAX in Template::Alloy.
1748
1749           WHILE may also be used as a post operative directive.
1750
1751               [% "$i" WHILE (i = i + 1) < 7 %] => 123456
1752
1753       "WRAPPER"
1754           Block directive.  Processes contents of its block and then passes
1755           them in the [% content %] variable to the block or filename listed
1756           in the WRAPPER tag.
1757
1758               [% WRAPPER foo b = 23 %]
1759               My content to be processed ([% b %]).[% a = 2 %]
1760               [% END %]
1761
1762               [% BLOCK foo %]
1763               A header ([% a %]).
1764               [% content %]
1765               A footer ([% a %]).
1766               [% END %]
1767
1768           This would print.
1769
1770               A header (2).
1771               My content to be processed (23).
1772               A footer (2).
1773
1774           The WRAPPER directive may also be used as a post operative
1775           directive.
1776
1777               [% BLOCK baz %]([% content %])[% END -%]
1778               [% "foobar" WRAPPER baz %]
1779
1780           Would print
1781
1782               (foobar)');
1783
1784           Multiple filenames can be passed by separating them with a plus, a
1785           space, or commas (TT2 doesn't support the comma).  Any supplied
1786           arguments will be used on all templates.  Wrappers are processed in
1787           reverse order, so that the first wrapper listed will surround each
1788           subsequent wrapper listed.  Variables from inner wrappers are
1789           available to the next wrapper that surrounds it.
1790
1791               [% WRAPPER "path/to/outer.html",
1792                          "path/to/inner.html" a = "An arg" b = "Another arg" %]
1793

DIRECTIVES (HTML::Template Style)

1795       HTML::Template templates use directives that look similar to the
1796       following:
1797
1798           <TMPL_VAR NAME="foo">
1799
1800           <TMPL_IF NAME="bar">
1801             BAR
1802           </TMPL_IF>
1803
1804       The normal set of HTML::Template directives are TMPL_VAR, TMPL_IF,
1805       TMPL_ELSE, TMPL_UNLESS, TMPL_INCLUDE, and TMPL_LOOP.  These tags should
1806       have either a NAME attribute, an EXPR attribute, or a bare variable
1807       name that is used to specify the value to be operated.  If a NAME is
1808       specified, it may only be a single level value (as opposed to a TT
1809       chained variable).  In the case of the TMPL_INCLUDE directive, the NAME
1810       is the file to be included.
1811
1812       In Alloy, the EXPR attribute can be used with any of these types to
1813       specify TT compatible variable or expression that will be used for the
1814       value.
1815
1816           <TMPL_VAR NAME="foo">          Prints the value contained in foo
1817           <TMPL_VAR foo>                 Prints the value contained in foo
1818           <TMPL_VAR EXPR="foo">          Prints the value contained in foo
1819
1820           <TMPL_VAR NAME="foo.bar.baz">  Prints the value contained in {'foo.bar.baz'}
1821           <TMPL_VAR EXPR="foo.bar.baz">  Prints the value contained in {foo}->{bar}->{baz}
1822
1823           <TMPL_IF foo>                  Prints FOO if foo is true
1824             FOO
1825           </TMPL_IF
1826
1827           <TMPL_UNLESS foo>              Prints FOO unless foo is true
1828             FOO
1829           </TMPL_UNLESS
1830
1831           <TMPL_INCLUDE NAME="foo.ht">   Includes the template in "foo.ht"
1832
1833           <TMPL_LOOP foo>                Iterates on the arrayref foo
1834             <TMPL_VAR name>
1835           </TMPL_LOOP>
1836
1837       Template::Alloy makes all of the other TT3 directives available in
1838       addition to the normal set of HTML::Template directives.  For example,
1839       the following is valid in Alloy.
1840
1841           <TMPL_MACRO bar(n) BLOCK>You said <TMPL_VAR n></TMPL_MACRO>
1842           <TMPL_GET bar("hello")>
1843
1844       The TMPL_VAR tag may also include an optional ESCAPE attribute.  This
1845       specifies how the value of the tag should be escaped prior to
1846       substituting into the template.
1847
1848           Escape value |   Type of escape
1849           ---------------------------------
1850           HTML, 1      |   HTML encoding
1851           URL          |   URL encoding
1852           JS           |   basic javascript encoding (\n, \r, and \")
1853           NONE, 0      |   No encoding (default).
1854
1855       The TMPL_VAR tag may also include an optional DEFAULT attribute that
1856       contains a string that will be used if the variable returns false.
1857
1858           <TMPL_VAR foo DEFAULT="Foo was false">
1859

CHOMPING

1861       Chomping refers to the handling of whitespace immediately before and
1862       immediately after template tags.  By default, nothing happens to this
1863       whitespace.  Modifiers can be placed just inside the opening and just
1864       before the closing tags to control this behavior.
1865
1866       Additionally, the PRE_CHOMP and POST_CHOMP configuration variables can
1867       be set and will globally control all chomping behavior for tags that do
1868       not have their own chomp modifier.  PRE_CHOMP and POST_CHOMP can be set
1869       to any of the following values:
1870
1871           none:      0   +   Template::Constants::CHOMP_NONE
1872           one:       1   -   Template::Constants::CHOMP_ONE
1873           collapse:  2   =   Template::Constants::CHOMP_COLLAPSE
1874           greedy:    3   ~   Template::Constants::CHOMP_GREEDY
1875
1876       CHOMP_NONE
1877           Don't do any chomping.  The "+" sign is used to indicate
1878           CHOMP_NONE.
1879
1880               Hello.
1881
1882               [%+ "Hi." +%]
1883
1884               Howdy.
1885
1886           Would print:
1887
1888               Hello.
1889
1890               Hi.
1891
1892               Howdy.
1893
1894       CHOMP_ONE (formerly known as CHOMP_ALL)
1895           Delete any whitespace up to the adjacent newline.  The "-" is used
1896           to indicate CHOMP_ONE.
1897
1898               Hello.
1899
1900               [%- "Hi." -%]
1901
1902               Howdy.
1903
1904           Would print:
1905
1906               Hello.
1907               Hi.
1908               Howdy.
1909
1910       CHOMP_COLLAPSE
1911           Collapse adjacent whitespace to a single space.  The "=" is used to
1912           indicate CHOMP_COLLAPSE.
1913
1914               Hello.
1915
1916               [%= "Hi." =%]
1917
1918               Howdy.
1919
1920           Would print:
1921
1922               Hello. Hi. Howdy.
1923
1924       CHOMP_GREEDY
1925           Remove all adjacent whitespace.  The "~" is used to indicate
1926           CHOMP_GREEDY.
1927
1928               Hello.
1929
1930               [%~ "Hi." ~%]
1931
1932               Howdy.
1933
1934           Would print:
1935
1936               Hello.Hi.Howdy.
1937

CONFIGURATION

1939       The following configuration variables are supported (in alphabetical
1940       order).  Note: for further discussion you can refer to the TT config
1941       documentation.
1942
1943       Items may be passed in upper or lower case.  If lower case names are
1944       passed they will be resolved to uppercase during the "new" method.
1945
1946       All of the variables in this section can be passed to the "new"
1947       constructor.
1948
1949           my $obj = Template::Alloy->new(
1950               VARIABLES  => \%hash_of_variables,
1951               AUTO_RESET => 0,
1952               TRIM       => 1,
1953               POST_CHOMP => "=",
1954               PRE_CHOMP  => "-",
1955           );
1956
1957       ABSOLUTE
1958           Boolean.  Default false.  Are absolute paths allowed for included
1959           files.
1960
1961       ADD_LOCAL_PATH
1962           If true, allows calls include_filename to temporarily add the
1963           directory of the current template being processed to the
1964           INCLUDE_PATHS arrayref.  This allows templates to refer to files in
1965           the local template directory without specifying the local directory
1966           as part of the filename.  Default is 0.  If set to a negative
1967           value, the current directory will be added to the end of the
1968           current INCLUDE_PATHS.
1969
1970           This property may also be set in the template using the CONFIG
1971           directive.
1972
1973               [% CONFIG ADD_LOCAL_PATH => 1 %]
1974
1975       ANYCASE
1976           Allow directive matching to be case insensitive.
1977
1978               [% get 23 %] prints 23 with ANYCASE => 1
1979
1980       AUTO_RESET
1981           Boolean.  Default 1.  Clear blocks that were set during the process
1982           method.
1983
1984       AUTO_EVAL
1985           Boolean.  Default 0 (default 1 in Velocity syntax).  If set to
1986           true, double quoted strings will automatically be passed to the
1987           eval filter.  This configuration option may also be passed to the
1988           CONFIG directive.
1989
1990       AUTO_FILTER
1991           Can be the name of any filter.  Default undef.  Any variable
1992           returned by a GET directive (including implicit GET) will be passed
1993           to the named filter.  This configuration option may also be passed
1994           to the CONFIG directive.
1995
1996               # with AUTO_FILTER => 'html'
1997
1998               [% f = "&"; GET f %] prints &amp;
1999               [% f = "&"; f %]     prints &amp; (implicit GET)
2000
2001           If a variable already has another filter applied the AUTO_FILTER is
2002           not applied.  The "none" scalar virtual method has been added to
2003           allow for using variables without reapplying filters.
2004
2005               # with AUTO_FILTER => 'html'
2006
2007               [% f = "&";  f | none %] prints &
2008               [% f = "&"; g = f; g %]  prints &amp;
2009               [% f = "&"; g = f; g | none %]  prints & (because g = f is a SET directive)
2010               [% f = "&"; g = GET f; g | none %]  prints &amp; (because the actual GET directive was called)
2011
2012       BLOCKS
2013           Only available via when using the process interface.
2014
2015           A hashref of blocks that can be used by the process method.
2016
2017               BLOCKS => {
2018                   block_1 => sub { ... }, # coderef that returns a block
2019                   block_2 => 'A String',  # simple string
2020               },
2021
2022           Note that a Template::Document cannot be supplied as a value (TT
2023           supports this).  However, it is possible to supply a value that is
2024           equal to the hashref returned by the load_template method.
2025
2026       CACHE_SIZE
2027           Number of compiled templates to keep in memory.  Default undef.
2028           Undefined means to allow all templates to cache.  A value of 0 will
2029           force no caching.  The cache mechanism will clear templates that
2030           have not been used recently.
2031
2032       CACHE_STR_REFS
2033           Default 1.  If set, any string refs will have an MD5 sum taken that
2034           will then be used for caching the document - both in memory and on
2035           the file system (if configured).  This will give a significant
2036           speed boost.  Note that this affects strings passed to the EVALUATE
2037           directive or eval filters as well.  It may be set using the CONFIG
2038           directive.
2039
2040       CALL_CONTEXT (Not in TT)
2041           Can be one of 'item', 'list', or 'smart'.  The default type is
2042           'smart'.  The CALL_CONTEXT configuration specifies in what Perl
2043           context coderefs and methods used in the processed templates will
2044           be called.  TT historically has avoided the distinction of item
2045           (scalar) vs list context.  To avoid worrying about this, TT
2046           introduced 'smart' context.  The "@()" and "$()" context specifiers
2047           make it easier to use CALL_CONTEXT in some situations.
2048
2049           The following table shows the relationship between the various
2050           contexts:
2051
2052                  return values      smart context   list context    item context
2053                  -------------      -------------   ------------    ------------
2054               A   'foo'              'foo'           ['foo']         'foo'
2055               B   undef              undef           [undef]         undef
2056               C   (no return value)  undef           []              undef
2057               D   (7)                7               [7]             7
2058               E   (7,8,9)            [7,8,9]         [7,8,9]         9
2059               F   @a = (7)           7               [7]             1
2060               G   @a = (7,8,9)       [7,8,9]         [7,8,9]         3
2061               H   ({b=>"c"})         {b=>"c"}        [{b=>"c"}]      {b=>"c"}
2062               I   ([1])              [1]             [[1]]           [1]
2063               J   ([1],[2])          [[1],[2]]       [[1],[2]]       [2]
2064               K   [7,8,9]            [7,8,9]         [[7,8,9]]       [7,8,9]
2065               L   (undef, "foo")     die "foo"       [undef, "foo"]  "foo"
2066               M   wantarray?1:0      1               [1]             0
2067
2068           Cases F, H, I and M are common sticking points of the smart context
2069           in TT2.  Note that list context always returns an arrayref from a
2070           method or function call.  Smart context can give confusing results
2071           sometimes, especially the I and J cases.  Case L for smart match is
2072           very surprising.
2073
2074           The list and item context provide another feature for method calls.
2075           In smart context, TT will look for a hash key in the object by the
2076           same name as the method, if a method by that name doesn't exist.
2077           In item and list context Alloy will die if a method by that name
2078           cannot be found.
2079
2080           The CALL_CONTEXT configuration item can be passed to new or it may
2081           also be set during runtime using the CONFIG directive.  The
2082           following method call would be in list context:
2083
2084               [% CONFIG CALL_CONTEXT => 'list';
2085                  results = my_obj.get_results;
2086                  CONFIG CALL_CONTEXT => 'smart'
2087               %]
2088
2089           Note that we needed to restore CALL_CONTEXT to the default 'smart'
2090           value.  Template::Alloy has added the "@()" (list) and the "$()"
2091           (item) context specifiers.  The previous example could be written
2092           as:
2093
2094               [% results = @( my_obj.get_results ) %]
2095
2096           To call that same method in item (scalar) context you would do the
2097           following:
2098
2099               [% results = $( my_obj.get_results ) %]
2100
2101           The "@()" and "$()" operators are based on the Perl 6 counterpart.
2102
2103       COMPILE_DIR
2104           Base directory to store compiled templates.  Default undef.
2105           Compiled templates will only be stored if one of COMPILE_DIR and
2106           COMPILE_EXT is set.
2107
2108           If set, the AST of parsed documents will be cached.  If
2109           COMPILE_PERL is set, the compiled perl code will also be stored.
2110
2111       COMPILE_EXT
2112           Extension to add to stored compiled template filenames.  Default
2113           undef.
2114
2115           If set, the AST of parsed documents will be cached.  If
2116           COMPILE_PERL is set, the compiled perl code will also be stored.
2117
2118       COMPILE_JS
2119           Default false.
2120
2121           Requires installation of Template::Alloy::JS.  When enabled, the
2122           parsed templates will be translated into Javascript and executed
2123           using the V8 javascript engine.  If compile_dir is also set, this
2124           compiled javascript will be cached to disk.
2125
2126           If your templates are short, there is little benefit to using this
2127           other than you can then use the JS directive.  If your templates
2128           are long or you are running in a cached environment, this will
2129           speed up your templates.
2130
2131           Certain limitations exist when COMPILE_JS is set, most notably the
2132           USE and VIEW directives are not supported, and method calls on
2133           objects passed to the template do not work (code refs passed in do
2134           work however).  These limitations are due to the nature of
2135           JavaScript::V8 bind and Perl/JavaScript OO differences.
2136
2137       COMPILE_PERL
2138           Default false.
2139
2140           If set to 1 or 2, will translate the normal AST into a perl 5 code
2141           document.  This document can then be executed directly, cached in
2142           memory, or cached on the file system depending upon the
2143           configuration items set.
2144
2145           If set to 1, a perl code document will always be generated.
2146
2147           If set to 2, a perl code document will only be generated if an AST
2148           has already been cached for the document.  This should give a speed
2149           benefit and avoid extra compilation unless the document has been
2150           used more than once.
2151
2152           If Alloy is running in a cached environment such as mod_perl, then
2153           using compile_perl can offer some speed benefit and makes Alloy
2154           faster than Text::Tmpl and as fast as HTML::Template::Compiled (but
2155           Alloy has more features).
2156
2157           If you are not running in a cached environment, such as from
2158           commandline, or from CGI, it is generally faster to only run from
2159           the AST (with COMPILE_PERL => 0).
2160
2161       CONSTANTS
2162           Hashref.  Used to define variables that will be "folded" into the
2163           compiled template.  Variables defined here cannot be overridden.
2164
2165               CONSTANTS => {my_constant => 42},
2166
2167               A template containing:
2168
2169               [% constants.my_constant %]
2170
2171               Will have the value 42 compiled in.
2172
2173           Constants defined in this way can be chained as in [%
2174           constant.foo.bar.baz %].
2175
2176       CONSTANT_NAMESPACE
2177           Allow for setting the top level of values passed in CONSTANTS.
2178           Default value is 'constants'.
2179
2180       DEBUG
2181           Takes a list of constants |'ed together which enables different
2182           debugging modes.  Alternately the lowercase names may be used
2183           (multiple values joined by a ",").
2184
2185               The only supported TT values are:
2186               DEBUG_UNDEF (2)    - debug when an undefined value is used (now easier to use STRICT)
2187               DEBUG_DIRS  (8)    - debug when a directive is used.
2188               DEBUG_ALL   (2047) - turn on all debugging.
2189
2190               Either of the following would turn on undef and directive debugging:
2191
2192               DEBUG => 'undef, dirs',            # preferred
2193               DEBUG => 2 | 8,
2194               DEBUG => DEBUG_UNDEF | DEBUG_DIRS, # constants from Template::Constants
2195
2196       DEBUG_FORMAT
2197           Change the format of messages inserted when DEBUG has DEBUG_DIRS
2198           set on.  This essentially the same thing as setting the format
2199           using the DEBUG directive.
2200
2201       DEFAULT
2202           The name of a default template file to use if the passed one is not
2203           found.
2204
2205       DELIMITER
2206           String to use to split INCLUDE_PATH with.  Default is :.  It is
2207           more straight forward to just send INCLUDE_PATH an arrayref of
2208           paths.
2209
2210       DUMP
2211           Configures the behavior of the DUMP tag.  May be set to 0, a
2212           hashref, or another true value.  Default is true.
2213
2214           If set to 0, all DUMP directives will do nothing.  This is useful
2215           if you would like to turn off the DUMP directives under some
2216           environments.
2217
2218           IF set to a true value (or undefined) then DUMP directives will
2219           operate.
2220
2221           If set to a hashref, the values of the hash can be used to
2222           configure the operation of the DUMP directives.  The following are
2223           the values that can be set in this hash.
2224
2225           EntireStash
2226               Default 1.  If set to 0, then the DUMP directive will not print
2227               the entire contents of the stash when a DUMP directive is
2228               called without arguments.
2229
2230           handler
2231               Defaults to an internal coderef.  If set to a coderef, the DUMP
2232               directive will pass the arguments to be dumped and expects a
2233               string with the dumped data.  This gives complete control over
2234               the dump process.
2235
2236               Note 1: The default handler makes sure that values matching the
2237               private variable regex are not included.  If you install your
2238               own handler, you will need to take care of these variables if
2239               you intend for them to not be shown.
2240
2241               Note 2: If you would like the name of the variable to be
2242               dumped, include the string '$VAR1' and the DUMP directive will
2243               interpolate the value.  For example, to dump all output as YAML
2244               - you could do the following:
2245
2246                   DUMP => {
2247                      handler => sub {
2248                          require YAML;
2249                          return "\$VAR1 =\n".YAML::Dump(shift);
2250                      },
2251                   }
2252
2253           header
2254               Default 1.  Controls whether a header is printed for each DUMP
2255               directive.  The header contains the file and line number the
2256               DUMP directive was called from.  If set to 0 the headers are
2257               disabled.
2258
2259           html
2260               Defaults to 1 if $ENV{'REQUEST_METHOD'} is set - 0 otherwise.
2261               If set to 1, then the output of the DUMP directive is passed to
2262               the html filter and encased in "pre" tags.  If set to 0 no html
2263               encoding takes place.
2264
2265           Sortkeys, Useqq, Ident, Pad, etc
2266               Any of the Data::Dumper configuration items may be passed.
2267
2268       ENCODING
2269           Default undef.  If set, and if Perl version is greater than or
2270           equal to 5.7.3 (when Encode.pm was first included), then
2271           Encode::decode will be called every time a template file is
2272           processed and will be passed the value of ENCODING and text from
2273           the template.
2274
2275           This item can also be set using [% CONFIG ENCODING => encoding %]
2276           before calling INCLUDE or PROCESS directives to change encodings on
2277           the fly.
2278
2279       END_TAG
2280           Set a string to use as the closing delimiter for TT.  Default is
2281           "%]".
2282
2283       ERROR
2284           Used as a fall back when the processing of a template fails.  May
2285           either be a single filename that will be used in all cases, or may
2286           be a hashref of options where the keynames represent error types
2287           that will be handled by the filename in their value.  A key named
2288           default will be used if no other matching keyname can be found.
2289           The selection process is similar to that of the TRY/CATCH/THROW
2290           directives (see those directives for more information).
2291
2292               my $t = Template::Alloy->new({
2293                   ERROR => 'general/catch_all_errors.html',
2294               });
2295
2296               my $t = Template::Alloy->new({
2297                   ERROR => {
2298                       default   => 'general/catch_all_errors.html',
2299                       foo       => 'catch_all_general_foo_errors.html',
2300                       'foo.bar' => 'catch_foo_bar_errors.html',
2301                   },
2302               });
2303
2304           Note that the ERROR handler will only be used for errors during the
2305           processing of the main document.  It will not catch errors that
2306           occur in templates found in the PRE_PROCESS, POST_PROCESS, and
2307           WRAPPER configuration items.
2308
2309       ERRORS
2310           Same as the ERROR configuration item.  Both may be used
2311           interchangeably.
2312
2313       EVAL_PERL
2314           Boolean.  Default false.  If set to a true value, PERL and RAWPERL
2315           blocks will be allowed to run.  This is a potential security hole,
2316           as arbitrary perl can be included in the template.  If
2317           Template::Toolkit is installed, a true EVAL_PERL value also allows
2318           the perl and evalperl filters to be used.
2319
2320       FILTERS
2321           Allow for passing in TT style filters.
2322
2323               my $filters = {
2324                   filter1 =>  sub { my $str = shift; $s =~ s/./1/gs; $s },
2325                   filter2 => [sub { my $str = shift; $s =~ s/./2/gs; $s }, 0],
2326                   filter3 => [sub { my ($context, @args) = @_; return sub { my $s = shift; $s =~ s/./3/gs; $s } }, 1],
2327               };
2328
2329               my $str = q{
2330                   [% a = "Hello" %]
2331                   1 ([% a | filter1 %])
2332                   2 ([% a | filter2 %])
2333                   3 ([% a | filter3 %])
2334               };
2335
2336               my $obj = Template::Alloy->new(FILTERS => $filters);
2337               $obj->process(\$str) || die $obj->error;
2338
2339           Would print:
2340
2341                   1 (11111)
2342                   2 (22222)
2343                   3 (33333)
2344
2345           Filters passed in as an arrayref should contain a coderef and a
2346           value indicating if they are dynamic or static (true meaning
2347           dynamic).  The dynamic filters are passed the pseudo context object
2348           and any arguments and should return a coderef that will be called
2349           as the filter.  The filter coderef is then passed the string.
2350
2351       GLOBAL_CACHE
2352           Default 0.  If true, documents will be cached in
2353           $Template::Alloy::GLOBAL_CACHE.  It may also be passed a hashref,
2354           in which case the documents will be cached in the passed hashref.
2355
2356           The TT, Tmpl, and velocity will automatically cache documents in
2357           the object.  The HTML::Template interface uses a new object each
2358           time.  Setting the HTML::Template's CACHE configuration is the same
2359           as setting GLOBAL_CACHE.
2360
2361       INCLUDE_PATH
2362           A string or an arrayref or coderef that returns an arrayref that
2363           contains directories to look for files included by processed
2364           templates.  Defaults to "." (the current directory).
2365
2366       INCLUDE_PATHS
2367           Non-TT item.  Same as INCLUDE_PATH but only takes an arrayref.  If
2368           not specified then INCLUDE_PATH is turned into an arrayref and
2369           stored in INCLUDE_PATHS.  Overrides INCLUDE_PATH.
2370
2371       INTERPOLATE
2372           Boolean.  Specifies whether variables in text portions of the
2373           template will be interpolated.  For example, the $variable and
2374           ${var.value} would be substituted with the appropriate values from
2375           the variable cache (if INTERPOLATE is on).
2376
2377               [% IF 1 %]The variable $variable had a value ${var.value}[% END %]
2378
2379       LOAD_PERL
2380           Indicates if the USE directive can fall back and try and load a
2381           perl module if the indicated module was not found in the
2382           PLUGIN_BASE path.  See the USE directive.  This configuration has
2383           no bearing on the COMPILE_PERL directive used to indicate using
2384           compiled perl documents.
2385
2386       MAX_EVAL_RECURSE (Alloy only)
2387           Will use $Template::Alloy::MAX_EVAL_RECURSE if not present.
2388           Default is 50.  Prevents runaway on the following:
2389
2390               [% f = "[% f|eval %]" %][% f|eval %]
2391
2392       MAX_MACRO_RECURSE (Alloy only)
2393           Will use $Template::Alloy::MAX_MACRO_RECURSE if not present.
2394           Default is 50.  Prevents runaway on the following:
2395
2396               [% MACRO f BLOCK %][% f %][% END %][% f %]
2397
2398       NAMESPACE
2399           No Template::Namespace::Constants support.  Hashref of hashrefs
2400           representing constants that will be folded into the template at
2401           compile time.
2402
2403               Template::Alloy->new(NAMESPACE => {constants => {
2404                    foo => 'bar',
2405               }});
2406
2407           Is the same as
2408
2409               Template::Alloy->new(CONSTANTS => {
2410                    foo => 'bar',
2411               });
2412
2413           Any number of hashes can be added to the NAMESPACE hash.
2414
2415       NEGATIVE_STAT_TTL (Not in TT)
2416           Defaults to STAT_TTL which defaults to $STAT_TTL which defaults to
2417           1.
2418
2419           Similar to STAT_TTL - but represents the time-to-live seconds until
2420           a document that was not found is checked again against the system
2421           for modifications.  Setting this number higher will allow for fewer
2422           file system accesses.  Setting it to a negative number will allow
2423           for the file system to be checked every hit.
2424
2425       NO_INCLUDES
2426           Default false.  If true, calls to INCLUDE, PROCESS, WRAPPER and
2427           INSERT will fail.  This option is also available when using the
2428           process method.
2429
2430       OUTPUT
2431           Alternate way of passing in the output location for processed
2432           templates.  If process is not passed an output argument, it will
2433           look for this value.
2434
2435           See the process method for a listing of possible values.
2436
2437       OUTPUT_PATH
2438           Base path for files written out via the process method or via the
2439           redirect and file filters.  See the redirect virtual method and the
2440           process method for more information.
2441
2442       PLUGINS
2443           A hashref of mappings of plugin modules.
2444
2445              PLUGINS => {
2446                 Iterator => 'Template::Plugin::Iterator',
2447                 DBI      => 'MyDBI',
2448              },
2449
2450           See the USE directive for more information.
2451
2452       PLUGIN_BASE
2453           Default value is Template::Plugin.  The base module namespace that
2454           template plugins will be looked for.  See the USE directive for
2455           more information.  May be either a single namespace, or an arrayref
2456           of namespaces.
2457
2458       POST_CHOMP
2459           Set the type of chomping at the ending of a tag.  See the section
2460           on chomping for more information.
2461
2462       POST_PROCESS
2463           Only available via when using the process interface.
2464
2465           A list of templates to be processed and appended to the content
2466           after the main template.  During this processing the "template"
2467           namespace will contain the name of the main file being processed.
2468
2469           This is useful for adding a global footer to all templates.
2470
2471       PRE_CHOMP
2472           Set the type of chomping at the beginning of a tag.  See the
2473           section on chomping for more information.
2474
2475       PRE_DEFINE
2476           Same as the VARIABLES configuration item.
2477
2478       PRE_PROCESS
2479           Only available via when using the process interface.
2480
2481           A list of templates to be processed before and pre-pended to the
2482           content before the main template.  During this processing the
2483           "template" namespace will contain the name of the main file being
2484           processed.
2485
2486           This is useful for adding a global header to all templates.
2487
2488       PROCESS
2489           Only available via when using the process interface.
2490
2491           Specify a file to use as the template rather than the one passed in
2492           to the ->process method.
2493
2494       RECURSION
2495           Boolean.  Default false.  Indicates that INCLUDED or PROCESSED
2496           files can refer to each other in a circular manner.  Be careful
2497           about recursion.
2498
2499       RELATIVE
2500           Boolean.  Default false.  If true, allows filenames to be specified
2501           that are relative to the currently running process.
2502
2503       SEMICOLONS
2504           Boolean.  Default false.  If true, then the syntax will require
2505           that semi-colons separate multiple directives in the same tag.
2506           This is useful for keeping the syntax a little more clean as well
2507           as trouble shooting some errors.
2508
2509       SHOW_UNDEFINED_INTERP (Not in TT)
2510           Default false (default true in Velocity).  If INTERPOLATE is true,
2511           interpolated dollar variables that return undef will be removed.
2512           With SHOW_UNDEFINED_INTERP set, undef values will leave the
2513           variable there.
2514
2515               [% CONFIG INTERPOLATE => 1 %]
2516               [% SET foo = 1 %][% SET bar %]
2517               ($foo)($bar) ($!foo)($!bar)
2518
2519           Would print:
2520
2521               (1)() (1)()
2522
2523           But the following:
2524
2525               [% CONFIG INTERPOLATE => 1, SHOW_UNDEFINED_INTERP => 1 %]
2526               [% SET foo = 1 %][% SET bar %]
2527               ($foo)($bar) ($!foo)($!bar)
2528
2529           Would print:
2530
2531               (1)($bar) (1)()
2532
2533           Note that you can use an exclamation point directly after the
2534           dollar to make the variable silent.  This is similar to how
2535           Velocity works.
2536
2537       START_TAG
2538           Set a string or regular expression to use as the opening delimiter
2539           for TT.  Default is "[%".  You should be sure that the tag does not
2540           include grouping parens or INTERPOLATE will not function properly.
2541
2542       STASH
2543           Template::Alloy manages its own stash of variables.  You can pass a
2544           Template::Stash or Template::Stash::XS object, but Template::Alloy
2545           will copy all of values out of the object into its own stash.
2546           Template::Alloy won't use any of the methods of the passed STASH
2547           object.  The STASH option is only available when using the process
2548           method.
2549
2550       STAT_TTL
2551           Defaults to $STAT_TTL which defaults to 1.  Represents time-to-live
2552           seconds until a cached in memory document is compared to the file
2553           system for modifications.  Setting this number higher will allow
2554           for fewer file system accesses.  Setting it to a negative number
2555           will allow for the file system to be checked every hit.
2556
2557       STREAM
2558           Defaults to false.  If set to true, generated template content will
2559           be printed to the currently selected filehandle (default is STDOUT)
2560           as soon as it is ready - there will be no buffering of the output.
2561
2562           The Stream role uses the Play role's directives
2563           (non-compiled_perl).
2564
2565           All directives and configuration work, except for the following
2566           exceptions:
2567
2568           CLEAR directive
2569               Because the output is not buffered - the CLEAR directive would
2570               have no effect.  The CLEAR directive will throw an error when
2571               STREAM is on.
2572
2573           TRIM configuration
2574               Because the output is not buffered - trim operations cannot be
2575               played on the output buffers.
2576
2577           WRAPPER configuration/directive
2578               The WRAPPER configuration and directive items effectively turn
2579               off STREAM since the WRAPPERS are generated in reverse order
2580               and because the content is inserted into the middle of the
2581               WRAPPERS.  WRAPPERS will still work, they just won't stream.
2582
2583           VARIOUS errors
2584               Because the template is streaming, items that cause errors my
2585               result in partially printed pages - since the error would occur
2586               part way through the print.
2587
2588           All output is printed directly to the currently selected filehandle
2589           (defaults to STDOUT) via the CORE::print function.  Any output
2590           parameter passed to process or process_simple will be ignored.
2591
2592           If you would like the output to go to another handle, you will need
2593           to select that handle, process the template, and re-select STDOUT.
2594
2595       STRICT
2596           Defaults to false.  If set to true, any undefined variable that is
2597           encountered will cause the processing of the template to abort.
2598           This can be caught with a TRY block.  This can be useful for making
2599           sure that the template only attempts to use variables that were
2600           correctly initialized similar in spirit to Perl's "use strict."
2601
2602           When this occurs the strict_throw method is called.
2603
2604           See the STRICT_THROW configuration for additional options.
2605
2606           Similar functionality could be implemented using UNDEFINED_ANY.
2607
2608           The STRICT configuration item can be passed to new or it may also
2609           be set during runtime using the CONFIG directive.  Once set though
2610           it cannot be disabled for the duration of the current template and
2611           sub components.  For example you could call [% CONFIG STRICT => 1
2612           %] in header.tt and strict mode would be enabled for the header.tt
2613           and any sub templates processed by header.tt.
2614
2615       STRICT_THROW (not in TT)
2616           Default undef.  Can be set to a subroutine which will be called
2617           when STRICT is set and an undefined variable is processed.  It will
2618           be passed the error type, error message, and a hashref of template
2619           information containing the current component being processed, the
2620           current outer template being processed, the identity reference for
2621           the variable, and the stringified name of the identity.  This
2622           override can be used for filtering allowable elements.
2623
2624               my $ta = Template::Alloy->new({
2625                   STRICT => 1,
2626                   STRICT_THROW => sub {
2627                       my ($ta, $err_type, $msg, $args) = @_;
2628
2629                       return if $args->{'component'} eq 'header.tt'
2630                                 && $args->{'template'} eq 'main.html'
2631                                 && $args->{'name'} eq 'foo.bar(1)'; # stringified identity name
2632
2633                       $ta->throw($err_type, $msg); # all other undefined variables die
2634                   },
2635               });
2636
2637       SYNTAX (not in TT)
2638           Defaults to "cet".  Indicates the syntax that will be used for
2639           parsing included templates or eval'ed strings.  You can use the
2640           CONFIG directive to change the SYNTAX on the fly (it will not
2641           affect the syntax of the document currently being parsed).
2642
2643           The syntax may be passed in upper or lower case.
2644
2645           The available choices are:
2646
2647               alloy - Template::Alloy style - the same as TT3
2648               tt3   - Template::Toolkit ver3 - same as Alloy
2649               tt2   - Template::Toolkit ver2 - almost the same as TT3
2650               tt1   - Template::Toolkit ver1 - almost the same as TT2
2651               ht    - HTML::Template - same as HTML::Template::Expr without EXPR
2652               hte   - HTML::Template::Expr
2653               js    - JavaScript style - requires compile_js to be set.
2654               jsr   - JavaScript Raw style - requires compile_js to be set.
2655
2656           Passing in a different syntax allows for the process method to use
2657           a non-TT syntax and for the output method to use a non-HT syntax.
2658
2659           The following is a sample of HTML::Template interface usage parsing
2660           a Template::Toolkit style document.
2661
2662               my $obj = Template::Alloy->new(filename => 'my/template.tt'
2663                                                syntax   => 'cet');
2664               $obj->param(\%swap);
2665               print $obj->output;
2666
2667           The following is a sample of Template::Toolkit interface usage
2668           parsing a HTML::Template::Expr style document.
2669
2670               my $obj = Template::Alloy->new(SYNTAX => 'hte');
2671               $obj->process('my/template.ht', \%swap);
2672
2673           You can use the define_syntax method to add another custom syntax
2674           to the list of available options.
2675
2676       TAG_STYLE
2677           Allow for setting the type of tag delimiters to use for parsing the
2678           TT.  See the TAGS directive for a listing of the available types.
2679
2680       TRIM
2681           Remove leading and trailing whitespace from blocks and templates.
2682           This operation is performed after all enclosed template tags have
2683           been executed.
2684
2685       UNDEFINED_ANY
2686           This is not a TT configuration option.  This option expects to be a
2687           code ref that will be called if a variable is undefined during a
2688           call to play_expr.  It is passed the variable identity array as a
2689           single argument.  This is most similar to the "undefined" method of
2690           Template::Stash.  It allows for the "auto-defining" of a variable
2691           for use in the template.  It is suggested that UNDEFINED_GET be
2692           used instead as UNDEFINED_ANY is a little to general in defining
2693           variables.
2694
2695           You can also sub class the module and override the undefined_any
2696           method.
2697
2698       UNDEFINED_GET
2699           This is not a TT configuration option.  This option expects to be a
2700           code ref that will be called if a variable is undefined during a
2701           call to GET.  It is passed the variable identity array as a single
2702           argument.  This is more useful than UNDEFINED_ANY in that it is
2703           only called during a GET directive rather than in embedded
2704           expressions (such as [% a || b || c %]).
2705
2706           You can also sub class the module and override the undefined_get
2707           method.
2708
2709       V1DOLLAR
2710           This allows for some compatibility with TT1 templates.  The only
2711           real behavior change is that [% $foo %] becomes the same as [% foo
2712           %].  The following is a basic table of changes invoked by using
2713           V1DOLLAR.
2714
2715              With V1DOLLAR        Equivalent Without V1DOLLAR (Normal default)
2716              "[% foo %]"          "[% foo %]"
2717              "[% $foo %]"         "[% foo %]"
2718              "[% ${foo} %]"       "[% ${foo} %]"
2719              "[% foo.$bar %]"     "[% foo.bar %]"
2720              "[% ${foo.bar} %]"   "[% ${foo.bar} %]"
2721              "[% ${foo.$bar} %]"  "[% ${foo.bar} %]"
2722              "Text: $foo"         "Text: $foo"
2723              "Text: ${foo}"       "Text: ${foo}"
2724              "Text: ${$foo}"      "Text: ${foo}"
2725
2726       V2EQUALS
2727           Default 1 in the TT syntax, defaults to 0 in the HTML::Template
2728           syntax.
2729
2730           If set to 1 then "==" is an alias for "eq" and "!= is an alias for
2731           "ne".
2732
2733               [% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
2734               [% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]
2735
2736               Prints
2737
2738               0
2739               1
2740
2741       V2PIPE
2742           Restores the behavior of the pipe operator to be compatible with
2743           TT2.
2744
2745           With V2PIPE = 1
2746
2747               [%- BLOCK a %]b is [% b %]
2748               [% END %]
2749               [%- PROCESS a b => 237 | repeat(2) %]
2750
2751               # output of block "a" with b set to 237 is passed to the repeat(2) filter
2752
2753               b is 237
2754               b is 237
2755
2756           With V2PIPE = 0 (default)
2757
2758               [%- BLOCK a %]b is [% b %]
2759               [% END %]
2760               [% PROCESS a b => 237 | repeat(2) %]
2761
2762               # b set to 237 repeated twice, and b passed to block "a"
2763
2764               b is 237237
2765
2766       VARIABLES
2767           A hashref of variables to initialize the template stash with.
2768           These variables are available for use in any of the executed
2769           templates.  See the section on VARIABLES for the types of
2770           information that can be passed in.
2771
2772       VMETHOD_FUNCTIONS
2773           Defaults to 1.  All scalar virtual methods are available as top
2774           level functions as well.  This is not true of TT2.  In
2775           Template::Alloy the following are equivalent:
2776
2777               [% "abc".length %]
2778               [% length("abc") %]
2779
2780           You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.
2781
2782       WRAPPER
2783           Only available via when using the process interface.
2784
2785           Operates similar to the WRAPPER directive.  The option can be given
2786           a single filename, or an arrayref of filenames that will be used to
2787           wrap the processed content.  If an arrayref is passed the filenames
2788           are processed in reverse order, so that the first filename
2789           specified will end up being on the outside (surrounding all other
2790           wrappers).
2791
2792              my $t = Template::Alloy->new(
2793                  WRAPPER => ['my/wrappers/outer.html', 'my/wrappers/inner.html'],
2794              );
2795
2796           Content generated by the PRE_PROCESS and POST_PROCESS will come
2797           before and after (respectively) the content generated by the
2798           WRAPPER configuration item.
2799
2800           See the WRAPPER directive for more examples of how wrappers are
2801           constructed.
2802

CONFIGURATION (HTML::Template STYLE)

2804       The following HTML::Template and HTML::Template::Expr configuration
2805       variables are supported (in HTML::Template documentation order).  Note:
2806       for further discussion you can refer to the HT documentation.  Many of
2807       the variables mentioned in the TT CONFIGURATION section apply here as
2808       well.  Unless noted, these items only apply when using the output
2809       method.
2810
2811       Items may be passed in upper or lower case.  All passed items are
2812       resolved to upper case.
2813
2814       These variables should be passed to the "new" constructor.
2815
2816           my $obj = Template::Alloy->new(
2817               type   => 'filename',
2818               source => 'my/template.ht',
2819               die_on_bad_params => 1,
2820               loop_context_vars => 1,
2821               global_vars       => 1
2822               post_chomp => "=",
2823               pre_chomp  => "-",
2824           );
2825
2826       TYPE
2827           Can be one of filename, filehandle, arrayref, or scalarref.
2828           Indicates what type of input is in the "source" configuration item.
2829
2830       SOURCE
2831           Stores where to read the input file.  The type is specified in the
2832           "type" configuration item.
2833
2834       FILENAME
2835           Indicates a filename to read the template from.  Same as putting
2836           the filename in the "source" item and setting "type" to "filename".
2837
2838           Must be set to enable caching.
2839
2840       FILEHANDLE
2841           Should contain an open filehandle to read the template from.  Same
2842           as putting the filehandle in the "source" item and setting "type"
2843           to "filehandle".
2844
2845           Will not be cached.
2846
2847       ARRAYREF
2848           Should contain an arrayref whose values are the lines of the
2849           template.  Same as putting the arrayref in the "source" item and
2850           setting "type" to "arrayref".
2851
2852           Will not be cached.
2853
2854       SCALARREF
2855           Should contain an reference to a scalar that contains the template.
2856           Same as putting the scalar ref in the "source" item and setting
2857           "type" to "scalarref".
2858
2859           Will not be cached.
2860
2861       CACHE
2862           If set to one, then Alloy will use a global, in-memory document
2863           cache to store compiled templates in between calls.  This is
2864           generally only useful in a mod_perl environment.  The document is
2865           checked for a different modification time at each request.
2866
2867       BLIND_CACHE
2868           Same as with cache enabled, but will not check if the document has
2869           been modified.
2870
2871       FILE_CACHE
2872           If set to 1, will cache the compiled document on the file system.
2873           If true, file_cache_dir must be set.
2874
2875       FILE_CACHE_DIR
2876           The directory where to store cached documents when file_cache is
2877           true.  This is similar to the TT compile_dir option.
2878
2879       DOUBLE_FILE_CACHE
2880           Uses a combination of file_cache and cache.
2881
2882       PATH
2883           Same as INCLUDE_PATH when using the process method.
2884
2885       ASSOCIATE
2886           May be a single CGI object or an arrayref of objects.  The params
2887           from these objects will be added to the params during the output
2888           call.
2889
2890       CASE_SENSITIVE
2891           Allow passed variables set through the param method, or the
2892           associate configuration to be used case sensitively.  Default is
2893           off.  It is highly suggested that this be set to 1.
2894
2895       LOOP_CONTEXT_VARS
2896           Default false.  When true, calls to the loop directive will create
2897           the following variables that give information about the current
2898           iteration of the loop:
2899
2900              __first__   - True on first iteration only
2901              __last__    - True on last iteration only
2902              __inner__   - True on any iteration that isn't first or last
2903              __odd__     - True on odd iterations
2904              __counter__ - The iteration count
2905
2906           These variables are also available to LOOPs run under TT syntax if
2907           loop_context_vars is set and if QR_PRIVATE is set to 0.
2908
2909       GLOBAL_VARS.
2910           Default true in HTE mode.  Default false in HT.  Allows top level
2911           variables to be used in LOOPs.  When false, only variables defined
2912           in the current LOOP iteration hashref will be available.
2913
2914       DEFAULT_ESCAPE
2915           Controls the type of escape used on named variables in TMPL_VAR
2916           directives.  Can be one of HTML, URL, or JS.  The values of
2917           TMPL_VAR directives will be encoded with this type unless they
2918           specify their own type via an ESCAPE attribute.
2919
2920           You may alternately use the AUTO_FILTER directive which can be any
2921           of the item vmethod filters (you must use lower case when
2922           specifying the AUTO_FILTER directive).  The AUTO_FILTER directive
2923           will also be applied to TMPL_VAR EXPR and TMPL_GET items while
2924           DEFAULT_ESCAPE only applies to TMPL_VAR NAME items.
2925
2926       NO_TT
2927           Default false in 'hte' syntax.  Default true in 'ht' syntax.  If
2928           true, no extended TT directives will be allowed.
2929
2930           The output method uses 'hte' syntax by default.
2931

SEMI PUBLIC METHODS

2933       The following list of methods are other interesting methods of Alloy
2934       that may be re-implemented by subclasses of Alloy.
2935
2936       "exception"
2937           Creates an exception object blessed into the package listed in
2938           Template::Alloy::Exception.
2939
2940       "execute_tree"
2941           Executes a parsed tree (returned from parse_tree)
2942
2943       "play_expr"
2944           Play the parsed expression.  Turns a variable identity array into
2945           the parsed variable.  This method is also responsible for playing
2946           operators and running virtual methods and filters.  The variable
2947           identity array may also contain literal values, or operator
2948           identity arrays.
2949
2950       "include_filename"
2951           Takes a file path, and resolves it into the full filename using
2952           paths from INCLUDE_PATH or INCLUDE_PATHS.
2953
2954       "_insert"
2955           Resolves the file passed, and then returns its contents.
2956
2957       "list_filters"
2958           Dynamically loads the filters list from Template::Filters when a
2959           filter is used that does not have a native implementation in Alloy.
2960
2961       "load_template"
2962           Given a filename or a string reference will return a "document"
2963           hashref hash that contains the parsed tree.
2964
2965               my $doc = $self->load_template($file); # errors die
2966
2967           This method handles the in-memory caching of the document.
2968
2969       "load_tree"
2970           Given the "document" hashref, will either load the parsed AST from
2971           file (if configured to do so), or will load the content, parse the
2972           content using the Parse role, and will return the tree.  File based
2973           caching of the parsed AST happens here.
2974
2975       "load_perl"
2976           Only used if COMPILE_PERL is true (default is false).
2977
2978           Given the "document" hashref, will either load the compiled perl
2979           from file (if configured to do so), or will load the AST using
2980           "load_tree", will compile a new perl code document using the
2981           Compile role, and will return the perl code.  File based caching of
2982           the compiled perl happens here.
2983
2984       "parse_tree"
2985           Parses the passed string ref with the appropriate template syntax.
2986
2987           See Template::Alloy::Parse for more details.
2988
2989       "parse_expr"
2990           Parses the passed string ref for a variable or expression.
2991
2992           See Template::Alloy::Parse for more details.
2993
2994       "parse_args"
2995           See Template::Alloy::Parse for more details.
2996
2997       "set_variable"
2998           Used to set a variable.  Expects a variable identity array and the
2999           value to set.  It will autovifiy as necessary.
3000
3001       "strict_throw"
3002           Called during processing of template when STRICT configuration is
3003           set and an uninitialized variable is met.  Arguments are the
3004           variable identity reference.  Will call STRICT_THROW configuration
3005           item if set, otherwise will call throw with a useful message.
3006
3007       "throw"
3008           Creates an exception object from the arguments and dies.
3009
3010       "undefined_any"
3011           Called during play_expr if a value is returned that is undefined.
3012           This could be used to magically create variables on the fly.  This
3013           is similar to Template::Stash::undefined.  It is suggested that
3014           undefined_get be used instead.  Default behavior returns undef.
3015           You may also pass a coderef via the UNDEFINED_ANY configuration
3016           variable.  Also, you can try using the DEBUG => 'undef',
3017           configuration option which will throw an error on undefined
3018           variables.
3019
3020       "undefined_get"
3021           Called when a variable is undefined during a GET directive.  This
3022           is useful to see if a value that is about to get inserted into the
3023           text is undefined.  undefined_any is a little too general for most
3024           cases.  Also, you may pass a coderef via the UNDEFINED_GET
3025           configuration variable.
3026

OTHER UTILITY METHODS

3028       The following is a brief list of other methods used by Alloy.
3029       Generally, these shouldn't be overwritten by subclasses.
3030
3031       "ast_string"
3032           Returns perl code representation of a variable.
3033
3034       "context"
3035           Used to create a "pseudo" context object that allows for
3036           portability of TT plugins, filters, and perl blocks that need a
3037           context object.  Uses the Template::Alloy::Context class.
3038
3039       "debug_node"
3040           Used to get debug info on a directive if DEBUG_DIRS is set.
3041
3042       "get_line_number_by_index"
3043           Used to turn string index position into line number
3044
3045       "interpolate_node"
3046           Used for parsing text nodes for dollar variables when interpolate
3047           is on.
3048
3049       "play_operator"
3050           Provided by the Operator role.  Allows for playing an operator AST.
3051
3052           See Template::Alloy::Operator for more details.
3053
3054       "apply_precedence"
3055           Provided by the Parse role.  Allows for parsed operator array to be
3056           translated to a tree based upon operator precedence.
3057
3058       "_process"
3059           Called by process and the PROCESS, INCLUDE and other directives.
3060
3061       "slurp"
3062           Reads contents of passed filename - throws file exception on error.
3063
3064       "split_paths"
3065           Used to split INCLUDE_PATH or other directives if an arrayref is
3066           not passed.
3067
3068       "tt_var_string"
3069           Returns a template toolkit representation of a variable.
3070
3071       "_vars"
3072           Return a reference to the current stash of variables.  This is
3073           currently only used by the pseudo context object and may disappear
3074           at some point.
3075

THANKS

3077       Thanks to Andy Wardley for creating Template::Toolkit.
3078
3079       Thanks to Sam Tregar for creating HTML::Template.
3080
3081       Thanks to David Lowe for creating Text::Tmpl.
3082
3083       Thanks to the Apache Velocity guys.
3084
3085       Thanks to Ben Grimm for a patch to allow passing a parsed document to
3086       the ->process method.
3087
3088       Thanks to David Warring for finding a parse error in HTE syntax.
3089
3090       Thanks to Carl Franks for adding the base ENCODING support.
3091

AUTHOR

3093       Paul Seamons <paul@seamons.com>
3094

LICENSE

3096       This module may be distributed under the same terms as Perl itself.
3097
3098
3099
3100perl v5.32.1                      2021-03-23                Template::Alloy(3)
Impressum