Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

*** empty log message ***

git-svn-id: svn://svn.tt2.org/tt/Template2/trunk@18 d5a88997-0a34-4036-9ed2-92fb5d660d91
  • Loading branch information...
commit e1ad1609f32c565ffcae50dd164548de9a1c2640 1 parent 9d806e6
Andy Wardley authored
439 Changes
@@ -87,7 +87,7 @@ New Language Features
87 87 template or enclosing block.
88 88
89 89 * New META directive allowing you to define metadata items for your
90   - template. These are attached to the compiled template and wrapped
  90 + templates. These are attached to the compiled template and wrapped
91 91 up as a Template::Document object. The 'template' variable is a
92 92 reference to the current parent document and metadata items may be
93 93 accessed directly. Of particular note is the fact that the
@@ -123,6 +123,16 @@ New Language Features
123 123 (e.g. PERL...END processes the block and filters the output into
124 124 Perl evaluation at runtime).
125 125
  126 +* Comments now only extend to the end of the current line.
  127 +
  128 + [%
  129 +
  130 +* The TAGS directive can now be used to switch tag styles by name.
  131 + Several new tag styles are defined (e.g. html, asp, php, mason).
  132 +
  133 + [% TAGS html %]
  134 + <!-- INCLUDE header -->
  135 +
126 136 * The output from any directive or block can now be captured and assigned to
127 137 a variable.
128 138
@@ -138,7 +148,8 @@ New Language Features
138 148 [% END %]
139 149
140 150 * The handling of complex expressions has been improved, permitting
141   - basic directives to contain logical shortcut operators, etc.
  151 + basic directives to contain logical shortcut operators, etc. All
  152 + binary operators now have the same precedence rules as Perl.
142 153
143 154 [% foo or bar %] # GET foo, or bar if foo is false (0/undef)
144 155 [% CALL func1 and func2 %] # func2 only called if func1 returns true
@@ -149,12 +160,27 @@ New Language Features
149 160
150 161 [% foo = bar ? baz : qux %]
151 162
  163 +* A leading '$' on a variable is now used to indicate pre-interpolation
  164 + of that element. This simplifies the syntax and makes it consistent
  165 + with double-quoted string interpolation and text block interpolation
  166 + via the INTERPOLATE flag. If you've been relying on the version 1
  167 + "feature" that ignores the leading '$' then you'll need to change your
  168 + templates to remove the '$' characters (except where you really want
  169 + them) or set the V1DOLLAR flag to 1 to revert to the version 1
  170 + behaviour. See the 'Gotchas' section below for more details.
  171 +
  172 + # version 1
  173 + [% hash.${key} %] [% hash.${complex.key} %]
  174 +
  175 + # version 2
  176 + [% hash.$key %] [% hash.${complex.key} %]
  177 +
152 178 * Various new pseudo-methods have been added for inspecting and manipulating
153 179 data. The full list now looks something like this:
154 180
155   - [% value.defined %] # value is defined
156   - [% value.length %] # length of string
157   - [% value.split(delimiter, limit) %] # split string as Perl does
  181 + [% var.defined %] # variable is defined
  182 + [% var.length %] # length of string
  183 + [% var.split(delimiter, limit) %] # split string as Perl does
158 184
159 185 [% hash.keys %] # return list of hash keys
160 186 [% hash.values %] # ditto hash values
@@ -171,67 +197,139 @@ New Language Features
171 197 Templates Compiled to Perl Code
172 198 -------------------------------
173 199
174   -* Templates are now compiled to Perl code, with credit and respect due
175   - to Doug Steinwand for providing an implementation around which the
176   - new parser was built. This brings a number of important benefits:
177   -
178   - - Speed and Memory Efficiency
179   -
180   - Version 1 used a list of opcodes to represent directives and
181   - lower-level operations. These were evaluated by the hideously
182   - contrived, and darkly sinister Template::Context::_evaluate()
183   - method. In version 2, all templates are parsed and rebuilt as
184   - Perl code. This is then evaluated and stored as a reference to a
185   - Perl sub-routine which can then be executed and re-executed
186   - significantly faster and with far less memory overhead.
187   -
188   - - Persistance.
189   -
190   - Once a template has been compiled to Perl code it can be saved to
191   - disk as a "compiled template" by defining the COMPILE_EXT option.
192   - This allows you to specify a filename extension (e.g. '.ttc')
193   - which is added to the template filename and used to create a new
194   - file containg the Perl code. Next time you use the template, even
195   - if you've shut down your program/server/computer in the mean time,
196   - the compiled template is there in a file as Perl code and is
197   - simply require()d and executed. It all happens significantly
198   - faster because there's no Template::Parser to run. In fact, if
199   - all your templates are "compiled" on disk then the
200   - Template::Parser and Template::Grammar modules won't even be
201   - loaded, further reducing startup time and memory consumption (the
202   - grammar file, in particular is rather large). The
203   - Template::Provider module handles the loading, caching and
204   - persistance of templates, and will examine file timestamps and
205   - re-compiled modified templates as required.
206   -
207   - - Flexibility.
208   -
209   - Because "compiled templates" are now nothing more than Perl
210   - sub-routines, you can use anyone or anything to generate them and
211   - run them all under the same roof. Different parser back-ends can
212   - generate Perl code optimised for speed or functionality, for example.
213   - Or different parsers can compile different template languages
214   - (PHP, ASP, Mason, roll-your-own, etc.) and run them alongside
215   - regular templates. Or if you don't trust a parser, you can wri
216   - even write your own Perl code and have your templates execute
217   - as fast as the code you can write.
218   -
219   -* Templates (i.e. sub-routines) now return their generated output,
220   - rather than sending it to $context->output(). This speeds things
221   - up and makes the code simpler, as well as allowing greater
222   - flexibility in how template sub-routines can work.
223   -
224   -* Exceptions (errors) are now raised via Perl's die() and caught by
225   - an enclosing eval { } block. Again, this simplifies the code generated
226   - and improves runtime efficiency.
227   -
228   -* The directives [% RETURN %] and [% STOP %] are now implemented as
229   - special case exceptions which are caught in the appropriate place
230   - and handled accordingly.
231   -
  200 +Templates are now compiled to Perl code, with credit and respect due
  201 +to Doug Steinwand for providing an implementation around which the
  202 +new parser was built. This brings a number of important benefits:
  203 +
  204 +* Speed and Memory Efficiency
  205 +
  206 + Version 1 used a list of opcodes to represent directives and
  207 + lower-level operations. These were evaluated by the hideously
  208 + contrived, and darkly sinister Template::Context::_evaluate()
  209 + method. In version 2, all templates are parsed and rebuilt as Perl
  210 + code. This is then evaluated and stored as a reference to a Perl
  211 + sub-routine which can then be executed and re-executed significantly
  212 + faster and with far less memory overhead.
  213 +
  214 +* Persistance.
  215 +
  216 + Once a template has been compiled to Perl code it can be saved to
  217 + disk as a "compiled template" by defining the COMPILE_EXT option.
  218 + This allows you to specify a filename extension (e.g. '.ttc') which
  219 + is added to the template filename and used to create a new file
  220 + containg the Perl code. Next time you use the template, even if
  221 + you've shut down your program/server/computer in the mean time, the
  222 + compiled template is there in a file as Perl code and is simply
  223 + require()d and executed. It all happens significantly faster
  224 + because there's no Template::Parser to run. In fact, if all your
  225 + templates are "compiled" on disk then the Template::Parser and
  226 + Template::Grammar modules won't even be loaded, further reducing
  227 + startup time and memory consumption (the grammar file, in particular
  228 + is rather large). The Template::Provider module handles the
  229 + loading, caching and persistance of templates, and will examine file
  230 + timestamps and re-compiled modified templates as required.
  231 +
  232 +* Flexibility.
  233 +
  234 + Because "compiled templates" are now nothing more than Perl
  235 + sub-routines, you can use anyone or anything to generate them and
  236 + run them all under the same roof. Different parser back-ends can
  237 + generate Perl code optimised for speed or functionality, for
  238 + example. Or different parsers can compile different template
  239 + languages (PHP, ASP, Mason, roll-your-own, etc.) and run them
  240 + alongside regular templates. Or if you don't trust a parser, you
  241 + can even write your own Perl code and have your templates execute as
  242 + fast as the code you can write.
  243 +
  244 +
  245 +Configuration Options
  246 +---------------------
232 247
233   -Miscellaneous Features
234   -----------------------
  248 +* Template blocks may be pre-defined using the new BLOCKS option. These
  249 + may be specified as template text or as references to sub-routines or
  250 + Template::Document objects.
  251 +
  252 + my $template = Template->new({
  253 + BLOCKS => {
  254 + header => '<html><head><title>[% title %]</title></head><body>',
  255 + footer => '</body></html>',
  256 + funky => sub { blah_blah($blah); return $some_text },
  257 + }
  258 + });
  259 +
  260 +* Automatic error handling can be provided with the ERROR option. This
  261 + allows you to specify a single template or hash array of templates which
  262 + should be used in the case of an uncaught exception being raised in the
  263 + a template. In other words, if something in one of your templates
  264 + throws a 'dbi' error then you can define an ERROR template to catch
  265 + this. The original template output is discarded and the ERROR template
  266 + processed in its place. PRE_PROCESS and POST_PROCESS templates (e.g.
  267 + header and footers) are left intact. This provides a particularly
  268 + useful high-level error handling abstraction where you simply create
  269 + templates to handle particular exceptions and provide the mapping
  270 + through the ERROR hash.
  271 +
  272 + my $template = Template->new({
  273 + ERROR => {
  274 + dbi => 'error/database.html', # DBI error
  275 + user.pwd => 'error/badpasswd.html', # invalid user password
  276 + user => 'user/index.html', # general 'user' handler
  277 + default => 'error/error.html', # default error template
  278 + }
  279 + });
  280 +
  281 +* The INCLUDE_PATH is now fully dynamic and can be changed at any time.
  282 + The new Template::Provider which manages the loading of template files
  283 + will correctly adapt to chahges in the INCLUDE_PATH and act accordingly.
  284 +
  285 +* The TEMPLATES option allows you to specify a list of one or more
  286 + Template::Provider object which will take responsibility for loading
  287 + templates. Each provider can have it's own INCLUDE_PATH, caching
  288 + options (e.g CACHE_SIZE) and so on. You can sub-class the
  289 + Template::Provider module to allow templates to be loaded from a
  290 + database, for example, and then define your new provider in the
  291 + TEMPLATES list. The providers are queried in order as a "Chain of
  292 + Responsiblity". Each may return a compiled template, raise an
  293 + error, or decline to serve the template and pass control onto the
  294 + next provider in line.
  295 +
  296 +* The CACHE_SIZE option defines a maximum number of templates that will
  297 + be cached by the provider. It is undefined by default, causing all
  298 + templates to be cached. A value of 0 disables caching altogether while
  299 + a positive integer defines a maximum limit. The cache (now built into
  300 + Template::Provider) is much smarter and will automatically reload and
  301 + compile modified source templates.
  302 +
  303 +* The Template::Provider cache can write compiled templates (e.g. Perl code)
  304 + to disk to create a persistant cache. The COMPILE_EXT may be used to
  305 + specify a filename extension (e.g. '.ttc') which is used to create
  306 + compiled template files. These compiled template files
  307 + can then be reloaded on subsequent invocations using via Perl's
  308 + require() (which is about as fast as it can get). The Template::Parser
  309 + and Template::Grammar modules are loaded on demand, so if all templates
  310 + have been pre-compiled then the modules don't get loaded at all. This
  311 + is a big win, given that Template::Grammar is the biggy.
  312 +
  313 +* The ABSOLUTE and RELATIVE options are now used to enable the loading of
  314 + template files (via INCLUDE or PROCESS) that are specifies with absolute
  315 + (e.g. /tmp/somefile) or relative (e.g. ../tmp/another) filenames. Both
  316 + are disabled by default.
  317 +
  318 +* The PLUGINS option is similar to TEMPLATES but allows you to specify
  319 + one or more plugin providers. These take responsibility for loading
  320 + and instantiating plugins. The Template::Plugins module is the default
  321 + provider and multiplexes requests out to other Template::Plugin::*
  322 + plugin modules.
  323 +
  324 +* The FILTERS option is the same but for providing filters. The
  325 + Template::Filters module is the default provider here.
  326 +
  327 +* The TOLERANT option can be used to tailor the behaviour of providers
  328 + (e.g. Template::Provider, Template::Plugins, Template::Filters) when
  329 + they encounter an error. By default, providers are not TOLERANT (0)
  330 + and will report all failures as errors. When TOLERANT is set to 1,
  331 + they will ignore errors and return STATUS_DECLINED to give the next
  332 + provider a chance to deliver a valid resource.
235 333
236 334 * The INTERPOLATE option is now automatically disabled within PERL and
237 335 RAWPERL blocks to prevent Perl $variables from being interpreted as
@@ -245,7 +343,7 @@ Miscellaneous Features
245 343 my $bar = 'another value';
246 344 # etc...
247 345 [% END %]
248   - no we're interpolating variables again, like $var
  346 + now we're interpolating variables again, like $var
249 347
250 348 * Added the TRIM option to automatically removed leading and trailing
251 349 whitespace from the output of templates and BLOCKs. This was suggested
@@ -253,14 +351,21 @@ Miscellaneous Features
253 351 moment. I'll check and fill in this **gap**, but thanks to him anwyay.
254 352
255 353
256   -
257 354 Plugins and Filters
258 355 -------------------
259 356
260 357 * Added the 'upper' and 'lower' filters for case folding text.
261 358
  359 +* Added the Date plugin, as provided by Thierry-Michel Barral.
  360 +
  361 +Tools
  362 +-----
  363 +
  364 +* Added the --define var=val option to ttree
  365 +
  366 +Gotchas
  367 +-------
262 368
263   -
264 369 * Bare CATCH blocks are no longer permitted and must be explicitly
265 370 scoped with a matching TRY. In most cases, this simply means adding
266 371 a [% TRY %] to the start of any templates that define CATCH blocks,
@@ -391,128 +496,95 @@ In addition to those changes, the main new features of the language are:
391 496 There are a number of other significant changes in the architecture
392 497 and implementation.
393 498
  499 +Other Enhancements and Internal Features
  500 +----------------------------------------
394 501
395   - * Local named BLOCK definitions are better behaved and don't permanently
396   - mask any real files. Currently, INCLUDE does not import BLOCKs, but
397   - PROCESS does (as per variables), although this may change slightly.
398   -
399   - * The Template::Stash object now encapsulates all the magical variable
400   - resolution code. Both simple and compound variables can be accessed
401   - or updated using the get() and set() methods, with all "variable magic"
402   - happening automatically.
403   -
404   - * The Template::Context object is now greatly simplified. This acts
405   - as a general interface to the Template Toolkit functionality, being
406   - a collection of the various other modules that actually implement
407   - the functionality (e.g. Template::Stash, Template::Provider,
408   - Template::Document, Template::Plugins, etc.)
409   -
410   - * The Template::Provider object provides a general facility for
411   - retrieving templates from disk (or other source), and if necessary
412   - compiling via a call to a Template::Parser helper object.
413   - Multiple Template::Provider objects may be specified as the
414   - TEMPLATES option to a Template::Context. These form a
415   - chain-of-command in which each successive provider is asked to
416   - fetch() a template and may return a compiled template, an error,
417   - or decline to service the request, thereby deferring to the next
418   - provider in the chain. The Template::Provider also handles
419   - caching of compiled templates and has many improvements over the
420   - version 1 Template::Cache, most significant of which is the
421   - ability to limit the cache to a maximum number of templates.
422   -
423   - * The Template::Parser object now compiles template text into Perl code
424   - and then evaluates it into a sub-routine reference using Perl's
425   - eval(). This is then wrapped up into a Template::Document object,
426   - including any metadata items and/or additional named BLOCKs defined
427   - in the input template.
428   -
429   - * The Template::Document object is a thin wrapper around a compiled
430   - template sub-routine. It provides a process() method for processing
431   - the template and a blocks() method for returning a reference to the
432   - hash array of any additional named BLOCKs defined in the original
433   - template text. An AUTOLOAD method returns values of metadata items,
434   - allowing a Template::Document reference to be used as the 'template'
435   - variable.
436   -
437   - * The Template::Service module provides a high-level service for
438   - processing templates, using an underlying Template::Context
439   - reference to access the toolkit functionality. PRE_PROCESS and
440   - POST_PROCESS templates may be specified which are added to all
441   - templates processed via this service. An ERROR template may also
442   - be specified, or as a reference to a hash array mapping error
443   - types to template names. This is then used to provide consistent
444   - and automatic error handling in response to uncaught errors thrown
445   - from templates. In such a case, the approporiate error template
446   - is processed in place of the original template. PRE_PROCESS and
447   - POST_PROCESS templates are added to the error template to maintain
448   - the expected consistency of the service. The Template::Service
449   - module may be sub-classed, or replaced by other modules to implement
450   - different template based services.
451   -
452   - * The Template::Plugins module is a special purpose provider variant
453   - for loading and instantiating plugins. Multiple plugin providers
454   - may be specified as the PLUGINS option to a context and these act
455   - in a chain-of-command as per the TEMPLATES providers.
456   -
457   - * The Template::Filters module is similar to Template::Plugins, but
458   - for providing access to filters. The FILTERS options may also
459   - contain multiple entries as above.
460   -
461   - * The Template::Base module defines a common base class for many of
462   - the toolkit modules. It implements shared functionality such as a
463   - constructor, error reporting and handling, etc. Modules are now
464   - much easier to sub-class, all using separate new() and _init()
465   - methods.
466   -
467   - * The Template::Config module (name may change) provides methods for
468   - loading and instantiating different Template Toolkit modules. Using
469   - this factory-based approach makes it far easier to change the default
470   - object class for a specific part of the toolkit. e.g.
  502 +* Templates (i.e. sub-routines) now return their generated output,
  503 + rather than sending it to $context->output(). This speeds things
  504 + up and makes the code simpler, as well as allowing greater
  505 + flexibility in how template sub-routines can work.
  506 +
  507 +* Exceptions are now raised via Perl's die() and caught by an
  508 + enclosing eval { } block. Again, this simplifies the code generated
  509 + and improves runtime efficiency. The [% RETURN %] and [% STOP %]
  510 + directives are now implemented as special case exceptions which are
  511 + caught in the appropriate place and handled accordingly.
  512 +
  513 +* Local named BLOCK definitions are better behaved and don't permanently
  514 + mask any real files. BLOCK definitions remain local to the template in
  515 + which they're defined, although they can be accessed from templates
  516 + INCLUDEd or PROCESSed from within. The PROCESS directive will export
  517 + defined BLOCKs to the caller (as with variables) whereas INCLUDE will
  518 + keep them "private".
  519 +
  520 +* The Template::Stash object now encapsulates all the magical variable
  521 + resolution code. Both simple and compound variables can be accessed
  522 + or updated using the get() and set() methods, with all variable binding
  523 + magic happening automatically.
  524 +
  525 +* The Template::Context object is now greatly simplified. This acts
  526 + as a general interface to the Template Toolkit functionality, being
  527 + a collection of the various other modules that actually implement
  528 + the functionality (e.g. Template::Stash, Template::Provider,
  529 + Template::Document, Template::Plugins, etc.)
  530 +
  531 +* The Template::Provider object provides a general facility for
  532 + retrieving templates from disk (or other source), and if necessary
  533 + compiling via a call to a Template::Parser helper object. Multiple
  534 + Template::Provider objects may be chained together, each with their
  535 + own caching options, and so on.
  536 +
  537 +* The Template::Parser object now compiles template text into Perl
  538 + code and then evaluates it into a sub-routine reference using Perl's
  539 + eval(). This is then wrapped up into a Template::Document object,
  540 + including any metadata items and/or additional named BLOCKs defined
  541 + in the input template.
  542 +
  543 +* The Template::Document object is a thin wrapper around a compiled
  544 + template sub-routine. It provides a process() method for processing
  545 + the template and a blocks() method for returning a reference to the
  546 + hash array of any additional named BLOCKs defined in the original
  547 + template text. An AUTOLOAD method returns values of metadata items,
  548 + allowing a Template::Document reference to be used as the 'template'
  549 + variable.
  550 +
  551 +* The Template::Service module provides a high-level service for
  552 + processing templates, allowing PRE_PROCESS and POST_PROCESS templates
  553 + to be specified along with an ERROR handling hash.
  554 +
  555 +* The Template::Base module defines a common base class for many of
  556 + the toolkit modules. It implements shared functionality such as a
  557 + constructor, error reporting and handling, etc. Modules are now
  558 + much easier to sub-class, all using separate new() and _init()
  559 + methods.
  560 +
  561 +* The Template::Config module provides methods for loading and
  562 + instantiating different Template Toolkit modules. Using this
  563 + factory-based approach makes it far easier to change the default
  564 + object class for a specific part of the toolkit. e.g.
471 565
472 566 use Template;
473 567 use Template::Config;
474 568
475   - $Template::Config::PARSER = 'MyTemplate::MyParser';
  569 + $Template::Config::PARSER = 'MyOrg::Template::MyParser';
476 570
  571 + # $tt object will create and use a MyOrg::Template::MyParser
  572 + # object as PARSER
477 573 my $tt = Template->new({ ... })
478   - ...
479   -
480   - # $tt object will use a MyTemplate::MyParser object for PARSER
481   -
482   - * The Template module remains, as it ever was, a simple front-end
483   - to the Template Toolkit. This creates a single Template::Service
484   - to which it delegates control for processing templates. Output
485   - is returned according to the OUTPUT options specified for the module
486   - and/or any output option passed explicitly to the process() method.
487   -
488   -There's still some debug code in the wrong places, and some things that
489   -need to be tidied up to boost performance. In particular, the parser
490   -goes out of its way to pretty-print generated Perl code (for the sake of
491   -easy debugging - set $Template::Parser::DEBUG to see the generated code)
492   -so expect it to run a little sluggish. Once the templates are compiled,
493   -they should execute measurably faster than before but unless you're
494   -running a persistant server, you probably won't notice how fast they
495   -run because the process time is overshadowed by the parse time.
496   -I did some very rough benchmarks and had it processing templates
497   -around 2 - 3 times faster than version 1. This still falls short of
498   -what's possible, but for now it represents a good start. :-)=
499   -
500   -
501 574
  575 +* The Template module remains, as it ever was, a simple front-end to
  576 + the Template Toolkit. This creates a single Template::Service to
  577 + which it delegates control for processing templates. Output is
  578 + returned according to the OUTPUT options specified for the module
  579 + and/or any output option passed explicitly to the process() method.
502 580
503 581
504   -This list isn't complete - it's more of a reminder to me at the moment.
505 582 ----------------------------------------------------------------------
506 583
507   -* All directives now compile to Perl code and run
508   -
509 584 * USERDIR and USERBLOCK are currently not supported (and may never be,
510 585 given that they're experimental features of TT1 anyway).
511 586
512   -* Fixed parser to not INTERPOLATE within PERL blocks.
513   -
514   -* Added TAG_STYLEs html, mason, asp and php, as provided by some kind
515   - dude on the list whose names escapes me at the moment. Changed default
  587 +* Changed default TAGS to
516 588 to [% %] and changed names of some others
517 589
518 590 * Changed how error/return values should be returned from user code.
@@ -520,21 +592,16 @@ This list isn't complete - it's more of a reminder to me at the moment.
520 592
521 593 die $error_msg;
522 594 die Template::Exception->new($type, $info);
523   -
524   -* All binary operators have the same precedence as Perl.
525   -
  595 + $context->throw($msg);
  596 + $context->throw($type, $info);
  597 + $context->throw($exception);
  598 +
526 599 * Added '-- use name --' to Template::Test to switch between multiple
527 600 Template objects specified as a list reference as the second arg
528 601 to test_expect()
529 602
530   -* must explicitly use iterator if you want to access .first .last, etc.
531   - in a loop.
532   -
533   -* note that parser is not loaded at startup time.
534   -
535   -
536   -
537   -
  603 +* $Template::Directive::While::MAXITER is now
  604 + $Template::Directive::WHILE_MAX
538 605
539 606 changes from alpha to beta
540 607 --------------------------
20 TODO
... ... @@ -1,3 +1,4 @@
  1 +
1 2 Pending
2 3 -------
3 4
@@ -12,6 +13,9 @@ Pending
12 13
13 14 Misc
14 15 ----
  16 +* No \refs.
  17 +
  18 +* faster parser back end which bypasses the stash, based on Doug's code.
15 19
16 20 * Fix Plugin.pm - it's still basically v1 code and much can be discarded
17 21
@@ -76,22 +80,9 @@ Misc
76 80
77 81 * Template::Context include()/process() should work with raw CODE refs.
78 82
79   -* Complete Template::Service error handling.
80   -
81 83 * any OUTPUT_PATH in Template.pm should be prepended to OUTPUT when OUTPUT
82 84 is a file name.
83 85
84   -* add new TAG_STYLE entries and allows [% TAGS style %] directive
85   -
86   -* Template::Document's handling of STOP needs looking at
87   -
88   -* ERROR may be a single value instead of a hash (default)
89   -
90   -* fixed if/elsif generation
91   -
92   -* optimised FOREACH to only use an iterator if already so (but note that
93   - this got changed again later)
94   -
95 86 * cleaned up Template::Iterator. Now derived from Template::Base.
96 87 Removed ACTION and ORDER now that they are supported as list pseudo
97 88 methods in the Stash LIST_OPS.
@@ -117,9 +108,6 @@ Misc
117 108
118 109 * fix \@ quoting (and others) in Directive (Perrin reported / Chuck patched)
119 110
120   -* BLOCK caching is still a little messy - it works, but with belt and braces.
121   - Need to finalise behaviour wrt importing BLOCK defs via INCLUDE/PROCESS.
122   -
123 111 * Added Date plugin and test, as provided by Thierry-Michel Barral and abw.
124 112
125 113 * Integrate changes to Template::Test from version 1.07 and beyond. Now
18 bin/ttree
@@ -83,6 +83,11 @@ my %ttopts = $config->varlist('^template_', 1);
83 83 my %ucttopts;
84 84 @ucttopts{ map { uc } keys %ttopts } = values %ttopts;
85 85
  86 +# get all template variable definitions
  87 +my $replace = $config->get('define');
  88 +print "replace hash: ", join(', ', map { "$_ => $replace->{ $_ }"}
  89 + keys %$replace), "\n";
  90 +
86 91 # now create complete parameter hash for creating template processor
87 92 my $ttopts = {
88 93 %ucttopts,
@@ -92,10 +97,6 @@ my $ttopts = {
92 97 # ERROR => \&error,
93 98 };
94 99
95   -my $ttdata = {
96   - # TODO: this is lava flow...
97   - 'sys' => { 'time' => sub { time } },
98   -};
99 100
100 101 sub error {
101 102 my $error = join('', @_);
@@ -151,7 +152,7 @@ if (@ARGV) {
151 152 # explicitly process files specified on command lines
152 153 foreach my $file (@ARGV) {
153 154 print " + $file\n" if $verbose;
154   - $template->process("$file", $ttdata, $file)
  155 + $template->process("$file", $replace, $file)
155 156 || print " ! ", $template->error(), "\n";
156 157 }
157 158 }
@@ -286,7 +287,7 @@ sub process_file {
286 287
287 288 # process file
288 289 unless ($dryrun) {
289   - $template->process("./$file", $ttdata, $file)
  290 + $template->process("./$file", $replace, $file)
290 291 || print(" ! ", $template->error(), "\n");
291 292
292 293 if ($preserve) {
@@ -307,7 +308,8 @@ sub read_config {
307 308 my $file = shift;
308 309
309 310 my $config = AppConfig->new({
310   - ERROR => sub { die @_, "\ntry `$NAME --help'\n" } },
  311 + GLOBAL => { ARGCOUNT => 1 },
  312 + ERROR => sub { die @_, "\ntry `$NAME --help'\n" } },
311 313 'help|h' => { ACTION => \&help },
312 314 'src|s=s' => { EXPAND => EXPAND_ALL },
313 315 'dest|d=s' => { EXPAND => EXPAND_ALL },
@@ -319,6 +321,7 @@ sub read_config {
319 321 'preserve|p' => { DEFAULT => 0 },
320 322 'all|a' => { DEFAULT => 0 },
321 323 'debug|dbg' => { DEFAULT => 0 },
  324 + 'define=s%',
322 325 'ignore=s@',
323 326 'copy=s@',
324 327 'accept=s@',
@@ -484,6 +487,7 @@ File search specifications (all may appear multiple times):
484 487 --accept=REGEX Process only files matching REGEX
485 488
486 489 Additional options to set Template Toolkit configuration items:
  490 + --define var=value Define template variable
487 491 --interpolate Interpolate '\$var' references in text
488 492 --case Case sensitivity of reserved words
489 493 --eval_perl Evaluate [% PERL %] ... [% END %] code blocks
4 lib/Template/Directive.pm
@@ -453,9 +453,9 @@ sub while {
453 453 return <<EOF;
454 454
455 455 # WHILE
456   -$OUTPUT do {
  456 +do {
457 457 my \$failsafe = $WHILE_MAX;
458   - while (\$failsafe-- && ($expr)) {
  458 + while (--\$failsafe && ($expr)) {
459 459 $block
460 460 }
461 461 die "WHILE loop terminated (> $WHILE_MAX iterations)\\n"
2  lib/Template/Provider.pm
@@ -191,7 +191,7 @@ sub _init {
191 191 $self->{ SIZE } = $size;
192 192 $self->{ INCLUDE_PATH } = $path;
193 193 $self->{ DELIMITER } = $dlim;
194   - $self->{ PREFIX } = $params->{ PREFIX };
  194 +# $self->{ PREFIX } = $params->{ PREFIX };
195 195 $self->{ ABSOLUTE } = $params->{ ABSOLUTE } || 0;
196 196 $self->{ RELATIVE } = $params->{ RELATIVE } || 0;
197 197 $self->{ TOLERANT } = $params->{ TOLERANT } || 0;
23 t/README
@@ -13,6 +13,7 @@ context.t Template::Context module
13 13 datafile.t Datafile plugin (Template::Plugin::Datafile)
14 14 directive.t Directive layout, chomping, comments, etc.
15 15 document.t Template::Document module
  16 +dom.t XML::DOM plugin (Template::Plugin::XML::DOM)
16 17 evalperl.t Evaluation of PERL and RAWPERL blocks
17 18 exception.t Template::Exception module
18 19 filter.t FILTER directive and various filters
@@ -24,33 +25,38 @@ list.t List definition and access via various methods
24 25 object.t Binding objects to template variables
25 26 output.t OUTPUT_PATH and OUTPUT options
26 27 provider.t Template::Provider module
  28 +rss.t XML::RSS plugin (Template::Plugin::XML::RSS)
  29 +service.t Template::Service module
27 30 stop.t STOP directive and throwing 'stop' exception
28 31 table.t Table plugin (Template::Plugin::Table)
29 32 tags.t TAGS directive
30 33 url.t URL plugin (Template::Plugin::URL)
31 34 vars.t Variable usage and GET / SET / CALL / DEFAULT directives
32 35 varsv1.t As above, using version 1 handling of leading '$'
  36 +while.t WHILE directive
33 37
34 38 TODO:
35 39
36 40 if.t IF / UNLESS / ELSEIF / ELSE directives
37 41 parser.t Template::Parser module
38   -service.t Template::Service module
39 42 switch.t SWITCH / CASE directives
40 43 plugins.t Template::Plugins provider module
41 44 template.t Template module
42 45 try.t TRY / THROW / CATCH / FINAL directives
43 46 code.t binding code to variables (or covered in vars.t?)
44   -dom.t copy from v1
45   -rss.t copy from v1
46 47
47   -literal : 'foo' = bar
48   -directive + multi + comment + block -> directives
49   -interpolate options
50   -break into while/foreach/if, etc.
51   -comments
  48 +literal : 'foo' = bar, @ characters, escaping, etc.
52 49 named params with object.t and code.t
53 50
  51 +===
  52 +anonblock
  53 +macro
  54 +cache
  55 +recursion << OPTION
  56 +return/stop/etc
  57 +
  58 +
  59 +
54 60 format => plugins
55 61 -------------------------------
56 62
@@ -123,3 +129,4 @@ ok vars merge of many tests
123 129 ok varsv1 ditto for VERSION => 1 compatability
124 130 fix while mainly ok, but broken due to (a = b) not working
125 131
  132 +
5 t/binop.t
@@ -130,6 +130,11 @@ yes
130 130 -- expect --
131 131 yes
132 132
  133 +-- test --
  134 +[% "yes" UNLESS no %]
  135 +-- expect --
  136 +yes
  137 +
133 138
134 139 -- test --
135 140 [% IF ! yes %]
13 t/block.t
@@ -30,6 +30,8 @@ my $ttcfg = {
30 30 INCLUDE_PATH => [ qw( t/test/lib test/lib ) ],
31 31 POST_CHOMP => 1,
32 32 BLOCKS => {
  33 + header => '<html><head><title>[% title %]</title></head><body>',
  34 + footer => '</body></html>',
33 35 block_a => sub { return 'this is block a' },
34 36 block_b => sub { return 'this is block b' },
35 37 },
@@ -74,3 +76,14 @@ This is block 1, defined in blockdef, a is alpha
74 76 this is block a
75 77 this is block b
76 78
  79 +-- test --
  80 +[% INCLUDE header
  81 + title = 'A New Beginning'
  82 ++%]
  83 +A long time ago in a galaxy far, far away...
  84 +[% PROCESS footer %]
  85 +
  86 +-- expect --
  87 +<html><head><title>A New Beginning</title></head><body>
  88 +A long time ago in a galaxy far, far away...
  89 +</body></html>
75 t/case.t
... ... @@ -0,0 +1,75 @@
  1 +#============================================================= -*-perl-*-
  2 +#
  3 +# t/case.t
  4 +#
  5 +# Test the CASE sensitivity option.
  6 +#
  7 +# Written by Andy Wardley <abw@kfs.org>
  8 +#
  9 +# Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
  10 +# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
  11 +#
  12 +# This is free software; you can redistribute it and/or modify it
  13 +# under the same terms as Perl itself.
  14 +#
  15 +# $Id$
  16 +#
  17 +#========================================================================
  18 +
  19 +use strict;
  20 +use lib qw( ./lib ../lib );
  21 +use Template::Test;
  22 +$^W = 1;
  23 +
  24 +$Template::Test::DEBUG = 0;
  25 +
  26 +ok(1);
  27 +
  28 +my $config = {
  29 + CASE => 1,
  30 + POST_CHOMP => 1,
  31 +};
  32 +
  33 +test_expect(\*DATA, $config, callsign());
  34 +
  35 +__DATA__
  36 +-- test --
  37 +[% include = a %]
  38 +[% for = b %]
  39 +i([% include %])
  40 +f([% for %])
  41 +-- expect --
  42 +i(alpha)
  43 +f(bravo)
  44 +
  45 +-- test --
  46 +[% IF a AND b %]
  47 +good
  48 +[% ELSE %]
  49 +bad
  50 +[% END %]
  51 +-- expect --
  52 +good
  53 +
  54 +-- test --
  55 +# 'and', 'or' and 'not' can ALWAYS be expressed in lower case, regardless
  56 +# of CASE sensitivity option.
  57 +[% IF a and b %]
  58 +good
  59 +[% ELSE %]
  60 +bad
  61 +[% END %]
  62 +-- expect --
  63 +good
  64 +
  65 +-- test --
  66 +[% include = a %]
  67 +[% include %]
  68 +-- expect --
  69 +alpha
  70 +
  71 +
  72 +
  73 +
  74 +
  75 +
10 t/directive.t
@@ -298,3 +298,13 @@ this is block foo
298 298 this is block bar
299 299 end
300 300
  301 +-- start --
  302 +[% r; r = s; "-"; r %].
  303 +-- expect --
  304 +romeo-sierra.
  305 +
  306 +-- test --
  307 +[% IF a; b; ELSIF c; d; ELSE; s; END %]
  308 +-- expect --
  309 +bravo
  310 +
122 t/while.t
... ... @@ -0,0 +1,122 @@
  1 +#============================================================= -*-perl-*-
  2 +#
  3 +# t/while.t
  4 +#
  5 +# Test the WHILE directive
  6 +#
  7 +# Written by Andy Wardley <abw@kfs.org>
  8 +#
  9 +# Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
  10 +# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
  11 +#
  12 +# This is free software; you can redistribute it and/or modify it
  13 +# under the same terms as Perl itself.
  14 +#
  15 +# $Id$
  16 +#
  17 +#========================================================================
  18 +
  19 +use strict;
  20 +use lib qw( ./lib ../lib );
  21 +use Template::Test;
  22 +use Template::Parser;
  23 +use Template::Directive;
  24 +$^W = 1;
  25 +
  26 +$Template::Test::DEBUG = 0;
  27 +#$Template::Parser::DEBUG = 1;
  28 +
  29 +# set low limit on WHILE's maximum iteration count
  30 +$Template::Directive::WHILE_MAX = 100;
  31 +
  32 +my $config = {
  33 + INTERPOLATE => 1,
  34 + POST_CHOMP => 1,
  35 +};
  36 +
  37 +my @list = ( 'x-ray', 'yankee', 'zulu', );
  38 +my @pending;
  39 +my $replace = {
  40 + 'a' => 'alpha',
  41 + 'b' => 'bravo',
  42 + 'c' => 'charlie',
  43 + 'd' => 'delta',
  44 + 'dec' => sub { --$_[0] },
  45 + 'inc' => sub { ++$_[0] },
  46 + 'reset' => sub { @pending = @list; "Reset list\n" },
  47 + 'next' => sub { shift @pending },
  48 + 'true' => 1,
  49 +};
  50 +
  51 +test_expect(\*DATA, $config, $replace);
  52 +
  53 +__DATA__
  54 +before
  55 +[% WHILE bollocks %]
  56 +do nothing
  57 +[% END %]
  58 +after
  59 +-- expect --
  60 +before
  61 +after
  62 +
  63 +-- test --
  64 +Commence countdown...
  65 +[% a = 10 %]
  66 +[% WHILE a %]
  67 +[% a %]..[% a = dec(a) %]
  68 +[% END +%]
  69 +The end
  70 +-- expect --
  71 +Commence countdown...
  72 +10..9..8..7..6..5..4..3..2..1..
  73 +The end
  74 +
  75 +-- test --
  76 +[% reset %]
  77 +[% WHILE (item = next) %]
  78 +item: [% item +%]
  79 +[% END %]
  80 +-- expect --
  81 +Reset list
  82 +item: x-ray
  83 +item: yankee
  84 +item: zulu
  85 +
  86 +-- test --
  87 +[% reset %]
  88 +[% WHILE (item = next) %]
  89 +item: [% item +%]
  90 +[% BREAK IF item == 'yankee' %]
  91 +[% END %]
  92 +Finis
  93 +-- expect --
  94 +Reset list
  95 +item: x-ray
  96 +item: yankee
  97 +Finis
  98 +
  99 +-- test --
  100 +[% reset %]
  101 +[% "* $item\n" WHILE (item = next) %]
  102 +-- expect --
  103 +Reset list
  104 +* x-ray
  105 +* yankee
  106 +* zulu
  107 +
  108 +-- test --
  109 +[% TRY %]
  110 +[% WHILE true %].[% END %]
  111 +[% CATCH +%]
  112 +error: [% error.info %]
  113 +[% END %]
  114 +-- expect --
  115 +...................................................................................................
  116 +error: WHILE loop terminated (> 100 iterations)
  117 +
  118 +
  119 +
  120 +
  121 +
  122 +

0 comments on commit e1ad160

Please sign in to comment.
Something went wrong with that request. Please try again.