3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
6
<title>Template::Parser</title>
7
<link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
8
<link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
9
<link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
10
<link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
11
<link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
13
<link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
15
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
16
<script type="text/javascript" src="../../js/tt2.js"></script>
17
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
18
<meta name="author" content="Andy Wardley">
23
<a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
25
<li><a href="../../modules/index.html">Modules</a></li>
26
<li><a href="../../modules/Template/index.html">Template::*</a></li>
27
<li class="last"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
29
<div class="controls">
30
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
31
<span class="about">Click to view the menu. It's very nice.</span>
33
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
34
<span class="about">Click to hide the menu and go all widescreen!</span>
38
<a href="../../modules/Template/Namespace/index.html" title="Template::Namespace::* Modules" class="go back">Back<span class="about"><h4>Template::Namespace::* Modules</h4></span></a>
39
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
40
<a href="../../modules/Template/Plugin.html" title="Template::Plugin" class="go next">Next<span class="about"><h4>Template::Plugin</h4>Base class for Template Toolkit plugins</span></a>
43
<h1 class="headline">Template::Parser</h1>
44
<h2 class="subhead">LALR(1) parser for compiling template documents</h1>
49
<a href="../../index.html" id="logo"></a>
52
<li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
53
<li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
54
<li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
55
<li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
56
<li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
57
<li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
58
<li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
59
<li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
60
<li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
61
<li class="l2"><a href="../../modules/Template/Document.html">Document.pm</a></li>
62
<li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
63
<li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
64
<li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
65
<li class="l2"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
66
<li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
67
<li class="l2"><a href="../../modules/Template/Parser.html" class="warm">Parser.pm</a></li>
68
<li class="l2"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
69
<li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
70
<li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
71
<li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
72
<li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
73
<li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
74
<li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
75
<li class="l2"><a href="../../modules/Template/Test.html">Test.pm</a></li>
76
<li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
77
<li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
78
<li class="l0"><a href="../../tools/index.html">Tools</a></li>
79
<li class="l0 last"><a href="../../tutorial/index.html">Tutorial</a></li>
81
<div class="foot"></div>
87
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
88
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
92
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
93
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
94
<li class=""><a href="#PUBLIC_METHODS">PUBLIC METHODS</a></li>
95
<li class="sub"><a href="#method_new">new(\%params)</a></li>
96
<li class="sub"><a href="#method_parse">parse($text)</a></li>
97
<li class=""><a href="#CONFIGURATION_OPTIONS">CONFIGURATION OPTIONS</a></li>
98
<li class="sub"><a href="#section_START_TAG_END_TAG">START_TAG, END_TAG</a></li>
99
<li class="sub"><a href="#section_TAG_STYLE">TAG_STYLE</a></li>
100
<li class="sub"><a href="#section_PRE_CHOMP_POST_CHOMP">PRE_CHOMP, POST_CHOMP</a></li>
101
<li class="sub"><a href="#section_INTERPOLATE">INTERPOLATE</a></li>
102
<li class="sub"><a href="#section_ANYCASE">ANYCASE</a></li>
103
<li class="sub"><a href="#section_GRAMMAR">GRAMMAR</a></li>
104
<li class="sub"><a href="#section_DEBUG">DEBUG</a></li>
105
<li class=""><a href="#AUTHOR">AUTHOR</a></li>
106
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
107
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
114
<div class="section">
116
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
117
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
120
<pre>use Template::Parser;
122
$parser = Template::Parser->new(\%config);
123
$template = $parser->parse($text)
124
|| die $parser->error(), "\n";</pre>
127
<div class="section">
129
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
130
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
134
The <code>Template::Parser</code> module implements a LALR(1) parser and
135
associated methods for parsing template documents into Perl code.
139
<div class="section">
141
<h1 id="PUBLIC_METHODS" onclick="switch_section(this)" title="Click title to show/hide section content.">PUBLIC METHODS</h1>
142
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
145
<div class="subsection">
147
<h2 id="method_new" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">new(\%params)</h2>
148
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
152
The <code>new()</code> constructor creates and returns a reference to a
153
new <code>Template::Parser</code> object.
156
A reference to a hash may be supplied as a parameter to provide
157
configuration values. See <a href="#CONFIGURATION_OPTIONS">CONFIGURATION
158
OPTIONS</a> below for a summary of these options and <a href="../../manual/Config.html">Template::Manual::Config</a>
161
<pre>my $parser = Template::Parser->new({
162
START_TAG => quotemeta('<+'),
163
END_TAG => quotemeta('+>'),
166
</div> <div class="subsection">
168
<h2 id="method_parse" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">parse($text)</h2>
169
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
173
The <code>parse()</code> method parses the text passed in the first
174
parameter and returns a reference to a hash array of data defining the
175
compiled representation of the template text, suitable for passing to the
176
<a href="../../modules/Template/Document.html">Template::Document</a>
177
<a href="../../modules/Template/Document.html#method_new">new()</a>
178
constructor method. On error, undef is returned.
180
<pre>$data = $parser->parse($text)
181
|| die $parser->error();</pre>
183
The <code>$data</code> hash reference returned contains a
184
<code>BLOCK</code> item containing the compiled Perl code for the
185
template, a <code>DEFBLOCKS</code> item containing a reference to a hash
186
array of sub-template <code>BLOCK</code>s defined within in the template,
187
and a <code>METADATA</code> item containing a reference to a hash array
188
of metadata values defined in <code>META</code> tags.
194
<div class="section">
196
<h1 id="CONFIGURATION_OPTIONS" onclick="switch_section(this)" title="Click title to show/hide section content.">CONFIGURATION OPTIONS</h1>
197
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
201
The <code>Template::Parser</code> module accepts the following
202
configuration options. Please see <a href="../../manual/Config.html">Template::Manual::Config</a>
203
for futher details on each option.
205
<div class="subsection">
207
<h2 id="section_START_TAG_END_TAG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">START_TAG, END_TAG</h2>
208
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
212
The <a href="../../manual/Config.html#section_START_TAG_END_TAG">START_TAG</a> and <a href="../../manual/Config.html#section_START_TAG_END_TAG">END_TAG</a> options are used to specify
213
character sequences or regular expressions that mark the start and end of
214
a template directive.
216
<pre>my $parser = Template::Parser->new({
217
START_TAG => quotemeta('<+'),
218
END_TAG => quotemeta('+>'),
221
</div> <div class="subsection">
223
<h2 id="section_TAG_STYLE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TAG_STYLE</h2>
224
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
228
The <a href="../../manual/Config.html#section_TAG_STYLE">TAG_STYLE</a> option can be used to set both <a
229
href="#section_START_TAG">START_TAG</a> and <a
230
href="#section_END_TAG">END_TAG</a> according to pre-defined tag styles.
232
<pre>my $parser = Template::Parser->new({
233
TAG_STYLE => 'star', # [* ... *]
236
</div> <div class="subsection">
238
<h2 id="section_PRE_CHOMP_POST_CHOMP" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PRE_CHOMP, POST_CHOMP</h2>
239
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
243
The <a href="../../manual/Config.html#section_PRE_CHOMP_POST_CHOMP">PRE_CHOMP</a> and <a href="../../manual/Config.html#section_PRE_CHOMP_POST_CHOMP">POST_CHOMP</a> can be set to remove any
244
whitespace before or after a directive tag, respectively.
246
<pre>my $parser = Template::Parser-E<gt>new({
251
</div> <div class="subsection">
253
<h2 id="section_INTERPOLATE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">INTERPOLATE</h2>
254
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
258
The <a href="../../manual/Config.html#section_INTERPOLATE">INTERPOLATE</a> flag can be set to allow
259
variables to be embedded in plain text blocks.
261
<pre>my $parser = Template::Parser->new({
265
Variables should be prefixed by a <code>$</code> to identify them, using
266
curly braces to explicitly scope the variable name where necessary.
270
The day today is ${day.today}.</pre>
272
</div> <div class="subsection">
274
<h2 id="section_ANYCASE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ANYCASE</h2>
275
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
279
The <a href="../../manual/Config.html#section_ANYCASE">ANYCASE</a> option can be set to allow directive
280
keywords to be specified in any case.
282
<pre># with ANYCASE set to 1
283
[% INCLUDE foobar %] # OK
284
[% include foobar %] # OK
285
[% include = 10 %] # ERROR, 'include' is a reserved word</pre>
287
</div> <div class="subsection">
289
<h2 id="section_GRAMMAR" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">GRAMMAR</h2>
290
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
294
The <a href="../../manual/Config.html#section_GRAMMAR">GRAMMAR</a> configuration item can be used to
295
specify an alternate grammar for the parser. This allows a modified or
296
entirely new template language to be constructed and used by the Template
299
<pre>use MyOrg::Template::Grammar;
301
my $parser = Template::Parser->new({
302
GRAMMAR = MyOrg::Template::Grammar->new();
305
By default, an instance of the default <a href="../../modules/Template/Grammar.html">Template::Grammar</a> will be created
306
and used automatically if a <code>GRAMMAR</code> item isn't specified.
309
</div> <div class="subsection">
311
<h2 id="section_DEBUG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEBUG</h2>
312
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
316
The <a href="../../manual/Config.html#section_DEBUG">DEBUG</a> option can be used to enable various
317
debugging features of the <code>Template::Parser</code> module.
319
<pre>use Template::Constants qw( :debug );
321
my $template = Template->new({
322
DEBUG => DEBUG_PARSER | DEBUG_DIRS,
328
<div class="section">
330
<h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
331
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
335
Andy Wardley <abw@wardley.org> <a
336
href="http://wardley.org/">http://wardley.org/</a>
340
<div class="section">
342
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
343
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
347
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
350
This module is free software; you can redistribute it and/or modify it
351
under the same terms as Perl itself.
354
The main parsing loop of the <code>Template::Parser</code> module was
355
derived from a standalone parser generated by version 0.16 of the
356
<code>Parse::Yapp</code> module. The following copyright notice appears
357
in the <code>Parse::Yapp</code> documentation.
359
<pre>The Parse::Yapp module and its related modules and shell
360
scripts are copyright (c) 1998 Francois Desarmenien,
361
France. All rights reserved.
363
You may use and distribute them under the terms of either
364
the GNU General Public License or the Artistic License, as
365
specified in the Perl README file.</pre>
368
<div class="section">
370
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
371
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
375
<a href="../../modules/Template.html">Template</a>, <a href="../../modules/Template/Grammar.html">Template::Grammar</a>, <a href="../../modules/Template/Directive.html">Template::Directive</a>
382
<div class="pageinfo">
383
/modules/Template/Parser.html last modified 10:54:56 31-May-2007
388
<a href="http://opensource.org/" class="osi"></a>
389
<div class="controls">
391
<a href="../../modules/Template/Namespace/index.html" title="Template::Namespace::* Modules" class="go back">Back<span class="about"><h4>Template::Namespace::* Modules</h4></span></a>
392
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
393
<a href="../../modules/Template/Plugin.html" title="Template::Plugin" class="go next">Next<span class="about"><h4>Template::Plugin</h4></span></a>
396
<div class="copyright">
397
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
399
<div class="licence">
400
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
401
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
402
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
407
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
408
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
409
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
410
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
411
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>