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(), "\n";

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 function) if they are intended to represent literal characters.

  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 => 'php',
  });

Available styles are:

template    [% ... %]               (default)
template1   [% ... %] or %% ... %%  (Template version 1)
metatext    %% ... %%               (Text::MetaText)
php         <? ... ?>               (PHP)
asp         <% ... %>               (ASP)
mason       <% ...  >               (HTML::Mason)
html        <!-- ... -->            (HTML comments)

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 %]
<!-- INCLUDE header -->

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 directive tags. Any 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 disabled by default.

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

With PRE_CHOMP set true, the newline and whitespace preceeding 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 previous line.

	Foo <----------.
		       |
   ,---(PRE_CHOMP)----'
   |
   `-- [% a = 10 %] --.
		       |
   ,---(POST_CHOMP)---'
   |
   `-> Bar

With POST_CHOMP set true, 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.

PRE_CHOMP and POST_CHOMP can be activated for individual 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 %]

Similarly, '+' characters can be used to disable PRE_CHOMP or POST_CHOMP (i.e. leave the whitespace/newline intact) options on a per-directive basis.

[% FOREACH user = userlist %]
User: [% user +%]
[% END %]

With POST_CHOMP set on, 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 surrounded 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">

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 FORNEXT WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL 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 '${' ... '}' construct 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(), "\n";

'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 others.

# 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 version 1. The curly braces may still be used to explicitly scope the interpolated variable name where necessary.

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 variable inside a directive, unless you explicitly want it to be interpolated.

One obvious side-effect is that any version 1 templates 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 langauge to be constructed and used by the Template Toolkit.

Source templates are compiled to Perl code by the Template::Parser using the Template::Grammar (by default) to define the language structure and semantics. Compiled 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 environment (other than the usual time and memory constraints).

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 comfortably familiar.

By default, an instance of the default Template::Grammar will be created and used automatically if a GRAMMAR 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@kfs.org>

http://www.template-toolkit.org/
http://www.kfs.org/~abw/

REVISION

$Revision: 1.1 $

COPYRIGHT

Copyright (C) 1996-2000 Andy Wardley.  All Rights Reserved.
Copyright (C) 1998-2000 Canon Research Centre Europe 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 either
the GNU General Public License or the Artistic License, as
specified in the Perl README file.

The tpage and ttree scripts are distributed and installed along with the Template Toolkit. The tpage script simply processes named files or STDIN if unspecified, using a default Template object. The ttree script can be used to process entire directory trees of templates, allowing large content systems such as web sites to be rebuilt from a single command or configuration file.

perldoc tpage
perldoc ttree

The Template::Tutorial document provides an introduction to the Template Toolkit and shows some typical examples of usage.

perldoc Template::Tutorial

You may also like to consult the paper 'Building and Managing Web Systems with the Template Toolkit' and accompanying slides from the presentation at the 4th Perl Conference. These are available from the Template Toolkit web site:

http://www.template-toolkit.org/docs.html

The following modules comprise the Template Toolkit. Consult the individual documentation for further details.

Template::Service: The Template::Service module handles the template processing lifecycle, adding PRE_PROCESS and POST_PROCESS templates, handling redirection through any defined PROCESS template, and dispatching any ERROR templates to handle uncaught exceptions. The actual processing of these templates is handled by an underlying Template::Context object.
Template::Context: The Template::Context module defines a class of objects which each represent a unique run-time environment in which templates are processed. The context maintains references to the stash of variables currently defined (Template::Stash) and to provider objects for templates (Template::Provider), filters (Template::Filters) and plugins (Template::Plugins).
Template::Stash: The Template::Stash module defines an object class which is used for storing, retrieving and evaluating variables and their values.
Template::Provider: The Template::Provider module defines an object class which is used to find, load, parse, compile and then cache template documents. The cache implements a simple fetch($template) method which will accept a wide range of inputs (filename, text ref, GLOB, IO::Handle, etc) and attempt to read the template and call on a Template::Parser to parse and compile it to a Template::Document which is then cached.
Template::Document: Template::Document objects are thin wrappers around the Perl subroutines which have been compiled from source templates by the Template::Parser. These objects also maintain any metadata values for the template and have references to any BLOCKs defined within the the template.
Template::Parser: The Template::Parser module defines an object class which implements the template parser and compiler. The template text is first scanned by a Perl regex which extracts the embedded directives and lexes the tokens contained within. A DFA (Deterministic Finite-state Automaton) then iterates through the tokens using the rules and states defined in Template::Grammar and generates a compiled template document as a Perl subroutine.
Template::Grammar: The Template::Grammar module defines the rules and state tables for the Template::Parser DFA. These are generated by the Parse::Yapp module. The Template-Toolkit distribution contains a parser directory which contains further files and information concerning the grammar and compilation thereof.
Template::Directive: This module implements a number of factory methods which are used by the Template::Parser to generate Perl code from source templates.
Template::Filters: This module implements the various FILTER subroutines and provides a simple interface through which filter subs can be retrieved.
Template::Plugins: This module provides access to the standard Template Toolkit or user defined plugin modules.
Template::Plugin: Base class for Template::Plugin::* modules.
Template::Exception: The Template::Exception module defines an exception type for representing error conditions within the Template Toolkit.
Template::Iterator: The Template::Iterator module defines a data iterator which is used by the FOREACH directive. This may be sub-classed to create more specialised iterators for traversing data sets.
Template::Constants: Defines various constants used in the Template Toolkit.
Template::Config: Implements a number of factory methods through which other Template::* modules can be automatically loaded and instantiated.
Template::Base: A common base class for many Template::* modules.
Template::Test: Module for testing the Template Toolkit, primarily used by the test scripts in the 't' distribution sub-directory.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 445:: =over without closing =back

To install Template, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Template

CPAN shell

perl -MCPAN -e shell
install Template

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)