NAME

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

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

  <P><B>text in bold</B><I>text in italic</I></P>

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

  join '', @_

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

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

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

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

  Use of inherited AUTOLOAD for non-method %s() is deprecated

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

  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();

NOTES CONCERNING THE CURRENT VERSION

BUGS

AUTHOR

COPYRIGHT