Template::Compiled - templates which compile into coderefs
use Template::Compiled; use Types::Standard -types; my $template = Template::Compiled->new( signature => [ name => Str, age => Optional[Int] ], delimiters => [ qw( [% %] ) ], outdent => 2, trim => 1, escape => 'html', template => q{ <p>Dear [%= $name %]</p> [% if (defined($age)) { %] <p>I see you are [%= $age %] years old.</p> [% } %] }, ); print $template->( name => 'Alice & Bob', age => 99 );
Template::Compiled allows you to define a template which will be compiled into a coderef that renders the template, filling in values. Templates can contain variables and chunks of Perl code.
Technically, the template is an object which overloads &{} so that it can act like a coderef, but you can get a real coderef by calling $template->sub.
&{}
$template->sub
Compiling the coderef might be slower than some other template modules, but rendering the template should be pretty much as fast as a pure Perl template module can get. So in a persistent environment, where the same template may be used over and over, this should be pretty fast.
The class provides a standard Moose-style constructor with the following attributes.
template
The template as a string of text. Details of the template format are described below. This attribute will coerce from an arrayref of strings by joining them.
signature
A sub signature for validating arguments passed to the template when rendering it. Must be suitable for Type::Params compile_named.
compile_named
delimiters
The strings which delimit code within the template. The default delimiters are the PHP-ish <? and ?>.
<?
?>
escape
A coderef to autoescape strings. For example:
my $template = Template::Compiled->new( ..., escape => sub { my $text = shift; HTML::Entities::encode_entities_numeric($text); }, );
As a shortcut, you may say escape => "html" or escape => "xml".
escape => "html"
escape => "xml"
trim
If set to true, leading and trailing whitespace will be trimmed from the rendered output. (Not from each line!)
Defaults to false.
outdent
This many whitespace characters are trimmed from the start of every line. If negitive, all whitespace is trimmed from the start of every line.
Defaults to zero.
post_process
If provided, this coderef gets a chance to modify the rendered output right at the end. It should be a coderef manipulating $_.
$_
utils_package
A package to import into the namespace the coderef is compiled in. Defaults to Template::Compiled::Utils which provides some useful functions.
sub
The whole point of this module is to let us generate this for you. Don't provide it to the constructor!
The sub doesn't contain any references back to the Template::Compiled object, so it can be garbage collected by Perl.
my $template = Template::Compiled->new( ... ); my $compiled = $template->sub; undef $template; # free memory used by object print $compiled->( %args );
These are not especially necessary, but this module provides some methods which may make your code a little clearer.
$template->render( %args )
Alternative way to write $template->( %args ).
$template->( %args )
$template->print( %args )
Alternative way to write print( $template->( %args ) ).
print( $template->( %args ) )
$template->print( $fh, %args )
Alternative way to write $fh->print( $template->( %args ) ).
$fh->print( $template->( %args ) )
Template::Compiled overloads the following operations:
bool
Always true.
Returns sub.
""
Returns template.
Future versions may overload concatenation to do something useful.
Templates are strings with embedded Perl code. Although the delimeters can be changed, there are two basic forms for the Perl code:
<?= EXPR ?> <? CODE ?>
The first form evaluates EXPR and appends it to the output string, escaping it if necessary. (The expression is actually evaluated in a do block, so may include multiple semicolon-delimited statements, and has its own lexical scope.)
do
The second form evaluates CODE but does not automatically append anything to the output. If you need to append anything to the output string in your code block, you can do $OUT .= "blah" or echo "blah". (Don't use print because this will print immediately rather than appending to the output!)
$OUT .= "blah"
echo "blah"
print
Within the template, the following variables are available to you:
$OUT
The output of the template so far. May be altered or appended to.
$INDENT
A string of whitespace equivalent to how much this block of code is indented, minus outdenting.
%_
A hash of the arguments provided when rendering the template.
For example, with:
$template->render( foo => 1, bar => [ 2, 3, 4 ] );
Then:
<?= $_{foo} ?> # 1 <?= $_{bar}[0] ?> # 2
If your template declared a signature, then named aliases are provided for arguments.
<? $foo; # 1 $bar; # [ 2, 3, 4 ] # And if the signature declared that 'bar' was an # ArrayRef, then... # @bar; # ( 2, 3, 4 ) ?>
So, yeah, use signatures.
Scalar variables named with a leading underscore are reserved for internal use. Avoid them in your templates.
Within the template, the following functions are available to you:
_($string)
The <?= $foo ?> syntax automatically passes the variable through the template's escaping mechanism, but if you're using <? CODE ?> you will need to escape strings manually. The _() function can escape stuff for you.
<?= $foo ?>
<? CODE ?>
_()
echo($string)
Equivalent to $OUT .= $string.
$OUT .= $string
Provided by Template::Compiled::Utils, so may not be available if you're using a different utils package.
echof($format, @data)
Equivalent to $OUT .= sprintf($format, @data).
$OUT .= sprintf($format, @data)
The start and end delimiters for code cannot be escaped.
But this isn't really as bad as it seems. If you need to output them literally:
<? echo '<?' ?> <? echo '?'.'>' ?>
If that becomes inconvenient, then you can simply choose different delimiters.
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Template-Compiled.
Template::Perlish is pretty similar really.
Type::Params provides the signatures for this module.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
To install Template::Compiled, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Compiled
CPAN shell
perl -MCPAN -e shell install Template::Compiled
For more information on module installation, please visit the detailed CPAN module installation guide.