NAME
Template::Perlish - Yet Another Templating system for Perl
VERSION
This document describes Template::Perlish version 1.62.
SYNOPSIS
use Template::Perlish;
my $tp = Template::Perlish->new();
# A complex template, including some logic as Perl code
my $tmpl = <<END_OF_TEMPLATE
Dear [% name %],
we are pleased to present you the following items:
[%
my $items = $variables{items}; # Available %variables
my $counter = 0;
for my $item (@$items) {
%]
[%= ++$counter %]. [% $item %]
[%
}
%]
Please consult our complete catalog at [% uris.2.catalog %].
Yours,
[% director.name %] [% director.surname %].
END_OF_TEMPLATE
my $processed = $tt->process($template, {
name => 'Ciccio Riccio',
items => [ qw< ciao a tutti quanti > ],
uris => [
'http://whatever/',
undef,
{
catalog => 'http://whateeeeever/',
}
],
director => { surname => 'Poletti' },
});
The above prints:
Dear Ciccio Riccio,
we are pleased to present you the following items:
1. ciao
2. a
3. tutti
4. quanti
Please consult our complete catalog at http://whateeeeever/.
Yours,
Poletti.
There is also a convenience function for one-shot templates:
use Template::Perlish qw< render >;
my $rendered = render($template, \%variables);
There are also two functions that expose the path splitting algorithm
and the variable traversal, in case you need them:
use Template::Perlish qw< crumble traverse >;
my $array_ref = crumble("some.'-1'.'comp-lex'.path");
# returns [ 'some', '-1', 'comp-lex', 'path' ]
my $var;
my $ref_to_value = traverse(\$var, "some.0.'comp-lex'.path");
$$ref_to_value = 42; # note double sigil for indirection
# now we have that $some_variable is equal to:
# { some => [ { 'comp-lex' => { path => 42 } } ] }
SHOULD YOU USE THIS?
You're probably looking at the tons and tons of templating systems
available around - should you use this?
This system is quite basic and useful for simple situations. Say you
have a bunch of templates in which you want to put some variables -
then it's ok. On top of this, say that you want to add some simple
logic - like a couple of IF's or iterating over an array - then it's ok
again. For everything more complicated you should probably look
elsewhere.
As a summary:
PRO
* lightweight, a single-file module with minimal requirements that
you can easily embed in your script;
* simple approach to variable substitution, following
Template::Toolkit to cope with scalars, hashes and arrays;
PRO/CON
* Perl code to handle all logic. This can be regarded as a PRO if
you're a Perl programmer, because you already know the syntax; this
is probably (definitively?) a CON in all other cases;
CON
* you have to explicitly code everything that goes beyond simple
variable stuffing into a template.
* if you care about security, you MUST look elsewhere. There are
string evals inside Template::Perlish, so you must be 100% or more
sure that you trust your templates. Don't trust them if you don't
write them yourself, and even in that case be suspicious.
If you think that this module does not fit your requirements, my
personal suggestion for a templating system is Template::Toolkit: it's
complete, easy to use and extensible, has excellent documentation
(including a book and a quick reference guide) and support. Do you need
anything more?
But don't trust me! Take a look at Choosing a Templating System at
http://perl.apache.org/docs/tutorials/tmpl/comparison/comparison.html,
where you can find a fairly complete comparison about the streamline
templating systems in Perl, and decide by yourself!
DESCRIPTION
You bet, this is another templating system for Perl. Yes, because it's
the dream of every Perl programmer, me included. I needed something
that's easily portable, with no dependencies apart a recent Perl
version (but with some tweaking this should be solved), much in the
spirit of the ::Tiny modules.
Wherever possible I try to mimic Template::Toolkit, but I stop quite
early. If you only have to fill a template with a bunch of variables,
chances are that TT2 templates are good for Template::Perlish as well.
If you need even the slightest bit of logic, you'll have to part from
TT2 - and get full Perl power.
A template is simply a text (even if not necessarily) with some
particular markup to embed commands. In particular, all the stuff
included between [% and %] is considered as some sort of command, and
treated specially. All the rest is treated as simple text. Of course,
you can modify the start and stop delimiter for a command.
Commands can be of four different types:
variable embedding
that are expanded with the particular value for a given variable,
where variables are passed as a hash reference. A variable can be
defined as a sequence of alphanumeric (actually \w) tokens, separated
by dots (or anything described in "Templates" as of version 1.40).
The variables hash is visited considering each token as a subkey, in
order to let you visit complex data structures. You can also put
arrays in, just use the index as a key in this case.
scalar Perl variable
that is expanded with the value of the given scalar variable;
Perl expression
this MUST have a = equal sign immediately after the opener, and
contain a valid Perl expression. This expression is evaluated in
scalar context and the result is printed;
code
good old Perl code, in order to provide you with control structures,
modules, etc etc. This the most lazy approach I could think about,
and it's also why this module is called Perlish.
Take a look at the example in the "SYNOPSIS", it actually contains all
that this module provides.
To start, you'll need a Template::Perlish object and, of course, a
template. Templates are provided as text strings; if you have them into
files, you are in charge of loading them first.
# get a Template::Perlish object
my $tp = Template::Perlish->new();
# get the template (yes, it's your duty)
my $tmpl = do { open my $fh, '<', 'filename'; local $/; <$fh> };
The basic operation mode is via the "process" method, which works much
like in TT2. Anyway, this method will always give you back the
generated stuff, and won't print anything. This can probably be less
memory efficient when big templates are involved, but in this case you
should probably head somewhere else. Or not.
# print out the template filled with some variables
print $tp->process($tmpl, { key => 'value' });
Each template is transformed into Pure Perl code, then the code is
evaluated in order to get the output. Thus, if you want to operate on
the same template many times, a typical usage is:
# compile the template with something like:
my $compiled = $tp->compile($template);
# use the compiled template multiple times with different data
for my $dataset (@available_data) {
print "DATASET\n", $tp->evaluate($compiled, $dataset), "\n\n";
}
There is also a facility - namely "compile_as_sub" - that returns an
anonymous sub that encapsulates the "evaluate" call above:
my $sub = $tp->compile_as_sub($template)
or die "template did not compile: $EVAL_ERROR";
for my $dataset (@available_data) {
print {*STDOUT} "DATASET\n", $sub->($dataset), "\n\n";
}
As of release 1.2 the error reporting facility has been improved to
provide feedback if there are issues with the provided template, e.g.
when there is a syntax error in the Perl code inside. When an error
arises, the module will die() with a meaningful message about where the
error is. This happens with all the provided facilities.
Error checking is turned on automatically on all facilities. You can
avoid doing it in the "compile" method, although the check will kick in
at the first usage of the compiled form. To avoid the check upon the
compilation, pass the no_check option to "compile":
my $compiled = $tp->compile($template, no_check => 1);
By default, the stuff is assumed to be utf-8 compliant, which is
reflected by option utf8 defaulting to true in "new". This default is
inhibited by setting utf8 to a false value, or binmode to any defined
value.
INTERFACE
One Shot Templates
The following convenience function can be used to quickly render a
template:
render
use Template::Perlish qw< render >;
my $rendered = render($template); # OR
my $rendered = render($template, %variables); # OR
my $rendered = render($template, $var_ref); # OR
my $rendered = render($template, $var_ref, $opts_ref);
if you already have a template and the variables to fill it in, this
is probably the quickest thing to do.
You can pass the template alone, or you can pass the variables as
well, either as a flat list (that will be converted back to a hash)
or as a single reference.
It's also possible to set all options described for constructor
"new", as long as you
Returns the rendered template, i.e. the same output as "process".
Note that it assumes the default values for options explained in
"new".
Constructor
new
$tp = Template::Perlish->new(@opts); # OR
$tp = Template::Perlish->new(\%opts);
constructor, does exactly what you think. You can provide any
parameter, but only the following will make sense:
binmode
string to set binmode on the output filehandle. A defined value
disables the default to utf8.
functions
(as of version 1.58) hash reference with functions that will be
injected in the Template::Perlish namespace for the duration of the
template evaluation. Keys are assumed to be valid function names,
values are assumed to be valid sub references.
method_over_keys
boolean flag used for traversal, see "traverse".
Defaults to false;
start
delimiter for the start of a command (as opposed to plain
text/data).
Defaults to [%;
stdout
boolean value, allows one to clobber STDOUT for collecting the
expansion of a template, or to leave STDOUT untouched.
New option as of release 1.52. Until the previous stable release,
this behaviour was the norm: inside a template, whatever print to
STDOUT is trapped and put in the template expansion. For this
reason, this option defaults to a true value (1) in order to keep
backwards compatibility.
If you set this flag to a false value, STDOUT will not be modified
and will be accessible from within the templates. In this case, if
you still want to print inside the template you can use function
"P".
Defaults to true;
stop
delimiter for the end of a command.
Defaults to %];
strict_blessed
boolean flag used for traversal, see "traverse".
Defaults to false;
traverse_methods
boolean flag used for traversal, see "traverse".
Defaults to false;
utf8
sets the handling to utf8.
Defaults to true, unless binmode option is set to a defined value.
variables
variables that will be passed to all invocations of "process"
and/or "evaluate". It MUST be a reference to a hash.
Defaults to an empty hash reference.
-preset
this is a meta-option and is available only when the constructor is
called with a list of key/value pairs, not with a hash reference.
This allows you to load canned sequences of presets that will be
exposed for different releases and allow you to quickly tune the
usage of Template::Perlish, while still keeping backwards
compatibility.
Each preset is overlaid on the configuration as soon as it is
encountered in the arguments list, so order matters. Here are the
available presets:
default
sets defaults values written above;
1.52
overrides stdout to a false value, while setting traverse_method
and method_over_key to a true one. As a matter of fact, it
enables all new options available in release 1.52 in one single
shot.
As an example, if you want to use the new features in 1.52 but you
would like keys in a hash to take precedence over methods, you can
do either of the following:
$o = Template::Perlish->new(
-preset => '1.52',
method_over_key => 0,
);
# OR
$o = Template::Perlish->new(
stdout => 1,
traverse_methods => 0,
);
Parameters can be given directly as key-value pairs or via a hash
reference. In the former case, you can provide the same option
multiple times and also use meta-option -preset described above.
By default, the delimiters are the same as TT2, i.e. [% and %], and
the variables hash is empty.
The return value is a reference to an anonymous hash, whose elements
are the ones described above. You can modify them at will, there are
no accessors for this simple object.
Template Handling
compile
$compiled = $tp->compile($template);
$compiled = $tp->compile($template, no_check => $boolean);
compile a template generating the relevant Perl code. Using this
method is useful when the same template has to be used multiple
times, so the compilation can be done one time only.
You can turn off checking using the no_check optional parameter and
passing a true value. The check will be performed upon the first
usage of the compiled form though.
Returns a hash containing, among the rest, a text version of the
template transformed into Perl code.
compile_as_sub
$sub_reference = $tp->compile_as_sub($template);
Much like "compile", this method does exactly the same compilation,
but returns a reference to an anonymous subroutine that can be used
each time you want to "explode" the template.
The anonymous sub that is returned accepts a single, optional
parameter, namely a reference with the same role as $reference in
"evaluate".
Note that if you add/change/remove values using the variables member
of the Template::Perlish object, these changes will reflect on the
anonymous sub, so you end up using different values in two subsequent
invocations of the sub. This is consistent with the behaviuor of the
"evaluate" method.
evaluate
$final_text = $tp->evaluate($compiled); # OR
$final_text = $tp->evaluate($compiled, $reference);
evaluate a template (in its compiled form, see "compile") with the
available variables. In the former form, only the already configured
variables are used (see "Constructor"; in the latter, the given
$reference is considered.
If $reference is a hash reference, the variables set in the
constructor (if any) are merged with the ones in $reference and
eventually passed for expansion of the $compiled template. Keys from
$reference override those from the constructor and they also end up
in the %variables lexical hash that is visible in the template's
scope.
As of release 1.50, $reference can also be something else (most
probably, an array reference), it is used as the variables entry
point instead. In this case, the %variables lexical hash that is
visible in the template's scope is shaped like this:
%variables = (
HASH => { variables from the constructor... },
REF => $reference,
);
so you have in any way the chance to access the variables set in the
constructor.
Returns the processed text as a string.
process
$final_text = $tp->process($template); # OR
$final_text = $tp->process($template, $variables);
this method included "compile" and "evaluate" into a single step.
Templates
There's really very little to say: write your document/text/whatever,
and embed special parts with the delimiters of your choice (or stick to
the defaults). If you have to print stuff, just print to STDOUT, it
will be automatically catpured (unless you're calling the generated
code by yourself).
As of version 1.52, the new boolean option stdout has been introduced,
allowing to keep the old behaviour (i.e. printing to STDOUT is captured
in the expanded template) described above, or to use the new one where
STDOUT is not clobbered. This parameter defaults to 1 (i.e. a true
value, in Perl sense) for backwards compatibility. If you still want to
print out, though, you can use the new function "P". As a matter of
fact, you're encouraged to always use P, because it will work both in
the old and in the new setup.
Anything inside these "special" parts matching the regular expression
/^\s*\w+(?:\.\w+)*\s*$/, i.e. consisting only of a sequence of
alphanumeric tokens separated by dots, are considered to be variables
and processed accordingly. Thus, available variables can be accessed in
two ways: using the dotted notation, as in
[% some.value.3.lastkey %]
or explicitly using the %variables hash:
[% print $variables{some}{value}[3]{lastkey} %]
The former is cleaner, but the latter is more powerful of course.
As of release 1.50, Template::Perlish does not assume that the input
data structure is a hash reference any more. Hence, %variables might
not actually contain your input; see "Variables Accessors" for a robust
way to get the right value instead. Or you can use $V if you feel brave
(it's a reference to either %variables or is whatever else was provided
as input, so it alwasy points to the right data). See "evaluate" for
additional information about the provided parameters and %variables.
As of release 1.40, Template::Perlish also allows you to use more
complex variable names in your data structure and your template,
without having to resort to the second form. It will suffice to quote
the relevant parts where you want to put non-alphanumeric keys, e.g.:
'$whatever'.'...'."with '\" quotes"
The quoting rules for this feature added in 1.40 are the following:
* single quotes
are paired and can contain any character inside, except a single
quote. Use double quotes if you need to put single quotes. The quotes
themselves are stripped away before figuring out what the key is;
* double quotes
are paired and can contain any character inside, with some care. If
you need to put double quotes inside, you have to escape with a
backslash. Also, if you want to insert a literal backslash, you have
to prepend it with another backslash. In general, every time you put
a backslash, the following character is taken as-is and the escaping
backslash is tossed away. So the following:
"\'\a\ \v\e\r\y\ \s\t\r\a\n\g\e\ \k\e\y\'"
is interpreted as:
'a very strange key'
(including the single quotes).
* the rest
must be alphanumeric only, like it was before.
If you happen to have a value you want to print inside a simple scalar
variable, instead of:
[% print $variable; %]
you can also use the short form:
[% $variable %]
Note: only the scalar variable name, nothing else apart optional
spaces. If you have something fancier, i.e. a Perl expression, you can
use a shortcut to evaluate it and print all in one single command:
[%= my $value = 100; "*** $variable -> $value ***" %]
Note that there is an equal sign (=) immediately after the command
opener [%. The Perl expression is evaluated in scalar context, and the
result is printed (if defined, otherwise it's skipped). This sort of
makes the previous short form for simple scalars a bit outdated, but
you spare a character in any case and it's just DWIM.
If you know Perl, you should not have problems using the control
structures. Just intersperse the code with the templates as you would
normally do in any other templating system:
[%
if ($variables{this}) {
%]
blah blah [% this %], foo bar!
[%
}
else {
%]
yak yak that!
[%
}
%]
Take care to always terminate your commands with a ; each time you
would do it in actual code.
As of version 1.40, there are also a few functions that will make your
life easy if you want to access the variables, namely "V" to access a
variable provided its dotted-path representation, "A" for expanding the
variable as an array, "H" to expand it as a hash, and "HK" and "HV" to
get the keys and values of a hash, respectively.
There's no escaping mechanism, so if you want to include literal [% or
%] you either have to change delimiters, or you have to resort to
tricks. In particular, a stray closing inside a textual part won't be a
problem, e.g.:
[% print "variable"; %] %] [% print "another"; %]
prints:
variable %] another
The tricky part is including the closing in the Perl code, but there
can be many tricks:
[% print '>>>%'.']<<<' %]
prints
>>>%]<<<
To include a starter in the text just print it inside a Perl block:
here it comes [%= '[%' %] the delimiter
prints:
here it comes [% the delimiter
Another trick is to separate the two chars with an empty block:
here it comes [[%%]% the delimiter
Including the starter in the Perl code is not a problem, of course.
So the bottom line is: who needs escaping?
Variables Accessors
The following variable accessors can be used from within the templates.
All variable accessors accept three forms:
* without parameters. In this case, the root of the data is selected,
then the operation of the accessor is applied;
* with one parameter. In this case, the parameter is the path in the
data structure;
* with two parameters. In this case, the first parameter is the path
in the data structure, while the second one is the data structure to
be traversed.
The third alternative is useful when you want to take advantage of the
accessors on a sub-structure, like in the following example:
# suppose $item is a hash of hashes at each iteration...
for my $item (A 'some.array') {
my $wanted = V 'data.inside.item', $item;
# ... do something with $wanted...
}
Here are the accessors:
A
A
A 'path.to.arrayref'
A 'path.to.arrayref', $root
get the variable at the specific path and expand it as array. This
can be useful if you want to iterate over a variable that you know is
an array reference:
[% for my $item (A 'my.array') { ... } %]
is equivalent to:
[% for my $item (@{$variables{my}{array}}) { ... } %]
but more concise and a little more readable.
When no path is passed, the root of the input data is assumed to be a
reference to an array and that will be expanded.
You can optionally pass a second parameter with a data structure.
That will be used instead of the one provided to the template.
H
H
H 'path.to.hashref'
H 'path.to.hashref', $root
get the variable at the specific path and expand it as hash.
When no path is passed, the root of the input data is assumed to be a
reference to a hash and that will be expanded.
You can optionally pass a second parameter with a data structure.
That will be used instead of the one provided to the template.
HK
HK
HK 'path.to.hashref'
HK 'path.to.hashref', $root
get the variable at the specific path, expand it as hash and get its
keys. This can be useful if you want to iterate over the keys of a
variable that you know is an hash reference:
[% for my $key (HK 'my.hash') { ... } %]
is equivalent to:
[% for my $key (keys %{$variables{my}{hash}}) { ... } %]
but more concise and a bit more readable.
When no path is passed, the root of the input data is assumed to be a
reference to a hash and that will be expanded.
You can optionally pass a second parameter with a data structure.
That will be used instead of the one provided to the template.
HV
HV
HV 'path.to.hashref'
HV 'path.to.hashref', $root
similar to "HK", but provides values instead of keys.
V
V
V 'path.to.variable'
V 'path.to.variable', $root
get the variable at the specific path. The following:
[%= V('path.to.variable') + 1 %]
is the same as:
[%= $variables{path}{to}{variable} + 1 %]
but shorter and more readable.
When no path is passed, the root of the input data is assumed to be a
scalar and that will be returned.
You can optionally pass a second parameter with a data structure.
That will be used instead of the one provided to the template.
You can look at this accessor as an alternate form for "traverse",
only with a slightly different input interface (e.g. defaulting to
the template variables and swapped parameter positions).
Direct Printing
Up to version 1.50, if you printed (to STDOUT, which would be the
selected filehandle) your text would end up directly in the expanded
text. This was (and is still) meant as a feature.
As of version 1.52, this behaviour can change depending on the value of
option stdout (see "new"). By default, its value is such that the old
behaviour is preserved: prints to STDOUT are trapped and put in the
template's expansion.
In case the new option stdout is set to a false value, though, any
print will use the currently selected filehandle before entering the
template, i.e. STDOUT (the real one, not the one set within the
template) by default. This allows your code to actually communicate
with the external world, if you need to.
The following function allows you to still use a print-like interface
from within the template:
P
Hey [% P('foo-bar-baz') %], how are you?
Print an expression directly to the template's expansion. Whatever
the value of option stdout (see "new"), this function will always put
its argument inside the template.
In case stdout is true (which is the default value for backwards
compatibility), P and print to STDOUT are equivalent (as a matter of
fact, P just calls print to STDOUT behind the scenes).
In case stdout is false, instead, P will send its output to the
template, while print will send it to whatever handle is currently
selectd, and print to STDOUT will use the STDOUT available at the
time of template compilation.
As an example, consider the following template:
Hey '[% print 'foo' %]'
I spoke with '[% print {*STDOUT} 'bar' %]'
Do you know '[% P 'baz' %]'?
If stdout is true, it will be expanded to:
Hey 'foo'
I spoke with 'bar'
Do you know 'baz'?
If stdout is false, it will be expanded to:
Hey ''
I spoke with ''
Do you know 'baz'?
while the string foo will be printed to the currently selected
filehandle (which is usually STDOUT, but you might have something
different in your program), and the string bar is printed to STDOUT
as you know it.
External Path Handling
The following functions can be exported and expose the algorithms
implemented by Template::Perlish for breaking a string into a path for
accessing a data structure, and a traversal function to go into a data
structure according to a path.
They can be useful in case you need to build the data structure to pass
to Template::Perlish before expanding a template. A typical case might
be that you have a command line option to set the value of variables in
the data structure to be expanded in the template:
$ my-command --define path.to.1.variable=blah
and you want to apply the same algorithm as Template::Perlish, i.e. set
your data structure like this:
$data->{path}{to}[1]{variable} = 'blah';
This will provide consistency when expanding the template, because
using the same path will provide the right value:
[% path.to.1.variable %] expands to blah
crumble
my $array_ref = crumble($path); # OR
my $array_ref = crumble($path, 1); # OR, BETTER
my ($aref, $pos) = crumble($path, 1);
split the input $path into crumbs that should be followed into some
data structure (you can use "traverse" to do the actual traversal).
Returns a reference to an array with the crumbs, in order. Returns
undef if the provided $path cannot be broken down. See "Templates"
for the rules of breaking a path into pieces, this is the actual
function used to do that.
As of version 1.60, this function also accepts a second optional
boolean argument for supporting partial matches. If false (default),
the legacy behaviour is kept, and the provided input $path must match
in its entirety or the splitting will fail. If true, the extraction
of crumbs will begin at the first character of $path but be allowed
to stop in the middle; this e.g. allows parsing strings like
foo.bar:baz, with crumbs resulting in ['foo', 'bar']. The first
variant will only return the crumbs in an array reference; the second
variant will also point out the position where the match stopped, so
that residual stuff can be extracted (in the example, the :baz part).
traverse
my $x = traverse($data); # OR
my $x = traverse($data \%opts); # OR
my $x = traverse($data, $path); # OR
my $x = traverse($data, $path, \%opts);
traverse an input data structure and return something (depending on
the $data).
The first argument $data is mandatory and can be:
* a HASH or ARRAY reference, in which case a normal traversal will
take place, and missing keys/indexes will stop the traversal;
* a reference to a SCALAR or to another REF, in which case
auto-vivification in traversal will be enabled (see below for
details);
* anything else, in which case it's better to either avoid $path or
to provide an empty one to get it back, or it is likely to give an
error (because you can't traverse it actually).
When provided, $path is the path to follow inside data. It can be
either a plain string that will be split using "crumble", or an array
reference containing the different crumbs to follow. When missing, it
is the same as providing the empty path (i.e. an empty string or a
reference to an empty array).
Depending on what is held in $data, you will get either a value back
(if auto-vivification is NOT active) or a reference to it (if it is
active). This also changes how the traversal is done in case of
missing parts.
In particular, you will want to pass a reference to a hash or array
if you want to just read from data. In this case, the first missing
crumb will make the function return immediately an empty string value
(or, as of version 1.62, whatever is passed with option missing, if
anything); moreover, if all crumbs are successfully found, the value
will be returned. This is what is actually used by the functions
described in "Variables Accessors".
If you pass a reference to a scalar or to another reference instead,
you will get back a reference to a value. In this case, any missing
parts will trigger auto-vivification of the data structure, i.e. the
missing parts will be created automatically for you. This comes handy
when you want to write into the data structure, like in the following
example:
my $empty_data;
my $ref_to_v = traverse(\$empty_data, "some.0.'comp-lex'.path");
$$ref_to_v = 42; # note double sigil for indirection
# now we have that $empty_data is equal to:
# { some => [ { 'comp-lex' => { path => 42 } } ] }
You can e.g. want to use this approach to provide a consistent way to
set variables and expand them into templates:
my $vars;
${traverse(\$vars, 'one.two.3')} = 42;
my $text = render('It is as simple as [% one.two.3 %]', $vars);
Of course variable values might come from the command line or some
other source in the real world!
When something goes wrong in the traversal, undef is returned if
auto-vivification is enabled, an empty string (or, as of version
1.62, what is passed as option missing if present) is returned
otherwise.
If $path is a reference to an array, its components can be plain
scalars or references themselves. When they are plain scalars, they
are used directly to access data or its descendants; otherwise,
traverse enforces that the current descendant in data is a reference
of the same type as the specific crumb. Consider this example:
my $data = { one => { two => [ qw< ciao a tutti quanti > ] } }
my $path1 = [ qw< one two 3 > ]; # good
my $path2 = [ 'one', { two => 1 }, 3 ]; # good
my $path3 = [ 'one', { two => 1 }, [3] ]; # good
my $path4 = [ qw< one two >, { 3 => 1 } ]; # fails if !ref
To get the quanti string, you have to traverse (in order) one hash,
one hash and one array. The first path $path1 is good to this regard,
because it does not ask for any check and the last element is a good
one to be used as an array index.
$path2 and $path3 are good as well, because the required checks are
fine: after passing one we end up with a hash, that is the same
reference as { two => 1} and gets us to the array reference. $path3
asks for a further check that we are actually dealing with an array
reference at this stage.
$path4 is not good because after traversing one and two we end up
with an array reference. At this point, the next crumb is an hash
reference instead (whose key is 3), so the matching fails.
As you have seen, if you are forcing a match on the reference type,
the actual key used to dive into the relevant descendant of data is
either the (only) element of an array reference (as in [3] that
becomes 3), or the (only) key of a hash reference (as in { two => 1 }
that becomes two).
When auto-vivification is active, a reference in the path will also
force a specific auto-vivification type, i.e. the automatic creation
of either an array or a hash reference. If the crumb in path is not a
reference, a guess is taken in that non-negative integers are
considered indexes of an array, otherwise a hash is assumed. So,
let's take $path4 again, and let's see what happens when ref is true:
my $path4 = [ qw< one two >, { 3 => 1 } ];
my $data = {}; # start e.g. with an empty hash
${traverse(\$data, $path4)} = 42;
will auto-vivify $data completely and leave it as follows:
$data = {
one => { # "one" is not a non-negative integer => HASH
two => { # "two" is not a non-negative integer => HASH
3 => 42 # { 3 => 1 } is a hash reference => HASH
}
}
}
As of version 1.52, you can also pass an extra hash reference with
some additional options for traversal. For example, consider the
following setup:
sub what { return 'hey' };
sub urgh { return 'gaah!' }
my $object = bless {what => 'ever', foo => 'bar'}, __PACKAGE__;
Object $object is a blessed hash reference with two keys, two methods
and one method that has the same name of one of the keys. The
different available options will help you decide what to do in this
situation:
method_over_key
when traversal by method is enabled (see traverse_methods below),
this option allows controlling whether the key or the method win
when both are present.
In the example above, if this option is set to a true value the
path what triggers a method call; otherwise, the value in the hash
is considered (i.e. ever in the example). When a key is not
present, the method is called as a fallback.
Defaults to a false value.
strict_blessed
when traversal by method is enabled (see below), whenever a blessed
object is hit in the traversal only method calls are allowed. This
disables peeking inside the object in case a method is not
available but a key exists.
In the example above, using path what always triggers the method
call (returning hey), using path urgh calls the method call, using
path foo returns the empty string.
This option hides option method_over_key.
Defaults to a false value.
traverse_methods
boolean flag to enable traversal of blessed objects using method
calls instead of direct inspection by key. When this is false, the
other two options above are ignored.
In the example object, if this parameter is set to a false value
the object will be considered just a plain hash. Otherwise, what a
visit for keys what, urgh and foo returns depends on the options
above.
Defaults to a false value for backwards compatibility.
The following scheme attempts to explain what happens in the
different cases:
traverse_methods = false (default)
strict_blessed = whatever
method_over_keys = whatever
what -> 'ever' # key is used, method is ignored
foo -> 'bar' # key is used
urgh -> '' # method is ignored
traverse_methods = true
strict_blessed = false (default)
method_over_keys = false (default)
what -> 'ever' # key wins over method
foo -> 'bar' # key is used
urgh -> 'gaah!' # no key, method is called
traverse_methods = true
strict_blessed = false (default)
method_over_keys = true
what -> 'hey' # method wins over key
foo -> 'bar' # key is used
urgh -> 'gaah!' # method is called
traverse_methods = true
strict_blessed = true
method_over_keys = whatever
what -> 'hey' # method wins over key
foo -> '' # key is ignored
urgh -> 'gaah!' # method is called
Since version 1.62, additional option missing allows setting the
return value when the target key is not found. This applies only when
auto-vivification is not active. When this key is missing, the return
value is by default set to the empty string, preserving
backwards-compatibility.
To tell an undefined value from a really missing key, it's possible
to pass a marker reference and check the return value against it with
Scalar::Util::refaddr:
use Scalar::Util 'refaddr';
my $marker = [];
my $value = traverse($data, $path, { missing => $marker });
say 'the value is missing'
if ref($value) && refaddr($value) == refaddr($marker);
DIAGNOSTICS
Diagnostics have been improved in release 1.2 with respect to previous
versions, although there might still be some hiccups here and there.
Errors related to the template, in particular, will show you the
surrounding context of where the error has been detected, although the
exact line indication might be slightly wrong. You should be able to
find it anyway.
open(): %s
the only perlfunc/open is done to print stuff to a string. If you get
this error, you're probably using a version of Perl that's too old.
unclosed %s at position %d
a Perl block was opened but not closed.
Other errors are generated as part of the Perl compilation, so they
will reflect the particular compile-time error encountered at that
time.
CONFIGURATION AND ENVIRONMENT
Template::Perlish requires no configuration files or environment
variables.
DEPENDENCIES
None, apart a fairly recent version of Perl.
INCOMPATIBILITIES
As of version 1.52, providing an empty template will give you back an
empty string, as opposed to undef that is the old behaviour.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests through http://rt.cpan.org/
Due to the fact that Perl code is embedded directly into the template,
you have to take into consideration all the possible security
implications. In particular, you should avoid taking templates from
outside, because in this case you'll be evaluating Perl code that you
haven't checked. CAVEAT EMPTOR.
AUTHOR
Flavio Poletti <polettix@cpan.org>
LICENSE AND COPYRIGHT
Copyright (c) 2008-2016 by Flavio Poletti polettix@cpan.org.
This module is free software. You can redistribute it and/or modify it
under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.
SEE ALSO
The best templating system in the world is undoubtfully
Template::Toolkit.
See
http://perl.apache.org/docs/tutorials/tmpl/comparison/comparison.html
for a comparison (and a fairly complete list) of different templating
modules.