The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Template-Simple-0.49_05
River stage three • 4 direct dependents • 264 total dependents
2 ++
/ Text::Template::Simple

NAME

Text::Template::Simple - Simple text template engine

SYNOPSIS

   use Text::Template::Simple;
   my $template = Text::Template::Simple->new;
   my $tmp      = q~
   <%
      my %p = @_;
   %>
   
   <%=$p{str}%> : <%=scalar localtime time%>
   
   ~;
   print $template->compile($tmp, [str => 'Time now']);

DESCRIPTION

This is a simple template module. There is no extra template language. Instead, it uses Perl as a template language. Templates can be cached on disk or inside the memory via internal cache manager.

SYNTAX

Template syntax is very simple. There are few kinds of delimiters: code blocks (<% %>), self-printing blocks (<%= %>), escaped delimiters (<%! %>) and static include directive (<%+ %>):

   <%
      my @foo = qw(bar baz);
      foreach my $x (@foo) {
   %>
   Element is <%= $x %>
   <% } %>

do not directly use print() statements, since they'll break the code. Use <%= %> blocks. Delimiters can be altered:

   $template = Text::Template::Simple->new(
      delimiters => [qw/<?perl ?>/],
   );

then you can use them inside templates:

   <?perl
      my @foo = qw(bar baz);
      foreach my $x (@foo) {
   ?>
   Element is <?perl= $x ?>
   <?perl } ?>

If you want to include a text or html file, you can use the static include directive:

   <%+ my_other.html %>
   <%+ my_other.txt  %>

Included files won't be parsed and included statically.

Escaping Delimiters

If you have to build templates like this:

   Test: <%abc>

or this:

   Test: <%abc%>

This will result with a template compilation error. You have to use the delimiter escape command !:

   Test: <%!abc>
   Test: <%!abc%>

Those will be compiled as:

   Test: <%abc>
   Test: <%abc%>

Alternatively, you can change the default delimiters to solve this issue. See the "delimiters" option for "new" for more information on how to do this.

Template parameters

You can fetch parameters (passed to compile) in the usual perl way:

   <%
      my $foo = shift;
      my %bar = @_;
   %>
   Baz is <%= $bar{baz} %>

Special Variables

There is a special variable inside all templates. You must not define a variable with the same name inside templates or alter it's name before "compile".

Output Buffer Variable

Default name is $OUT. Output will be collected inside this variable and then returned. Works transparent, and you don't have to touch it manually.

METHODS

new

Creates a new template object and can take several parameters.

delimiters

Must be an array ref containing the two delimiter values: the opening delimiter and the closing delimiter:

   $template = Text::Template::Simple->new(
      delimiters => ['<?perl', '?>'],
   );

Default values are <% and %>.

faker

Compiled templates will have two special variables. The output is buffered inside a hidden variable named $OUT. You can alter the name of this variable if you pass a faker parameter:

   $template = Text::Template::Simple->new(
      faker => '$___this_does_not_exist',
   );

cache

Pass this with a true value if you want the cache feature. In-memory cache will be used unless you also pass a "cache_dir" parameter.

cache_dir

If you want disk-based cache, set this parameter to a valid directory path. You must also set "cache" to a true value.

resume

If has a true value, the die()able code fragments will not terminate the compilation of remaining parts, the compiler will simply resume it's job. However, enabling this may result with a performance penalty if cache is not enabled. If cache is enabled, the performance penalty will show itself after every compilation process (upto 2x slower).

This option is currently experimental and uses more resources. Only enable it for debugging.

CAVEAT: <% use MODULE %> directives won't resume.

strict

If has a true value, the template will be compiled under strict. Enabled by default.

safe

Set this to a true value if you want to execute the template code in a safe compartment. Disabled by default and highly experimental. This option can also disable some template features.

If you want to enable some unsafe conditions, you have to define Text::Template::Simple::Compiler::Safe::permit sub in your controller code and return a list of permitted opcodes inside that sub:

   sub Text::Template::Simple::Compiler::Safe::permit {
      my $class = shift;
      return qw(:default :subprocess); # enable backticks and system
   }

If this is not enough for you, you can define the safe compartment all by yourself by defining Text::Template::Simple::Compiler::Safe::object:

   sub Text::Template::Simple::Compiler::Safe::object {
      require Safe;
      my $safe = Safe->new('Text::Template::Simple::Dummy');
      $safe->permit(':browse');
      return $safe;
   }

:default, require and caller are enabled opcodes, unless you define your own. You have to disable strict option to disable require opcode. Disabling caller will also make your require/use calls die in perl 5.9.5 and later.

See Safe and especially Opcode for opcode lists and other details.

This is a string containing global elements (global to this particular object) for templates. You can define some generally accessible variables with this:

   $template = Text::Template::Simple->new(
      header => q~ my $foo = "bar"; ~,
   );

and then you can use it (without defining) inside any template that is compiled with $template object:

   Foo is <%=$foo%>

