Parse::Template(3) User Contributed Perl Documentation Parse::Template(3)NAMEParse::Template - Processor for templates containing Perl expressions
SYNOPSIS
use Parse::Template;
my %template =
(
'TOP' => q!Text before %%$self->eval('DATA')%% text after!,
'DATA' => q!Insert data: ! .
q!1. List: %%"@list$N"%%! .
q!2. Hash: %%"$hash{'key'}$N"%%! .
q!3. File content: %%<FH>%%! .
q!4. Sub: %%&SUB()$N%%!
);
my $tmplt = new Parse::Template (%template);
open FH, "< foo";
$tmplt->env('var' => '(value!)');
$tmplt->env('list' => [1, 2, 10],
'N' => "\n",
'FH' => \*FH,
'SUB' => sub { "->content generated by a sub<-" },
'hash' => { 'key' => q!It\'s an hash value! });
print $tmplt->eval('TOP'), "\n";
DESCRIPTION
The "Parse::Template" class evaluates Perl expressions placed within a
text. This class can be used as a code generator, or a generator of
documents in various document formats (HTML, XML, RTF, etc.).
The principle of template-based text generation is simple. A template
consists of a text which includes expressions to be evaluated.
Interpretation of these expressions generates text fragments which are
substituted in place of the expressions. In the case of
"Parse::Template" the expressions to be evaluated are Perl expressions
placed within two "%%".
Evaluation takes place within an environment in which, for example, you
can place data structures which will serve to generate the parts to be
completed.
TEMPLATE
Text + Perl Expression
|
+-----> Evaluation ----> Text(document or program)
|
Subs + Data structures
ENVIRONMENT
The "Parse::Template" class permits decomposing a template into parts.
These parts are defined by a hash passed as an argument to the class
constructor: "Parse::Template-">"new('someKey', '... text with
expressions to evaluate ...')". Within a part, a sub-part can be
included by means of an expression of the form:
$self->eval('SUB_PART_NAME')
$self designates the instance of the "Parse::Template" class. In an
expression you can also use the $part which contains the part of the
template where the expression is found.
Within an expression it is possible to specify only the name of a part
to be inserted. In this case a subroutine with the name of this part
is generated dynamically. In the example given in the synopsis, the
insertion of the "TOP" part can thus be rewritten as follows:
'TOP' => q!Text before %%DATA()%% text after!
"DATA()" is placed within "%%" and is in effect treated as an
expression to be evaluated.
The subroutines take arguments. In the following example, the argument
is used to control the depth of recursive calls of a template:
print Parse::Template->new(
'TOP' => q!%%$_[0] < 10 ? '[' . TOP($_[0] + 1) . ']' : ''%%!
)->eval('TOP', 0);
$_[0] initially contains 0. "TOP" is included as long as the argument
is less than 10. For each inclusion, 1 is added to the argument.
The "env()" method permits constructing the environment required for
evaluation of a template. Each entry to be defined within this
environment must be specified using a key consisting of the name of the
symbol to be created, associated with a reference whose type is that of
the entry to be created within this environment (for example, a
reference to an array to create an array). A scalar variable is
defined by associating the name of the variable with its value. A
scalar variable containing a reference is defined by writing
"'var'=">"\$variable", where $variable is a lexical variable that
contains the reference.
Each instance of "Parse::Template" is defined within a specific class,
a subclass of "Parse::Template". The subclass contains the environment
specific to the template and inherits methods from the
"Parse::Template" class.
If a template is created from an existing template (i.e. calling "new"
as a method of the existing template), it inherits all the parts
defined by its ancestor.
In case of a syntax error in the evalutaion of an expression,
"Parse::Template" tries to indicate the template part and the
expression that is "incriminated". If the variable
$Parse::Template::CONFESS contains the value TRUE, the stack of
evaluations is printed.
METHODS
new HASH
Constructor for the class. "HASH" is a hash which defines the
template text.
Example:
use Parse::Template;
$t = new Parse::Template('key' => 'associated text');
env HASH
env SYMBOL
Permits defining the environment that is specific to a template.
"env(SYMBOL)" returns the reference associated with the symbol, or
"undef" if the symbol is not defined. The reference that is
returned is of the type indicated by the character ("&, $, %, @,
*") that prefixes the symbol.
Examples:
$tmplt->env('LIST' => [1, 2, 3])} Defines a list
@{$tmplt->env('*LIST')} Returns the list
@{$tmplt->env('@LIST')} Ditto
eval PART_NAME
Evaluates the template part designated by "PART_NAME". Returns the
string resulting from this evaluation.
getPart PART_NAME
Returns the designated part of the template.
ppregexp REGEXP
Preprocesses a regular expression so that it can be inserted into a
template where the regular expression delimiter is either a "/" or
a "!".
setPart PART_NAME => TEXT
"setPart()" permits defining a new entry in the hash that defines
the contents of the template.
EXAMPLES
The "Parse::Template" class can be used in all sorts of amusing ways.
Here are a few illustrations.
HTML Generator
The first example shows how to generate an HTML document by using a
data structure placed within the evaluation environment. The template
consists of two parts, "DOC" and "SECTION". The "SECTION" part is
called within the "DOC" part to generate as many sections as there are
elements in the array "section_content".
my %template = ('DOC' => <<'END_OF_DOC;', 'SECTION' => <<'END_OF_SECTION;');
<html>
<head></head>
<body>
%%
my $content;
for (my $i = 0; $i <= $#section_content; $i++) {
$content .= SECTION($i);
}
$content;
%%
</body>
</html>
END_OF_DOC;
%%
$section_content[$_[0]]->{Content} =~ s/^/<p>/mg;
join '', '<H1>', $section_content[$_[0]]->{Title}, '</H1>',
$section_content[$_[0]]->{Content};
%%
END_OF_SECTION;
my $tmplt = new Parse::Template (%template);
$tmplt->env('section_content' => [
{
Title => 'First Section',
Content => 'Nothing to write'
},
{
Title => 'Second section',
Content => 'Nothing else to write'
}
]
);
print $tmplt->eval('DOC'), "\n";
HTML generation using functional notation
The second example shows how to generate an HTML document using a
functional notation, in other words, obtaining the text:
<P><B>text in bold</B><I>text in italic</I></P>
from:
P(B("text in bold"), I("text in italic"))
The functions P(), B() and I() are defined as parts of a template. The
Perl expression that permits producing the content of an element is
very simple, and reduces to:
join '', @_
The content to be evaluated is the same regardless of the tag and can
therefore be placed within a variable. We therefore obtain the
following template:
my $ELT_CONTENT = q!%%join '', @_%%!;
my $HTML_T1 = new Parse::Template(
'DOC' => '%%P(B("text in bold"), I("text in italic"))%%',
'P' => qq!<P>$ELT_CONTENT</P>!,
'B' => qq!<B>$ELT_CONTENT</B>!,
'I' => qq!<I>$ELT_CONTENT</I>!,
);
print $HTML_T1->eval('DOC'), "\n";
We can go further by making use of the $part variable, which is defined
by default in the environment of evaluation of the template:
my $ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!;
my $HTML_T2 = new Parse::Template(
'DOC' => '%%P(B("text in bold"), I("text in italic"))%%',
'P' => qq!$ELT_CONTENT!,
'B' => qq!$ELT_CONTENT!,
'I' => qq!$ELT_CONTENT!,
);
print $HTML_T2->eval('DOC'), "\n";
Let's look at another step which automates the production of
expressions from the list of HTML tags which are of interest to us:
my $DOC = q!P(B("text in bold"), I("text in italic"))!;
my $ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!;
my $HTML_T3 = new Parse::Template(
'DOC' => qq!%%$DOC%%!,
map { $_ => $ELT_CONTENT } qw(P B I)
);
print $HTML_T3->eval('DOC'), "\n";
To benefit from the possibility of using the template parts as
procedures, we can inherit from the generated template class:
use Parse::Template;
my $ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!;
my $G = new Parse::Template(
map { $_ => $ELT_CONTENT } qw(H1 B I)
);
@main::ISA = ref($G);
*AUTOLOAD = \&Parse::Template::AUTOLOAD;
print H1(B("text in bold"), I("text in italic"));
The reference to "Parse::Template::AUTOLOAD" avoids the warning
message:
Use of inherited AUTOLOAD for non-method %s() is deprecated
Not very elegant.
HTML generation by method call
With a slight transformation it is possible to use a method-invocation
notation:
my $ELT_CONTENT = q!%%shift(@_); "<$part>" . join('', @_) . "</$part>"%%!;
my $HTML_T4 = new Parse::Template(
map { $_ => $ELT_CONTENT } qw(P B I)
);
print $HTML_T4->P(
$HTML_T4->B("text in bold"),
$HTML_T4->I("text in italic")
), "\n";
The "shift(@_)" permits getting rid of the template object, which we
don't need within the expression.
Inheritance of parts
In the following example the child template $C inherits the parts
defined in its parent template $A:
my %ancestor =
(
'TOP' => q!%%"Use the $part model and -> " . CHILD()%%!,
'ANCESTOR' => q!ANCESTOR %%"'$part' part\n"%%!,
);
my %child =
(
'CHILD' => q!CHILD %%"'$part' part"%% -> %%ANCESTOR() . "\n"%%!,
);
my $A = new Parse::Template (%ancestor);
my $C = $A->new(%child);
print $C->TOP();
The part <TOP> defined in $A can be called directly from $C, that
derives from $A.
Other examples
"Parse::Template" was initially created to serve as a code generator
for the "Parse::Lex" class. You will find other examples of its use in
the classes "Parse::Lex", "Parse::CLex" and "Parse::Token".
NOTES CONCERNING THE CURRENT VERSION
I would be very interested to receive your comments and suggestions.
BUGS
Instances are not destroyed. Therefore, do not use this class to
create a large number of instances.
AUTHOR
Philippe Verdret (with translation of documentation into English by
Ocrat)
COPYRIGHT
Copyright (c) 1995-2001 Philippe Verdret. All rights reserved. This
module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
perl v5.14.0 2010-04-03 Parse::Template(3)
