/ 
ParseTemplate-0.31
River stage one • 1 direct dependent • 6 total dependents
/ Parse::Template

NAME

Parse::Template - Processor for templates containing Perl expressions (0.40)

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_value'}$N"%%! .
             q!3. File content: %%print <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_value' => q!It\'s an hash value! });
print $tmplt->eval('TOP'), "\n";

DESCRIPTION

The Parse::Template class permits evaluating 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 tagged areas with expressions to be evaluated. Interpretation of these expressions generates text fragments which are substituted in place of the expressions.

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.

Data used in generating missing parts can come from the environment or can be the result of queries performed by the expressions.

             Template
          Text + Perl Expression 
		|
		+-----> Evaluation ----> Text(document, program)
		|	
	   Subs + Data structures
            Environment

With the class Parse::Template a template can be decomposed into parts. These parts are defined by a hash passed as an argument to the new() method: 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. You can choose to specify only the name of the part, and in this case a subroutine with the name of the part will be dynamically generated. In the example given in the synopsis, the insertion of the TOP part can 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.

An argument can be 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);

$part and $self variables are defined by default and can be used in expressions. $self is the template instance, $part the template part name.

The env() method permits constructing the environment required for evaluation of a template. Each entry to be defined within the 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 created entry (for example, a reference to an array to create an array). A scalar variable is defined by declaring a name for the variable, associated 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 from the Parse::Template class.

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 some illustrations.

The first example shows how to generate an HTML document by using a data structure placed within the evaluation environment:

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";

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>

by using

P(B("text in bold"), I("text in italic"))

The Perl expression that permits producing this kind of structure 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 if we know that the lexical variable $part is defined by default in the environment of evaluation of the template:

$ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!;
$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:

$DOC = q!P(B("text in bold"), I("text in italic"))!;

$ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!;
$HTML_T3 = new Parse::Template(
     'DOC' => qq!%%$DOC%%!,
     map { $_ => $ELT_CONTENT } qw(P B I)
    );
print $HTML_T3->eval('DOC'), "\n";

With a final transformation it is possible to use a method-call notation to proceed with the generation:

 $ELT_CONTENT = q!%%shift(@_); "<$part>" . join('', @_) . "</$part>"%%!;

 $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";

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

This is an experimental module. I would be very interested to receive your comments and suggestions.

BUG

Instances are not destroyed. Therefore, do not use this class to create a large number of instances.

AUTHOR

Philippe Verdret (with translation of documentation by Ocrat)

COPYRIGHT

Copyright (c) 1995-1999 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.