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.  See
       "CONFIGURATION OPTIONS" below for a summary of these options and Template::Manual::Config
       for full details.

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

   parse($text)
       The "parse()" method parses the text passed in the first parameter and returns a reference
       to a hash array of data defining the compiled representation of the template text,
       suitable for passing to the Template::Document new() constructor method. On error, undef
       is returned.

           $data = $parser->parse($text)
               || die $parser->error();

       The $data hash reference returned contains a "BLOCK" item containing the compiled Perl
       code for the template, a "DEFBLOCKS" item containing a reference to a hash array of sub-
       template "BLOCK"s defined within in the template, and a "METADATA" item containing a
       reference to a hash array of metadata values defined in "META" tags.

CONFIGURATION OPTIONS

       The "Template::Parser" module accepts the following configuration options.  Please see
       Template::Manual::Config for futher details on each option.

   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.

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

   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',     # [* ... *]
           });

   PRE_CHOMP, POST_CHOMP
       The PRE_CHOMP and POST_CHOMP can be set to remove any whitespace before or after a
       directive tag, respectively.

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

   INTERPOLATE
       The INTERPOLATE flag can be set to allow variables to be embedded in plain text blocks.

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

       Variables should be prefixed by a "$" to identify them, using curly braces to explicitly
       scope the variable name where necessary.

           Hello ${name},

           The day today is ${day.today}.

   ANYCASE
       The ANYCASE option can be set to allow directive keywords to be specified in any case.

           # with ANYCASE set to 1
           [% INCLUDE foobar %]    # OK
           [% include foobar %]    # OK
           [% include = 10   %]    # ERROR, 'include' is a reserved word

   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 constructed and used by the
       Template Toolkit.

           use MyOrg::Template::Grammar;

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

       By default, an instance of the default Template::Grammar will be created and used
       automatically if a "GRAMMAR" item isn't specified.

   DEBUG
       The DEBUG option can be used to enable various debugging features of the
       "Template::Parser" module.

           use Template::Constants qw( :debug );

           my $template = Template->new({
               DEBUG => DEBUG_PARSER | DEBUG_DIRS,
           });

AUTHOR

       Andy Wardley <abw@wardley.org> <http://wardley.org/>

COPYRIGHT

       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       The main parsing loop of the "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.

SEE ALSO

       Template, Template::Grammar, Template::Directive