/ 
Template-Compiled-0.003
River stage zero No dependents
/ Template::Compiled

NAME

Template::Compiled - templates which compile into coderefs

SYNOPSIS

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 );

DESCRIPTION

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.

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.

Attributes

The class provides a standard Moose-style constructor with the following attributes.

template (Str, required)

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 (ArrayRef, optional)

A sub signature for validating arguments passed to the template when rendering it. Must be suitable for Type::Params compile_named.

delimiters (Tuple[Str, Str], optional)

The strings which delimit code within the template. The default delimiters are the PHP-ish <? and ?>.

escape (CodeRef, optional)

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".

trim (Bool, optional)

If set to true, leading and trailing whitespace will be trimmed from the rendered output. (Not from each line!)

Defaults to false.

outdent (Int, optional)

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 (CodeRef, optional)

If provided, this coderef gets a chance to modify the rendered output right at the end. It should be a coderef manipulating $_.

utils_package (Str, optional)

A package to import into the namespace the coderef is compiled in. Defaults to Template::Compiled::Utils which provides some useful functions.

sub (CodeRef, optional)

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 );

Methods

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->print( %args )

Alternative way to write print( $template->( %args ) ).

$template->print( $fh, %args )

Alternative way to write $fh->print( $template->( %args ) ).

Overloads

Template::Compiled overloads the following operations:

bool

Always true.

&{}

Returns sub.

""

Returns template.

Future versions may overload concatenation to do something useful.

TEMPLATE FORMAT

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.)

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!)

Variables

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.

Functions

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.

echo($string)

Equivalent to $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).

Provided by Template::Compiled::Utils, so may not be available if you're using a different utils package.

Escaping

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.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Template-Compiled.

SEE ALSO

Template::Perlish is pretty similar really.

Type::Params provides the signatures for this module.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

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.

DISCLAIMER OF WARRANTIES

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.