template::parser(3)

NAME

Template::Parser - LALR(1) parser for compiling template
documents

SYNOPSIS

use Template::Parser;
$parser   = Template::Parser->new(config);
$template = $parser->parse($text)
    || die $parser->error(), "0;

DESCRIPTION

The Template::Parser module implements a LALR(1) parser
and associated methods for parsing template documents into
Perl code.

PUBLIC METHODS

new%(params)

The new() constructor creates and returns a reference to a
new Template::Parser object. A reference to a hash may be
supplied as a parameter to provide configuration values.
These may include:

START_TAG, END_TAG: The START_TAG and END_TAG options are used to specify
character sequences or regular expressions that mark
the start and end of a template directive. The
default values for START_TAG and END_TAG are '[%' and
'%]' respectively, giving us the familiar directive
style:

[% example %]; Any Perl regex characters can be used and therefore
should be escaped (or use the Perl "quotemeta" func
tion) if they are intended to represent literal char
acters.

my $parser = Template::Parser->new({
START_TAG => quotemeta('<+'),
END_TAG => quotemeta('+>'),

});; example:

<+ INCLUDE foobar +>; The TAGS directive can also be used to set the
START_TAG and END_TAG values on a per-template file
basis.

[% TAGS <+ +> %]
TAG_STYLE: The TAG_STYLE option can be used to set both START_TAG
and END_TAG according to pre-defined tag styles.

my $parser = Template::Parser->new({
TAG_STYLE => 'star',

});; Available styles are:

template [% ... %] (default)
template1 [% ... %] or %% ... %% (TT version 1)
metatext %% ... %% (Text::Meta

Text)
star [* ... *] (TT alternate)
php <? ... ?> (PHP)
asp <% ... %> (ASP)
mason <% ... > (HTML::Mason)
html  (HTML com

ments); Any values specified for START_TAG and/or END_TAG will
over-ride those defined by a TAG_STYLE.; The TAGS directive may also be used to set a TAG_STYLE

[% TAGS html %]
PRE_CHOMP, POST_CHOMP: Anything outside a directive tag is considered plain
text and is generally passed through unaltered (but
see the INTERPOLATE option). This includes all
whitespace and newlines characters surrounding direc
tive tags. Directives that don't generate any output
will leave gaps in the output document.; Example:

Foo
[% a = 10 %]
Bar; Output:

Foo

Bar; The PRE_CHOMP and POST_CHOMP options can help to clean
up some of this extraneous whitespace. Both are dis
abled by default.

my $parser = Template::Parser->new({
PRE_CHOMP => 1,
POST_CHOMP => 1,

});; With PRE_CHOMP set to 1, the newline and whitespace
preceding a directive at the start of a line will be
deleted. This has the effect of concatenating a line
that starts with a directive onto the end of the pre
vious line.