add_args

ARRAYref. Can be used to add a global parameter list to the templates.

   $template = Text::Template::Simple->new(
      add_args => [qw(foo bar baz)],
   );

and then you can fetch them inside any template that is compiled with $template object:

   <%
      my $foo = shift;
      my $bar = shift;
      my $baz = shift;
   %>
   Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>

But it'll be logical to combine it with header parameter:

   $template = Text::Template::Simple->new(
      header   => q~my $foo = shift;my $bar = shift;my $baz = shift;~,
      add_args => [qw(foo bar baz)],
   );

and then you can use it inside any template that is compiled with $template object without manually fetching all the time:

   Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>

Can be useful, if you want to define a default object:

   $template = Text::Template::Simple->new(
      header   => q~my $self = shift;~,
      add_args => [$my_default_object],
   );

and then you can use it inside any template that is compiled with $template object without manually fetching:

   Foo is <%= $self->{foo} %>. Test: <%= $self->method('test') %>

warn_ids

If enabled, the module will warn you about compile steps using template ids. You must both enable this and the cache. If cache is disabled, no warnings will be generated.

fix_uncuddled

If you are using uncuddled elses/elsifs (which became popular after Damian Conway' s PBP Book) in your templates, this will break the parser. If you supply this parameter with a true value, the parser will reformat the data with cuddled versions before parsing it.

iolayer

This option does not have any effect under perls older than 5.8.0. Set this to utf8 (no initial colon) if your I/O is UTF-8. Not tested with other encodings.

stack

This option enables caller stack tracing for templates. The generated list is sent to warn. So, it is possible to capture this data with a signal handler. Available options are:

   string
   html_comment
   html_table
   text_table

html_comment is the same as string except that it also includes HTML comment markers. text_table needs the optional module Text::Table.

This option is also available to all templates as a function named stack for individual stack dumping. But, currently this interface is not documented.

compile DATA [, FILL_IN_PARAM, OPTIONS]

Compiles the template you have passed and manages template cache, if you've enabled cache feature. Then it returns the compiled template. Accepts three different types of data as the first parameter; a reference to a filehandle (GLOB), a string or a file path (path to the template file).

First parameter (DATA)

The first parameter can take three different values; a filehandle, a string or a file path. Distinguishing filehandles are easy, since they'll be passed as a reference (but see the bareword issue below). So, the only problem is distinguishing strings and file paths. compile first checks if the string length is equal or less than 255 characters and then tests if a file with this name exists. If all these tests fail, the string will be treated as the template text.

File paths

You can pass a file path as the first parameter:

   $text = $template->compile('/my/templates/test.tmpl');

Strings

You can pass a string as the first parameter:

   $text = $template->compile(q~
   <%for my $i (0..10) {%>
      counting <%=$i%>...
   <%}%>
   ~);

Filehandles

GLOBs must be passed as a reference. If you are using bareword filehandles, be sure to pass it's reference or it'll be treated as a file path and your code will probably die:

   open MYHANDLE, '/path/to/foo.tmpl' or die "Error: $!";
   $text = $template->compile(\*MYHANDLE); # RIGHT.
   $text = $template->compile( *MYHANDLE); # WRONG. Recognized as a file path
   $text = $template->compile(  MYHANDLE); # WRONG. Ditto. Will die under strict

or use the standard IO::File module:

   use IO::File;
   my $fh = IO::File->new;
   $fh->open('/path/to/foo.tmpl', 'r') or die "Error: $!";
   $text = $template->compile($fh);

or you can use lexicals inside open if you don't care about compatibility with older perl:

   open my $fh, '/path/to/foo.tmpl' or die "Error: $!";
   $text = $template->compile($fh);

Filehandles will be automatically closed.

FILL_IN_PARAM

An arrayref. Everything inside this will be accessible from the usual @_ array inside templates.

OPTIONS

A hashref. Several template specific options can be set with this parameter.

id

Controls the cache id generation. Can be useful, if you want to pass your own template id. If false or set to AUTO, internal mechanisms will be used to generate template keys.

map_keys

This will change the compiler behavior. If you enable this, you can construct templates like this:

   This is "<%foo%>", that is "<%bar%>" and the other is "<%baz%>"

i.e.: only the key names can be used instead of perl constructs. and as you can see, "<%" is used instead of "<%=". map_keys also disables usage of perl constructs. Only bare words can be used and you don't have to fetch parameters via @_ inside the template. Here is an example:

   $text = $template->compile(
            q~This is "<%foo%>", that is "<%bar%>" 
              and the other is "<%baz%>"~,
            [
               foo => "blah 1",
               bar => "blah 2",
               baz => "blah 3",
            ],
            {
               map_keys => 1
            },
   );

Can be good (and simple) for compiling i18n texts. If you don't use map_keys, the above code must be written as:

   $text = $template->compile(
            q~<%my(%l) = @_%>This is "<%=$l{foo}%>", that is "<%=$l{bar}%>" 
              and the other is "<%=$l{baz}%>"~,
            [
               foo => "blah 1",
               bar => "blah 2",
               baz => "blah 3",
            ],
   );

If map_keys is set to 'init', then the uninitialized values will be initialized to an empty string. But beware; init may cloak template errors. It'll silence uninitialized warnings, but can also make it harder to detect template errors.

If map_keys is set to 'init', then the compiler will check for the key's existence and check if it is defined or not.

chkmt

If you are using file templates (i.e.: not FH or not string) and you set this to a true value, modification time of templates will be checked and compared for template change.

reset_cache

Resets the in-memory cache and deletes all cache files, if you are using a disk cache.

dump_cache

Returns a string version of the dumped in-memory or disk-cache. Cache is dumped via Data::Dumper. Deparse option is enabled for in-memory cache.

Early versions of Data::Dumper don' t have a Deparse method, so you may need to upgrade your Data::Dumper or disable deparse-ing if you want to use this method.

dump_cache accepts some arguments in name => value format:

  • varname

    Controls the name of the dumped structure.

  • no_deparse

    If you set this to a true value, deparsing will be disabled

dump_cache_ids

Returns a list including the names (ids) of the templates in the cache.

idgen DATA

This may not have any meaning for the typical user. Used internally to generate unique ids for template DATA (if cache is enabled).

get_id

Returns the current cache id (if there is any).

cache_size

Returns the total cache (disk or memory) size in bytes. If you are using memory cache, you must have Devel::Size installed on your system or your code will die.

in_cache data => TEMPLATE_DATA

in_cache id => TEMPLATE_ID

This method can be called with data or id named parameter. If you use the two together, id will be used:

   if($template->in_cache(id => 'e369853df766fa44e1ed0ff613f563bd')) {
      print "ok!";
   }

or

   if($template->in_cache(data => q~Foo is <%=$bar%>~)) {
      print "ok!";
   }

CLASS METHODS

These are all global (i.e.: not local to any particular object).

DEBUG

Used to enable/disable debugging. Debug information is generated as warnings:

   Text::Template::Simple->DEBUG(1); # enable
   Text::Template::Simple->DEBUG(0); # disable
   Text::Template::Simple->DEBUG(2); # more verbose

DEBUG is disabled by default.

DIGEST

Returns the digester object:

   $digester = Text::Template::Simple->DIGEST;
   print $digester->add($data)->hexdigest;

CACHE MANAGER

Cache manager has two working modes. It can use disk files or memory for the storage. Memory based cache is far more faster than disk cache.

The template text is first parsed and compiled into an anonymous perl sub source. Then an unique key is generated from your source data (you can by-pass key generation phase if you supply your own id parameter).

If in-memory cache is used, the perl source will be compiled into an anonymous sub inside the in-memory cache hash and this compiled version will be used instead of continiously parsing/compiling the same template.

If disk cache is used, a template file with the ".tmpl.cache" extension will be generated on the disk.

Using cache is recommended under persistent environments like mod_perl and PerlEx.

In-memory cache can use two or three times more space than disk-cache, but it is far more faster than disk cache. Disk cache can also be slower than no-cache for small templates, since there is a little overhead when generating unique keys with the "DIGESTER" and also there will be a disk I/O. There is a modification time check option for disk based templates (see compile).

DIGESTER

Cache keys are generated with one of these modules:

   Digest::SHA
   Digest::SHA1
   Digest::SHA2
   Digest::SHA::PurePerl
   Digest::MD5
   MD5
   Digest::Perl::MD5

SHA algorithm seems to be more reliable for key generation, but md5 is widely available and Digest::MD5 is in CORE.

EXAMPLES

TODO

ERROR HANDLING

You may need to eval your code blocks to trap exceptions. Some failures are silently ignored, but you can display them as warnings if you enable debugging.

BUGS

Contact the author if you find any bugs.

CAVEATS

No mini language

There is no mini-language. Only perl is used as the template language. So, this may or may not be safe from your point of view. If this is a problem for you, just don't use this module. There are plenty of template modules with mini-languages inside CPAN.

Speed

There is an initialization cost and this'll show itself after the first compilation process. The second and any following compilations will be much faster. Using cache can also improve speed, since this'll eliminate the parsing phase. Also, using memory cache will make the program run more faster under persistent environments. But the overall speed really depends on your environment.

Internal cache manager generates ids for all templates. If you supply your own id parameter, this will improve performance.

SEE ALSO

This module's parser is based on Apache::SimpleTemplate and evolved from that. Also see Text::Template for a similar functionality. HTML::Template::Compiled has a similar approach for compiled templates. There is another similar module named Text::ScriptTemplate. Also see Safe and Opcode.

AUTHOR

Burak Gürsoy, <burak@cpan.org>

COPYRIGHT

Copyright 2004-2007 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.