Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Parse::Template(3)    User Contributed Perl Documentation   Parse::Template(3)

NAME
       Parse::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.32.1			  2012-02-28		    Parse::Template(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | EXAMPLES | NOTES CONCERNING THE CURRENT VERSION | BUGS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Parse::Template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help