Foo <----------.; ,---(PRE_CHOMP)----'; `-- [% a = 10 %] --.; ,---(POST_CHOMP)---'; `-> Bar
With POST_CHOMP set to 1, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line.
If PRE_CHOMP or POST_CHOMP is set to 2, then instead of removing all the whitespace, the whitespace will be collapsed to a single space. This is useful for HTML, where (usually) a contiguous block of whitespace is rendered the same as a single space.
You may use the CHOMP_NONE, CHOMP_ALL, and CHOMP_COL LAPSE constants from the Template::Constants module to deactivate chomping, remove all whitespace, or col lapse whitespace to a single space.
PRE_CHOMP and POST_CHOMP can be activated for individ ual directives by placing a '-' immediately at the start and/or end of the directive.: [% FOREACH user = userlist %]
[%- user -%]; [% END %]
The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one directive '[%- name -%]'. Thus, the template will be processed as if written:: [% FOREACH user = userlist %][% user %][% END %]
Note that this is the same as if PRE_CHOMP and POST_CHOMP were set to CHOMP_ALL; the only way to get the CHOMP_COLLAPSE behavior is to set PRE_CHOMP or POST_CHOMP accordingly. If PRE_CHOMP or POST_CHOMP is already set to CHOMP_COLLAPSE, using '-' will give you CHOMP_COLLAPSE behavior, not CHOMP_ALL behavior.
Similarly, '+' characters can be used to disable PRE_CHOMP or POST_CHOMP (i.e. leave the whites pace/newline intact) options on a per-directive basis.: [% FOREACH user = userlist %]
User: [% user +%]
[% END %]
With POST_CHOMP enabled, the above example would be parsed as if written:: [% FOREACH user = userlist %]User: [% user %]
[% END %]
INTERPOLATE: The INTERPOLATE flag, when set to any true value will
cause variable references in plain text (i.e. not sur
rounded by START_TAG and END_TAG) to be recognised and
interpolated accordingly.

my $parser = Template::Parser->new({
INTERPOLATE => 1,

});; Variables should be prefixed by a '$' to identify
them. Curly braces can be used in the familiar
Perl/shell style to explicitly scope the variable name
where required.

# INTERPOLATE => 0
<a href="http://[% server %]/[% help %]">
<img src="[% images %]/help.gif"></a>
[% myorg.name %]

# INTERPOLATE => 1
<a href="http://$server/$help">
<img src="$images/help.gif"></a>
$myorg.name

# explicit scoping with { }
<img src="$images/${icon.next}.gif">; Note that a limitation in Perl's regex engine
restricts the maximum length of an interpolated tem
plate to around 32 kilobytes or possibly less. Files
that exceed this limit in size will typically cause
Perl to dump core with a segmentation fault. If you
routinely process templates of this size then you
should disable INTERPOLATE or split the templates in
several smaller files or blocks which can then be
joined backed together via PROCESS or INCLUDE.
ANYCASE: By default, directive keywords should be expressed in
UPPER CASE. The ANYCASE option can be set to allow
directive keywords to be specified in any case.

# ANYCASE => 0 (default)
[% INCLUDE foobar %] # OK
[% include foobar %] # ERROR
[% include = 10 %] # OK, 'include' is a

variable

# ANYCASE => 1
[% INCLUDE foobar %] # OK
[% include foobar %] # OK
[% include = 10 %] # ERROR, 'include' is

reserved word; One side-effect of enabling ANYCASE is that you cannot
use a variable of the same name as a reserved word,
regardless of case. The reserved words are currently:

GET CALL SET DEFAULT INSERT INCLUDE PROCESS

WRAPPER; IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END
The only lower case reserved words that cannot be used for variables, regardless of the ANYCASE option, are the operators:: and or not mod div
V1DOLLAR: In version 1 of the Template Toolkit, an optional
leading '$' could be placed on any template variable
and would be silently ignored.

# VERSION 1
[% $foo %] === [% foo %]
[% $hash.$key %] === [% hash.key %]; To interpolate a variable value the '${' ... '}' con
struct was used. Typically, one would do this to
index into a hash array when the key value was stored
in a variable.; example:

my $vars = {
users => {
aba => { name => 'Alan Aardvark', ... },
abw => { name => 'Andy Wardley', ... },
...

},
uid => 'aba',
...

};

$template->process('user/home.html', $vars)

|| die $template->error(), "0;
'user/home.html':: [% user = users.${uid} %] # users.aba
Name: [% user.name %] # Alan Aardvark
This was inconsistent with double quoted strings and also the INTERPOLATE mode, where a leading '$' in text was enough to indicate a variable for interpolation, and the additional curly braces were used to delimit variable names where necessary. Note that this use is consistent with UNIX and Perl conventions, among oth ers.: # double quoted string interpolation
[% name = "$title ${user.name}" %]; # INTERPOLATE = 1
<img src="$images/help.gif"></a>
<img src="$images/${icon.next}.gif">
For version 2, these inconsistencies have been removed and the syntax clarified. A leading '$' on a variable is now used exclusively to indicate that the variable name should be interpolated (e.g. subsituted for its value) before being used. The earlier example from version 1:: # VERSION 1
[% user = users.${uid} %]
Name: [% user.name %]
can now be simplified in version 2 as:: # VERSION 2
[% user = users.$uid %]
Name: [% user.name %]
The leading dollar is no longer ignored and has the same effect of interpolation as '${' ... '}' in ver sion 1. The curly braces may still be used to explic itly scope the interpolated variable name where neces sary.
e.g.: [% user = users.${me.id} %]
Name: [% user.name %]
The rule applies for all variables, both within directives and in plain text if processed with the INTERPOLATE option. This means that you should no longer (if you ever did) add a leading '$' to a vari able inside a directive, unless you explicitly want it to be interpolated.
One obvious side-effect is that any version 1 tem plates with variables using a leading '$' will no longer be processed as expected. Given the following variable definitions,: [% foo = 'bar'
bar = 'baz'; %]
version 1 would interpret the following as:: # VERSION 1
[% $foo %] => [% GET foo %] => bar
whereas version 2 interprets it as:: # VERSION 2
[% $foo %] => [% GET $foo %] => [% GET bar %] =>; baz
In version 1, the '$' is ignored and the value for the variable 'foo' is retrieved and printed. In version 2, the variable '$foo' is first interpolated to give the variable name 'bar' whose value is then retrieved and printed.
The use of the optional '$' has never been strongly recommended, but to assist in backwards compatibility with any version 1 templates that may rely on this "feature", the V1DOLLAR option can be set to 1 (default: 0) to revert the behaviour and have leading '$' characters ignored.: my $parser = Template::Parser->new({
V1DOLLAR => 1,; });
GRAMMAR: The GRAMMAR configuration item can be used to specify
an alternate grammar for the parser. This allows a
modified or entirely new template language to be con
structed and used by the Template Toolkit.; Source templates are compiled to Perl code by the Tem
plate::Parser using the Template::Grammar (by default)
to define the language structure and semantics. Com
piled templates are thus inherently "compatible" with
each other and there is nothing to prevent any number
of different template languages being compiled and
used within the same Template Toolkit processing envi
ronment (other than the usual time and memory con
straints).; The Template::Grammar file is constructed from a YACC
like grammar (using Parse::YAPP) and a skeleton module
template. These files are provided, along with a
small script to rebuild the grammar, in the 'parser'
sub-directory of the distribution. You don't have to
know or worry about these unless you want to hack on
the template language or define your own variant.
There is a README file in the same directory which
provides some small guidance but it is assumed that
you know what you're doing if you venture herein. If
you grok LALR parsers, then you should find it com
fortably familiar.; By default, an instance of the default Template::Gram
mar will be created and used automatically if a GRAM
MAR item isn't specified.

use MyOrg::Template::Grammar;

my $parser = Template::Parser->new({
GRAMMAR = MyOrg::Template::Grammar->new();

});
parse($text)
The parse() method parses the text passed in the first parameter and returns a reference to a Template::Document object which contains the compiled representation of the template text. On error, undef is returned.
Example:: $doc = $parser->parse($text)
|| die $parser->error();

AUTHOR

Andy Wardley <abw@andywardley.com>

<http://www.andywardley.com/|http://www.andywardley.com/>

VERSION

2.65, distributed as part of the Template Toolkit version
2.08, released on 30 July 2002.

COPYRIGHT

Ltd.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The original Template::Parser module was derived from a standalone parser generated by version 0.16 of the Parse::Yapp module. The following copyright notice appears in the Parse::Yapp documentation.: The Parse::Yapp module and its related modules and; shell
scripts are copyright (c) 1998 Francois Desarmenien,
France. All rights reserved.; You may use and distribute them under the terms of ei; ther
the GNU General Public License or the Artistic Li; cense, as
specified in the Perl README file.

docs.sk

comprehensive documentation repository

In section