Text::Template::Library - a derived class of Text::Template
use Text::Template::Library; my $tmpl=Text::Template::Library->new(...); $tmpl->fill_in(...); in the template: { define macro1 } macro text { /define } ... { define macro2 } macro text { /define } ... { fill_in_module('macro2') }
I have used Text::Template for several years in different projects. Allways I have missed the possibility to create macros. For example suppose this template:
Text::Template
<table> [% for (@rows) { $OUT.="<<EOR"; <tr>...</tr> EOR } %] </table>
This works perfectly well but all my HTML editors get confused by the <<EOR construct. One solution would be to create a new template for the table row and use it:
<<EOR
<table> [% for (@rows) { $OUT.=fill_in_file('/path/to/row.tmpl'); } %] </table>
But that would mean to have hundreds of small files laying about.
Text::Template::Library allows you to include these subtemplates in the main template:
Text::Template::Library
[% define row %] <tr>...</tr> [% /define %] <table> [% for (@rows) { $OUT.=fill_in_module('row'); } %] </table>
To make this module work with Text::Template as base class I had to enhance it a bit. I have tried to contact the author M-J. Dominus several times to get my patches into Text::Template but never got a reply. In the end I decided to include a renamed and patched version of Text::Template 1.45 with this distribution. It is named Text::Template::Base. For more information about the changes see "Text::Template patches" below.
So, strictly speaking Text::Template::Library is not anymore a derived class of Text::Template but of Text::Template::Base.
Text::Template::Base
Other than with Text::Template::Base custom delimiters must be passed to the new() method. Passing them to fill_in() is not supported. Further, SAFE compartments are not (yet) supported.
new()
fill_in()
SAFE
The Text::Template::Library module inherits from Text::Template::Base. It overrides 2 methods, _acquire_data and fill_in. The first one reads the template and converts it to type STRING. After that is done our own _acquire_data greps out all parts of the template that are included in a DEFINE.../DEFINE sequence.
_acquire_data
fill_in
STRING
DEFINE.../DEFINE
The DEFINE statement consists of the current opening delimiter followed by literally one space (except newline), the string define, again one space (except newline), the name of the macro that must match ^\w+$, another space (except newline) and the closing delimiter. For example:
DEFINE
define
^\w+$
{ define name } # assuming default delimiters
or
[% define name %] # assuming DELIMITERS=>[qw/[% %]/]
The /DEFINE statement accordingly consists of the opening delimiter followed by one space, the string /define, another space and the closing delimiter.
/DEFINE
/define
White spaces including newlines following the closing /DEFINE statement are cut out of the template. So subsequent definitions like these:
{ define m1 } ... { /define } { define m2 } ... { /define }
do not create additional white spaces (newlines) in the main template. Otherwise you would have to write that this way:
{ define m1 } ... { /define }{ define m2 } ... { /define }
Also, white spaces up to the first newline (including) following the opening DEFINE statement are cut out. Hence, you can write
{ define m1 } ... { /define }
instead of
{ define m1 }... { /define }
The subtemplates are created as Text::Template::Base objects not Text::Template::Library objects. This made the parsing process a lot simpler. But it denies nesting of DEFINE statements.
Subtemplates are evaluated in the same package as the parent template. OUTPUT, EVALCACHE, BROKEN, BROKEN_ARG, PREPEND and FILENAME settings are also passed from the parent template to subtemplates.
OUTPUT
EVALCACHE
BROKEN
BROKEN_ARG
PREPEND
FILENAME
creates a Text::Template::Library object.
evaluates the template. Almost all parameters for Text::Template::Base::fill_in are supported except DELIMITERS (which must be passed to new()) and SAFE.
Text::Template::Base::fill_in
DELIMITERS
Prior to calling Text::Template::Base::fill_in this method localizes $Text::Template::Library::T and stores there the current template.
$Text::Template::Library::T
This variable can be used in subtemplates directly or indirectly via fill_in_module().
fill_in_module()
returns the compiled subtemplate named $name. The subtemplate is a Text::Template::Base object, not Text::Template::Library.
$name
evaluates the subtemplate $name. @params are passed to Text::Template::Base::fill_in.
@params
Unlike Text::Template::Base::fill_in this method throws an exception if there was an error. So, it can be used in combination with OUTPUT, see Text::Template::Base.
If the OUTPUT option was given to the parent template library returns an empty string on success, otherwise the computed string.
library
In templates you can use it this way:
$Text::Template::Library::T->library($name, @params);
Shortcut for
to be used in templates.
But calling
Text::Template::Library::fill_in_module(...)
is not much of a shortcut. To make it work normally you can import it into the package in which the template is evaluated:
{ package Q; use Text::Template::Library qw/fill_in_module/; } $tmpl->fill_in(PACKAGE=>'Q', ...);
or even simpler:
local *Q::call_module=\&Text::Template::Library; $tmpl->fill_in(PACKAGE=>'Q', ...);
This way you can use call_module() like fill_in_module() in your templates.
call_module()
fill_in_module on demand.
fill_in_module
While working on the module I have dicovered a few bugs in Text::Template 1.45. Further, some improvements were made. You'll find all patches in the patches directory. For more information see the doc.diff patch.
patches
I have sent these patches to the author of Text::Template, Mark Jason Dominus but haven't yet received an answer.
None of my changes should break existing code working with Text::Template 1.45.
Please apply all the patches to the Text::Template distribution prior to running make test with this distribution.
make test
The patches are applied in this order:
cd Text-Template-1.45 cp /path/to/Text-Template-Library-0.01/patches/*.diff . patch -p0 <fi_ofn.diff patch -p0 <evalcache.diff patch -p0 <set_lineno.diff patch -p0 <filename.diff patch -p0 <newline_in_delimiter.diff patch -p0 <doc.diff patch -p0 <local_underscore.diff make test make install
Normally you won't want to use this module directly. See TX for a more convenient way.
Torsten Foertsch, <torsten.foertsch@gmx.net>
Copyright (C) 2008-2009 by Torsten Foertsch
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
To install Text::Template::Library, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Template::Library
CPAN shell
perl -MCPAN -e shell install Text::Template::Library
For more information on module installation, please visit the detailed CPAN module installation guide.