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

FreeBSD Manual Pages

  
 
  

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

NAME
       Text::Template -	Expand template	text with embedded Perl

VERSION
       version 1.59

SYNOPSIS
	use Text::Template;

	$template = Text::Template->new(TYPE =>	'FILE',	 SOURCE	=> 'filename.tmpl');
	$template = Text::Template->new(TYPE =>	'ARRAY', SOURCE	=> [ ... ] );
	$template = Text::Template->new(TYPE =>	'FILEHANDLE', SOURCE =>	$fh );
	$template = Text::Template->new(TYPE =>	'STRING', SOURCE => '...' );
	$template = Text::Template->new(PREPEND	=> q{use strict;}, ...);

	# Use a	different template file	syntax:
	$template = Text::Template->new(DELIMITERS => [$open, $close], ...);

	$recipient = 'King';
	$text =	$template->fill_in();  # Replaces `{$recipient}' with `King'
	print $text;

	$T::recipient =	'Josh';
	$text =	$template->fill_in(PACKAGE => T);

	# Pass many variables explicitly
	$hash =	{ recipient => 'Abed-Nego',
		  friends => [ 'me', 'you' ],
		  enemies => { loathsome => 'Saruman',
			       fearsome	=> 'Sauron' },
		};
	$text =	$template->fill_in(HASH	=> $hash, ...);
	# $recipient is	Abed-Nego,
	# @friends is (	'me', 'you' ),
	# %enemies is (	loathsome => ..., fearsome => ... )

	# Call &callback in case of programming	errors in template
	$text =	$template->fill_in(BROKEN => \&callback, BROKEN_ARG => $ref, ...);

	# Evaluate program fragments in	Safe compartment with restricted permissions
	$text =	$template->fill_in(SAFE	=> $compartment, ...);

	# Print	result text instead of returning it
	$success = $template->fill_in(OUTPUT =>	\*FILEHANDLE, ...);

	# Parse	template with different	template file syntax:
	$text =	$template->fill_in(DELIMITERS => [$open, $close], ...);
	# Note that this is *faster* than using	the default delimiters

	# Prepend specified perl code to each fragment before evaluating:
	$text =	$template->fill_in(PREPEND => q{use strict 'vars';}, ...);

	use Text::Template 'fill_in_string';
	$text =	fill_in_string(	<<'EOM', PACKAGE => 'T', ...);
	Dear {$recipient},
	Pay me at once.
	       Love,
		G.V.
	EOM

	use Text::Template 'fill_in_file';
	$text =	fill_in_file($filename,	...);

	# All templates	will always have `use strict vars' attached to all fragments
	Text::Template->always_prepend(q{use strict 'vars';});

DESCRIPTION
       This is a library for generating	form letters, building HTML pages, or
       filling in templates generally.	A `template' is	a piece	of text	that
       has little Perl programs	embedded in it here and	there.	When you `fill
       in' a template, you evaluate the	little programs	and replace them with
       their values.

       You can store a template	in a file outside your program.	 People	can
       modify the template without modifying the program.  You can separate
       the formatting details from the main code, and put the formatting parts
       of the program into the template.  That prevents	code bloat and
       encourages functional separation.

   Example
       Here's an example of a template,	which we'll suppose is stored in the
       file "formletter.tmpl":

	   Dear	{$title} {$lastname},

	   It has come to our attention	that you are delinquent	in your
	   {$monthname[$last_paid_month]} payment.  Please remit
	   ${sprintf("%.2f", $amount)} immediately, or your patellae may
	   be needlessly endangered.

			   Love,

			   Mark	"Vizopteryx" Dominus

       The result of filling in	this template is a string, which might look
       something like this:

	   Dear	Mr. Smith,

	   It has come to our attention	that you are delinquent	in your
	   February payment.  Please remit
	   $392.12 immediately,	or your	patellae may
	   be needlessly endangered.

			   Love,

			   Mark	"Vizopteryx" Dominus

       Here is a complete program that transforms the example template into
       the example result, and prints it out:

	   use Text::Template;

	   my $template	= Text::Template->new(SOURCE =>	'formletter.tmpl')
	     or	die "Couldn't construct	template: $Text::Template::ERROR";

	   my @monthname = qw(January February March April May June
			      July August September October November December);
	   my %vars = (title	       => 'Mr.',
		       firstname       => 'John',
		       lastname	       => 'Smith',
		       last_paid_month => 1,   # February
		       amount	       => 392.12,
		       monthname       => \@monthname);

	   my $result =	$template->fill_in(HASH	=> \%vars);

	   if (defined $result)	{ print	$result	}
	   else	{ die "Couldn't	fill in	template: $Text::Template::ERROR" }

   Philosophy
       When people make	a template module like this one, they almost always
       start by	inventing a special syntax for substitutions.  For example,
       they build it so	that a string like "%%VAR%%" is	replaced with the
       value of	$VAR.  Then they realize the need extra	formatting, so they
       put in some special syntax for formatting.  Then	they need a loop, so
       they invent a loop syntax.  Pretty soon they have a new little template
       language.

       This approach has two problems: First, their little language is
       crippled. If you	need to	do something the author	hasn't thought of, you
       lose.  Second: Who wants	to learn another language?  You	already	know
       Perl, so	why not	use it?

       "Text::Template"	templates are programmed in Perl.  You embed Perl code
       in your template, with "{" at the beginning and "}" at the end.	If you
       want a variable interpolated, you write it the way you would in Perl.
       If you need to make a loop, you can use any of the Perl loop
       constructions.  All the Perl built-in functions are available.

Details
   Template Parsing
       The "Text::Template" module scans the template source.  An open brace
       "{" begins a program fragment, which continues until the	matching close
       brace "}".  When	the template is	filled in, the program fragments are
       evaluated, and each one is replaced with	the resulting value to yield
       the text	that is	returned.

       A backslash "\" in front	of a brace (or another backslash that is in
       front of	a brace) escapes its special meaning.  The result of filling
       out this	template:

	   \{ The sum of 1 and 2 is {1+2}  \}

       is

	   { The sum of	1 and 2	is 3  }

       If you have an unmatched	brace, "Text::Template"	will return a failure
       code and	a warning about	where the problem is.  Backslashes that	do not
       precede a brace are passed through unchanged.  If you have a template
       like this:

	   { "String that ends in a newline.\n"	}

       The backslash inside the	string is passed through to Perl unchanged, so
       the "\n"	really does turn into a	newline.  See the note at the end for
       details about the way backslashes work.	Backslash processing is	not
       done when you specify alternative delimiters with the "DELIMITERS"
       option.	(See "Alternative Delimiters", below.)

       Each program fragment should be a sequence of Perl statements, which
       are evaluated the usual way.  The result	of the last statement executed
       will be evaluated in scalar context; the	result of this statement is a
       string, which is	interpolated into the template in place	of the program
       fragment	itself.

       The fragments are evaluated in order, and side effects from earlier
       fragments will persist into later fragments:

	   {$x = @things; ''}The Lord High Chamberlain has gotten {$x}
	   things for me this year.
	   { $diff = $x	- 17;
	     $more = 'more'
	     if	($diff == 0) {
	       $diff = 'no';
	     } elsif ($diff < 0) {
	       $more = 'fewer';
	     }
	     '';
	   }
	   That	is {$diff} {$more} than	he gave	me last	year.

       The value of $x set in the first	line will persist into the next
       fragment	that begins on the third line, and the values of $diff and
       $more set in the	second fragment	will persist and be interpolated into
       the last	line.  The output will look something like this:

	   The Lord High Chamberlain has gotten	42
	   things for me this year.

	   That	is 25 more than	he gave	me last	year.

       That is all the syntax there is.

   The $OUT variable
       There is	one special trick you can play in a template.  Here is the
       motivation for it:  Suppose you are going to pass an array, @items,
       into the	template, and you want the template to generate	a bulleted
       list with a header, like	this:

	   Here	is a list of the things	I have got for you since 1907:
	     * Ivory
	     * Apes
	     * Peacocks
	     * ...

       One way to do it	is with	a template like	this:

	   Here	is a list of the things	I have got for you since 1907:
	   { my	$blist = '';
	     foreach $i	(@items) {
		 $blist	.= qq{	* $i\n};
	     }
	     $blist;
	   }

       Here we construct the list in a variable	called $blist, which we	return
       at the end.  This is a little cumbersome.  There	is a shortcut.

       Inside of templates, there is a special variable	called $OUT.  Anything
       you append to this variable will	appear in the output of	the template.
       Also, if	you use	$OUT in	a program fragment, the	normal behavior, of
       replacing the fragment with its return value, is	disabled; instead the
       fragment	is replaced with the value of $OUT.  This means	that you can
       write the template above	like this:

	   Here	is a list of the things	I have got for you since 1907:
	   { foreach $i	(@items) {
	       $OUT .= "  * $i\n";
	     }
	   }

       $OUT is reinitialized to	the empty string at the	start of each program
       fragment.  It is	private	to "Text::Template", so	you can't use a
       variable	named $OUT in your template without invoking the special
       behavior.

   General Remarks
       All "Text::Template" functions return "undef" on	failure, and set the
       variable	$Text::Template::ERROR to contain an explanation of what went
       wrong.  For example, if you try to create a template from a file	that
       does not	exist, $Text::Template::ERROR will contain something like:

	   Couldn't open file xyz.tmpl:	No such	file or	directory

   "new"
	   $template = Text::Template->new( TYPE => ..., SOURCE	=> ... );

       This creates and	returns	a new template object.	"new" returns "undef"
       and sets	$Text::Template::ERROR if it can't create the template object.
       "SOURCE"	says where the template	source code will come from.  "TYPE"
       says what kind of object	the source is.

       The most	common type of source is a file:

	   Text::Template->new(	TYPE =>	'FILE',	SOURCE => $filename );

       This reads the template from the	specified file.	 The filename is
       opened with the Perl "open" command, so it can be a pipe	or anything
       else that makes sense with "open".

       The "TYPE" can also be "STRING",	in which case the "SOURCE" should be a
       string:

	   Text::Template->new(	TYPE =>	'STRING',
				SOURCE => "This	is the actual template!" );

       The "TYPE" can be "ARRAY", in which case	the source should be a
       reference to an array of	strings.  The concatenation of these strings
       is the template:

	   Text::Template->new(	TYPE =>	'ARRAY',
				    SOURCE => [	"This is ", "the actual",
						" template!",
					      ]
			      );

       The "TYPE" can be FILEHANDLE, in	which case the source should be	an
       open filehandle (such as	you got	from the "FileHandle" or "IO::*"
       packages, or a glob, or a reference to a	glob).	In this	case
       "Text::Template"	will read the text from	the filehandle up to end-of-
       file, and that text is the template:

	   # Read template source code from STDIN:
	   Text::Template->new ( TYPE => 'FILEHANDLE',
				 SOURCE	=> \*STDIN  );

       If you omit the "TYPE" attribute, it's taken to be "FILE".  "SOURCE" is
       required.  If you omit it, the program will abort.

       The words "TYPE"	and "SOURCE" can be spelled any	of the following ways:

	   TYPE	    SOURCE
	   Type	    Source
	   type	    source
	   -TYPE    -SOURCE
	   -Type    -Source
	   -type    -source

       Pick a style you	like and stick with it.

       "DELIMITERS"
	   You may also	add a "DELIMITERS" option.  If this option is present,
	   its value should be a reference to an array of two strings.	The
	   first string	is the string that signals the beginning of each
	   program fragment, and the second string is the string that signals
	   the end of each program fragment.  See "Alternative Delimiters",
	   below.

       "ENCODING"
	   You may also	add a "ENCODING" option.  If this option is present,
	   and the "SOURCE" is a "FILE", then the data will be decoded from
	   the given encoding using the	Encode module.	You can	use any
	   encoding that Encode	recognizes.  E.g.:

	       Text::Template->new(
		   TYPE	    => 'FILE',
		   ENCODING => 'UTF-8',
		   SOURCE   => 'xyz.tmpl');

       "UNTAINT"
	   If your program is running in taint mode, you may have problems if
	   your	templates are stored in	files.	Data read from files is
	   considered 'untrustworthy', and taint mode will not allow you to
	   evaluate the	Perl code in the file.	(It is afraid that a malicious
	   person might	have tampered with the file.)

	   In some environments, however, local	files are trustworthy.	You
	   can tell "Text::Template" that a certain file is trustworthy	by
	   supplying "UNTAINT => 1" in the call	to "new".  This	will tell
	   "Text::Template" to disable taint checks on template	code that has
	   come	from a file, as	long as	the filename itself is considered
	   trustworthy.	 It will also disable taint checks on template code
	   that	comes from a filehandle.  When used with "TYPE => 'string'" or
	   "TYPE => 'array'", it has no	effect.

	   See perlsec for more	complete information about tainting.

	   Thanks to Steve Palincsar, Gerard Vreeswijk,	and Dr.	Christoph
	   Baehr for help with this feature.

       "PREPEND"
	   This	option is passed along to the "fill_in"	call unless it is
	   overridden in the arguments to "fill_in".  See ""PREPEND" feature
	   and using "strict" in templates" below.

       "BROKEN"
	   This	option is passed along to the "fill_in"	call unless it is
	   overridden in the arguments to "fill_in".  See "BROKEN" below.

   "compile"
	   $template->compile()

       Loads all the template text from	the template's source, parses and
       compiles	it.  If	successful, returns true; otherwise returns false and
       sets $Text::Template::ERROR.  If	the template is	already	compiled, it
       returns true and	does nothing.

       You don't usually need to invoke	this function, because "fill_in" (see
       below) compiles the template if it isn't	compiled already.

       If there	is an argument to this function, it must be a reference	to an
       array containing	alternative delimiter strings.	See "Alternative
       Delimiters", below.

   "fill_in"
	   $template->fill_in(OPTIONS);

       Fills in	a template.  Returns the resulting text	if successful.
       Otherwise, returns "undef"  and sets $Text::Template::ERROR.

       The OPTIONS are a hash, or a list of key-value pairs.  You can write
       the key names in	any of the six usual styles as above; this means that
       where this manual says "PACKAGE"	(for example) you can actually use any
       of

	   PACKAGE Package package -PACKAGE -Package -package

       Pick a style you	like and stick with it.	 The all-lowercase versions
       may yield spurious warnings about

	   Ambiguous use of package => resolved	to "package"

       so you might like to avoid them and use the capitalized versions.

       At present, there are eight legal options:  "PACKAGE", "BROKEN",
       "BROKEN_ARG", "FILENAME", "SAFE", "HASH", "OUTPUT", and "DELIMITERS".

       "PACKAGE"
	   "PACKAGE" specifies the name	of a package in	which the program
	   fragments should be evaluated.  The default is to use the package
	   from	which "fill_in"	was called.  For example, consider this
	   template:

	       The value of the	variable x is {$x}.

	   If you use "$template->fill_in(PACKAGE => 'R')" , then the $x in
	   the template	is actually replaced with the value of $R::x.  If you
	   omit	the "PACKAGE" option, $x will be replaced with the value of
	   the $x variable in the package that actually	called "fill_in".

	   You should almost always use	"PACKAGE".  If you don't, and your
	   template makes changes to variables,	those changes will be
	   propagated back into	the main program.  Evaluating the template in
	   a private package helps prevent this.  The template can still
	   modify variables in your program if it wants	to, but	it will	have
	   to do so explicitly.	 See the section at the	end on `Security'.

	   Here's an example of	using "PACKAGE":

	       Your Royal Highness,

	       Enclosed	please find a list of things I have gotten
	       for you since 1907:

	       { foreach $item (@items)	{
		       $item_no++;
		   $OUT	.= " $item_no. \u$item\n";
		 }
	       }

	       Signed,
	       Lord High Chamberlain

	   We want to pass in an array which will be assigned to the array
	   @items.  Here's how to do that:

	       @items =	('ivory', 'apes', 'peacocks', );
	       $template->fill_in();

	   This	is not very safe.  The reason this isn't as safe is that if
	   you had a variable named $item_no in	scope in your program at the
	   point you called "fill_in", its value would be clobbered by the act
	   of filling out the template.	 The problem is	the same as if you had
	   written a subroutine	that used those	variables in the same way that
	   the template	does.  ($OUT is	special	in templates and is always
	   safe.)

	   One solution	to this	is to make the $item_no	variable private to
	   the template	by declaring it	with "my".  If the template does this,
	   you are safe.

	   But if you use the "PACKAGE"	option,	you will probably be safe even
	   if the template does	not declare its	variables with "my":

	       @Q::items = ('ivory', 'apes', 'peacocks', );
	       $template->fill_in(PACKAGE => 'Q');

	   In this case	the template will clobber the variable $Q::item_no,
	   which is not	related	to the one your	program	was using.

	   Templates cannot affect variables in	the main program that are
	   declared with "my", unless you give the template references to
	   those variables.

       "HASH"
	   You may not want to put the template	variables into a package.
	   Packages can	be hard	to manage:  You	can't copy them, for example.
	   "HASH" provides an alternative.

	   The value for "HASH"	should be a reference to a hash	that maps
	   variable names to values.  For example,

	       $template->fill_in(
		   HASH	=> {
		       recipient => "The King",
		       items	 => ['gold', 'frankincense', 'myrrh'],
		       object	 => \$self,
		   }
	       );

	   will	fill out the template and use "The King" as the	value of
	   $recipient and the list of items as the value of @items.  Note that
	   we pass an array reference, but inside the template it appears as
	   an array.  In general, anything other than a	simple string or
	   number should be passed by reference.

	   We also want	to pass	an object, which is in $self; note that	we
	   pass	a reference to the object, "\$self" instead.  Since we've
	   passed a reference to a scalar, inside the template the object
	   appears as $object.

	   The full details of how it works are	a little involved, so you
	   might want to skip to the next section.

	   Suppose the key in the hash is key and the value is value.

	   o   If the value is "undef",	then any variables named $key, @key,
	       %key, etc., are undefined.

	   o   If the value is a string	or a number, then $key is set to that
	       value in	the template.

	   o   For anything else, you must pass	a reference.

	       If the value is a reference to an array,	then @key is set to
	       that array.  If the value is a reference	to a hash, then	%key
	       is set to that hash.  Similarly if value	is any other kind of
	       reference.  This	means that

		   var => "foo"

	       and

		   var => \"foo"

	       have almost exactly the same effect.  (The difference is	that
	       in the former case, the value is	copied,	and in the latter case
	       it is aliased.)

	   o   In particular, if you want the template to get an object	or any
	       kind, you must pass a reference to it:

		   $template->fill_in(HASH => {	database_handle	=> \$dbh, ... });

	       If you do this, the template will have a	variable
	       $database_handle	which is the database handle object.  If you
	       leave out the "\", the template will have a hash
	       %database_handle, which exposes the internal structure of the
	       database	handle object; you don't want that.

	   Normally, the way this works	is by allocating a private package,
	   loading all the variables into the package, and then	filling	out
	   the template	as if you had specified	that package.  A new package
	   is allocated	each time.  However, if	you also use the "PACKAGE"
	   option, "Text::Template" loads the variables	into the package you
	   specified, and they stay there after	the call returns.  Subsequent
	   calls to "fill_in" that use the same	package	will pick up the
	   values you loaded in.

	   If the argument of "HASH" is	a reference to an array	instead	of a
	   reference to	a hash,	then the array should contain a	list of	hashes
	   whose contents are loaded into the template package one after the
	   other.  You can use this feature if you want	to combine several
	   sets	of variables.  For example, one	set of variables might be the
	   defaults for	a fill-in form,	and the	second set might be the	user
	   inputs, which override the defaults when they are present:

	       $template->fill_in(HASH => [\%defaults, \%user_input]);

	   You can also	use this to set	two variables with the same name:

	       $template->fill_in(
		   HASH	=> [
		       { v => "The King" },
		       { v => [1,2,3] }
		   ]
	       );

	   This	sets $v	to "The	King" and @v to	"(1,2,3)".

       "BROKEN"
	   If any of the program fragments fails to compile or aborts for any
	   reason, and you have	set the	"BROKEN" option	to a function
	   reference, "Text::Template" will invoke the function.  This
	   function is called the "BROKEN" function.  The "BROKEN" function
	   will	tell "Text::Template" what to do next.

	   If the "BROKEN" function returns "undef", "Text::Template" will
	   immediately abort processing	the template and return	the text that
	   it has accumulated so far.  If your function	does this, it should
	   set a flag that you can examine after "fill_in" returns so that you
	   can tell whether there was a	premature return or not.

	   If the "BROKEN" function returns any	other value, that value	will
	   be interpolated into	the template as	if that	value had been the
	   return value	of the program fragment	to begin with.	For example,
	   if the "BROKEN" function returns an error string, the error string
	   will	be interpolated	into the output	of the template	in place of
	   the program fragment	that cased the error.

	   If you don't	specify	a "BROKEN" function, "Text::Template" supplies
	   a default one that returns something	like

	       Program fragment	delivered error	``Illegal division by 0	at
	       template	line 37''

	   (Note that the format of this message has changed slightly since
	   version 1.31.)  The return value of the "BROKEN" function is
	   interpolated	into the template at the place the error occurred, so
	   that	this template:

	       (3+4)*5 = { 3+4)*5 }

	   yields this result:

	       (3+4)*5 = Program fragment delivered error ``syntax error at template line 1''

	   If you specify a value for the "BROKEN" attribute, it should	be a
	   reference to	a function that	"fill_in" can call instead of the
	   default function.

	   "fill_in" will pass a hash to the "broken" function.	 The hash will
	   have	at least these three members:

	   "text"
	       The source code of the program fragment that failed

	   "error"
	       The text	of the error message ($@) generated by eval.

	       The text	has been modified to omit the trailing newline and to
	       include the name	of the template	file (if there was one).  The
	       line number counts from the beginning of	the template, not from
	       the beginning of	the failed program fragment.

	   "lineno"
	       The line	number of the template at which	the program fragment
	       began.

	   There may also be an	"arg" member.  See "BROKEN_ARG", below

       "BROKEN_ARG"
	   If you supply the "BROKEN_ARG" option to "fill_in", the value of
	   the option is passed	to the "BROKEN"	function whenever it is
	   called.  The	default	"BROKEN" function ignores the "BROKEN_ARG",
	   but you can write a custom "BROKEN" function	that uses the
	   "BROKEN_ARG"	to get more information	about what went	wrong.

	   The "BROKEN"	function could also use	the "BROKEN_ARG" as a
	   reference to	store an error message or some other information that
	   it wants to communicate back	to the caller.	For example:

	       $error =	'';

	       sub my_broken {
		  my %args = @_;
		  my $err_ref =	$args{arg};
		  ...
		  $$err_ref = "Some error message";
		  return undef;
	       }

	       $template->fill_in(
		   BROKEN     => \&my_broken,
		   BROKEN_ARG => \$error
	       );

	       if ($error) {
		 die "It didn't	work: $error";
	       }

	   If one of the program fragments in the template fails, it will call
	   the "BROKEN"	function, "my_broken", and pass	it the "BROKEN_ARG",
	   which is a reference	to $error.  "my_broken"	can store an error
	   message into	$error this way.  Then the function that called
	   "fill_in" can see if	"my_broken" has	left an	error message for it
	   to find, and	proceed	accordingly.

       "FILENAME"
	   If you give "fill_in" a "FILENAME" option, then this	is the file
	   name	that you loaded	the template source from.  This	only affects
	   the error message that is given for template	errors.	 If you	loaded
	   the template	from "foo.txt" for example, and	pass "foo.txt" as the
	   "FILENAME" parameter, errors	will look like "... at foo.txt line N"
	   rather than "... at template	line N".

	   Note	that this does NOT have	anything to do with loading a template
	   from	the given filename.  See "fill_in_file()" for that.

	   For example:

	    my $template = Text::Template->new(
		TYPE   => 'string',
		SOURCE => 'The value is	{1/0}');

	    $template->fill_in(FILENAME	=> 'foo.txt') or die $Text::Template::ERROR;

	   will	die with an error that contains

	    Illegal division by	zero at	at foo.txt line	1

       "SAFE"
	   If you give "fill_in" a "SAFE" option, its value should be a	safe
	   compartment object from the "Safe" package.	All evaluation of
	   program fragments will be performed in this compartment.  See Safe
	   for full details about such compartments and	how to restrict	the
	   operations that can be performed in them.

	   If you use the "PACKAGE" option with	"SAFE",	the package you
	   specify will	be placed into the safe	compartment and	evaluation
	   will	take place in that package as usual.

	   If not, "SAFE" operation is a little	different from the default.
	   Usually, if you don't specify a package, evaluation of program
	   fragments occurs in the package from	which the template was
	   invoked.  But in "SAFE" mode	the evaluation occurs inside the safe
	   compartment and cannot affect the calling package.  Normally, if
	   you use "HASH" without "PACKAGE", the hash variables	are imported
	   into	a private, one-use-only	package.  But if you use "HASH"	and
	   "SAFE" together without "PACKAGE", the hash variables will just be
	   loaded into the root	namespace of the "Safe"	compartment.

       "OUTPUT"
	   If your template is going to	generate a lot of text that you	are
	   just	going to print out again anyway,  you can save memory by
	   having "Text::Template" print out the text as it is generated
	   instead of making it	into a big string and returning	the string.
	   If you supply the "OUTPUT" option to	"fill_in", the value should be
	   a filehandle.  The generated	text will be printed to	this
	   filehandle as it is constructed.  For example:

	       $template->fill_in(OUTPUT => \*STDOUT, ...);

	   fills in the	$template as usual, but	the results are	immediately
	   printed to STDOUT.  This may	result in the output appearing more
	   quickly than	it would have otherwise.

	   If you use "OUTPUT",	the return value from "fill_in"	is still true
	   on success and false	on failure, but	the complete text is not
	   returned to the caller.

       "PREPEND"
	   You can have	some Perl code prepended automatically to the
	   beginning of	every program fragment.	 See ""PREPEND"	feature	and
	   using "strict" in templates"	below.

       "DELIMITERS"
	   If this option is present, its value	should be a reference to a
	   list	of two strings.	 The first string is the string	that signals
	   the beginning of each program fragment, and the second string is
	   the string that signals the end of each program fragment.  See
	   "Alternative	Delimiters", below.

	   If you specify "DELIMITERS" in the call to "fill_in", they override
	   any delimiters you set when you created the template	object with
	   "new".

Convenience Functions
   "fill_this_in"
       The basic way to	fill in	a template is to create	a template object and
       then call "fill_in" on it.   This is useful if you want to fill in the
       same template more than once.

       In some programs, this can be cumbersome.  "fill_this_in" accepts a
       string, which contains the template, and	a list of options, which are
       passed to "fill_in" as above.  It constructs the	template object	for
       you, fills it in	as specified, and returns the results.	It returns
       "undef" and sets	$Text::Template::ERROR if it couldn't generate any
       results.

       An example:

	   $Q::name = 'Donald';
	   $Q::amount =	141.61;
	   $Q::part = 'hyoid bone';

	   $text = Text::Template->fill_this_in( <<'EOM', PACKAGE => Q);
	   Dear	{$name},
	   You owe me \\${sprintf('%.2f', $amount)}.
	   Pay or I will break your {$part}.
	       Love,
	       Grand Vizopteryx	of Irkutsk.
	   EOM

       Notice how we included the template in-line in the program by using a
       `here document' with the	"<<" notation.

       "fill_this_in" is a deprecated feature.	It is only here	for backwards
       compatibility, and may be removed in some far-future version in
       "Text::Template".  You should use "fill_in_string" instead.  It is
       described in the	next section.

   "fill_in_string"
       It is stupid that "fill_this_in"	is a class method.  It should have
       been just an imported function, so that you could omit the
       "Text::Template->" in the example above.	 But I made the	mistake	four
       years ago and it	is too late to change it.

       "fill_in_string"	is exactly like	"fill_this_in" except that it is not a
       method and you can omit the "Text::Template->" and just say

	   print fill_in_string(<<'EOM', ...);
	   Dear	{$name},
	     ...
	   EOM

       To use "fill_in_string",	you need to say

	   use Text::Template 'fill_in_string';

       at the top of your program.   You should	probably use "fill_in_string"
       instead of "fill_this_in".

   "fill_in_file"
       If you import "fill_in_file", you can say

	   $text = fill_in_file(filename, ...);

       The "..." are passed to "fill_in" as above.  The	filename is the	name
       of the file that	contains the template you want to fill in.  It returns
       the result text.	or "undef", as usual.

       If you are going	to fill	in the same file more than once	in the same
       program you should use the longer "new" / "fill_in" sequence instead.
       It will be a lot	faster because it only has to read and parse the file
       once.

   Including files into	templates
       People always ask for this.  ``Why don't	you have an include
       function?'' they	want to	know.  The short answer	is this	is Perl, and
       Perl already has	an include function.  If you want it, you can just put

	   {qx{cat filename}}

       into your template.  VoilA .

       If you don't want to use	"cat", you can write a little four-line
       function	that opens a file and dumps out	its contents, and call it from
       the template.  I	wrote one for you.  In the template, you can say

	   {Text::Template::_load_text(filename)}

       If that is too verbose, here is a trick.	 Suppose the template package
       that you	are going to be	mentioning in the "fill_in" call is package
       "Q".  Then in the main program, write

	   *Q::include = \&Text::Template::_load_text;

       This imports the	"_load_text" function into package "Q" with the	name
       "include".  From	then on, any template that you fill in with package
       "Q" can say

	   {include(filename)}

       to insert the text from the named file at that point.  If you are using
       the "HASH" option instead, just put "include =>
       \&Text::Template::_load_text" into the hash instead of importing	it
       explicitly.

       Suppose you don't want to insert	a plain	text file, but rather you want
       to include one template within another?	Just use "fill_in_file"	in the
       template	itself:

	   {Text::Template::fill_in_file(filename)}

       You can do the same importing trick if this is too much to type.

Miscellaneous
   "my"	variables
       People are frequently surprised when this doesn't work:

	   my $recipient = 'The	King';
	   my $text = fill_in_file('formletter.tmpl');

       The text	"The King" doesn't get into the	form letter.  Why not?
       Because $recipient is a "my" variable, and the whole point of "my"
       variables is that they're private and inaccessible except in the	scope
       in which	they're	declared.  The template	is not part of that scope, so
       the template can't see $recipient.

       If that's not the behavior you want, don't use "my".  "my" means	a
       private variable, and in	this case you don't want the variable to be
       private.	 Put the variables into	package	variables in some other
       package,	and use	the "PACKAGE" option to	"fill_in":

	   $Q::recipient = $recipient;
	   my $text = fill_in_file('formletter.tmpl', PACKAGE => 'Q');

       or pass the names and values in a hash with the "HASH" option:

	   my $text = fill_in_file('formletter.tmpl', HASH => {	recipient => $recipient	});

   Security Matters
       All variables are evaluated in the package you specify with the
       "PACKAGE" option	of "fill_in".  if you use this option, and if your
       templates don't do anything egregiously stupid, you won't have to worry
       that evaluation of the little programs will creep out into the rest of
       your program and	wreck something.

       Nevertheless, there's really no way (except with	"Safe")	to protect
       against a template that says

	   { $Important::Secret::Security::Enable = 0;
	     # Disable security	checks in this program
	   }

       or

	   { $/	= "ho ho ho";	# Sabotage future uses of <FH>.
	     # $/ is always a global variable
	   }

       or even

	   { system("rm	-rf /")	}

       so don't	go filling in templates	unless you're sure you know what's in
       them.  If you're	worried, or you	can't trust the	person who wrote the
       template, use the "SAFE"	option.

       A final warning:	program	fragments run a	small risk of accidentally
       clobbering local	variables in the "fill_in" function itself.  These
       variables all have names	that begin with	$fi_, so if you	stay away from
       those names you'll be safe.  (Of	course,	if you're a real wizard	you
       can tamper with them deliberately for exciting effects; this is
       actually	how $OUT works.)  I can	fix this, but it will make the package
       slower to do it,	so I would prefer not to.  If you are worried about
       this, send me mail and I	will show you what to do about it.

   Alternative Delimiters
       Lorenzo Valdettaro pointed out that if you are using "Text::Template"
       to generate TeX output, the choice of braces as the program fragment
       delimiters makes	you suffer suffer suffer.  Starting in version 1.20,
       you can change the choice of delimiters to something other than curly
       braces.

       In either the "new()" call or the "fill_in()" call, you can specify an
       alternative set of delimiters with the "DELIMITERS" option.  For
       example,	if you would like code fragments to be delimited by "[@--" and
       "--@]" instead of "{" and "}", use

	   ... DELIMITERS => [ '[@--', '--@]' ], ...

       Note that these delimiters are literal strings, not regexes.  (I	tried
       for regexes, but	it complicates the lexical analysis too	much.)	Note
       also that "DELIMITERS" disables the special meaning of the backslash,
       so if you want to include the delimiters	in the literal text of your
       template	file, you are out of luck---it is up to	you to choose
       delimiters that do not conflict with what you are doing.	 The delimiter
       strings may still appear	inside of program fragments as long as they
       nest properly.  This means that if for some reason you absolutely must
       have a program fragment that mentions one of the	delimiters, like this:

	   [@--
	       print "Oh no, a delimiter: --@]\n"
	   --@]

       you may be able to make it work by doing	this instead:

	   [@--
	       # Fake matching delimiter in a comment: [@--
	       print "Oh no, a delimiter: --@]\n"
	   --@]

       It may be safer to choose delimiters that begin with a newline
       character.

       Because the parsing of templates	is simplified by the absence of
       backslash escapes, using	alternative "DELIMITERS" may speed up the
       parsing process by 20-25%.  This	shows that my original choice of "{"
       and "}" was very	bad.

   "PREPEND" feature and using "strict"	in templates
       Suppose you would like to use "strict" in your templates	to detect
       undeclared variables and	the like.  But each code fragment is a
       separate	lexical	scope, so you have to turn on "strict" at the top of
       each and	every code fragment:

	   { use strict;
	     use vars '$foo';
	     $foo = 14;
	     ...
	   }

	   ...

	   { # we forgot to put	`use strict' here
	     my	$result	= $boo + 12;	# $boo is misspelled and should	be $foo
	     # No error	is raised on `$boo'
	   }

       Because we didn't put "use strict" at the top of	the second fragment,
       it was only active in the first fragment, and we	didn't get any
       "strict"	checking in the	second fragment.  Then we misspelled $foo and
       the error wasn't	caught.

       "Text::Template"	version	1.22 and higher	has a new feature to make this
       easier.	You can	specify	that any text at all be	automatically added to
       the beginning of	each program fragment.

       When you	make a call to "fill_in", you can specify a

	   PREPEND => 'some perl statements here'

       option; the statements will be prepended	to each	program	fragment for
       that one	call only.  Suppose that the "fill_in" call included a

	   PREPEND => 'use strict;'

       option, and that	the template looked like this:

	   { use vars '$foo';
	     $foo = 14;
	     ...
	   }

	   ...

	   { my	$result	= $boo + 12;	# $boo is misspelled and should	be $foo
	     ...
	   }

       The code	in the second fragment would fail, because $boo	has not	been
       declared.  "use strict" was implied, even though	you did	not write it
       explicitly, because the "PREPEND" option	added it for you
       automatically.

       There are three other ways to do	this.  At the time you create the
       template	object with "new", you can also	supply a "PREPEND" option, in
       which case the statements will be prepended each	time you fill in that
       template.  If the "fill_in" call	has its	own "PREPEND" option, this
       overrides the one specified at the time you created the template.
       Finally,	you can	make the class method call

	   Text::Template->always_prepend('perl	statements');

       If you do this, then call calls to "fill_in" for	any template will
       attach the perl statements to the beginning of each program fragment,
       except where overridden by "PREPEND" options to "new" or	"fill_in".

       An alternative to adding	"use strict;" to the PREPEND option, you can
       pass STRICT => 1	to fill_in when	also passing the HASH option.

       Suppose that the	"fill_in" call included	both

	   HASH	  => {$foo => ''} and
	   STRICT => 1

       options,	and that the template looked like this:

	   {
	     $foo = 14;
	     ...
	   }

	   ...

	   { my	$result	= $boo + 12;	# $boo is misspelled and should	be $foo
	     ...
	   }

       The code	in the second fragment would fail, because $boo	has not	been
       declared. "use strict" was implied, even	though you did not write it
       explicitly, because the "STRICT"	option added it	for you	automatically.
       Any variable referenced in the template that is not in the "HASH"
       option will be an error.

   Prepending in Derived Classes
       This section is technical, and you should skip it on the	first few
       readings.

       Normally	there are three	places that prepended text could come from.
       It could	come from the "PREPEND"	option in the "fill_in"	call, from the
       "PREPEND" option	in the "new" call that created the template object, or
       from the	argument of the	"always_prepend" call.	"Text::Template" looks
       for these three things in order and takes the first one that it finds.

       In a subclass of	"Text::Template", this last possibility	is ambiguous.
       Suppose "S" is a	subclass of "Text::Template".  Should

	   Text::Template->always_prepend(...);

       affect objects in class "Derived"?  The answer is that you can have it
       either way.

       The "always_prepend" value for "Text::Template" is normally stored in
       a hash variable named %GLOBAL_PREPEND under the key "Text::Template".
       When "Text::Template" looks to see what text to prepend,	it first looks
       in the template object itself, and if not, it looks in
       $GLOBAL_PREPEND{class} where class is the class to which	the template
       object belongs.	If it doesn't find any value, it looks in
       $GLOBAL_PREPEND{'Text::Template'}.  This	means that objects in class
       "Derived" will be affected by

	   Text::Template->always_prepend(...);

       unless there is also a call to

	   Derived->always_prepend(...);

       So when you're designing	your derived class, you	can arrange to have
       your objects ignore "Text::Template::always_prepend" calls by simply
       putting "Derived->always_prepend('')" at	the top	of your	module.

       Of course, there	is also	a final	escape hatch: Templates	support	a
       "prepend_text" that is used to look up the appropriate text to be
       prepended at "fill_in" time.  Your derived class	can override this
       method to get an	arbitrary effect.

   JavaScript
       Jennifer	D. St Clair asks:

	   > Most of my	pages contain JavaScript and Stylesheets.
	   > How do I change the template identifier?

       Jennifer	is worried about the braces in the JavaScript being taken as
       the delimiters of the Perl program fragments.  Of course, disaster will
       ensue when perl tries to	evaluate these as if they were Perl programs.
       The best	choice is to find some unambiguous delimiter strings that you
       can use in your template	instead	of curly braces, and then use the
       "DELIMITERS" option.  However, if you can't do this for some reason,
       there are  two easy workarounds:

       1. You can put "\" in front of "{", "}",	or "\" to remove its special
       meaning.	 So, for example, instead of

	   if (br== "n3") {
	       // etc.
	   }

       you can put

	   if (br== "n3") \{
	       // etc.
	   \}

       and it'll come out of the template engine the way you want.

       But here	is another method that is probably better.  To see how it
       works, first consider what happens if you put this into a template:

	   { 'foo' }

       Since it's in braces, it	gets evaluated,	and obviously, this is going
       to turn into

	   foo

       So now here's the trick:	In Perl, "q{...}" is the same as '...'.	 So if
       we wrote

	   {q{foo}}

       it would	turn into

	   foo

       So for your JavaScript, just write

	   {q{if (br== "n3") {
	      // etc.
	      }}
	   }

       and it'll come out as

	   if (br== "n3") {
	       // etc.
	   }

       which is	what you want.

       head2 Shut Up!

       People sometimes	try to put an initialization section at	the top	of
       their templates,	like this:

	   { ...
	       $var = 17;
	   }

       Then they complain because there	is a 17	at the top of the output that
       they didn't want	to have	there.

       Remember	that a program fragment	is replaced with its own return	value,
       and that	in Perl	the return value of a code block is the	value of the
       last expression that was	evaluated, which in this case is 17.  If it
       didn't do that, you wouldn't be able to write "{$recipient}" and	have
       the recipient filled in.

       To prevent the 17 from appearing	in the output is very simple:

	   { ...
	       $var = 17;
	       '';
	   }

       Now the last expression evaluated yields	the empty string, which	is
       invisible.  If you don't	like the way this looks, use

	   { ...
	       $var = 17;
	       ($SILENTLY);
	   }

       instead.	 Presumably, $SILENTLY has no value, so	nothing	will be
       interpolated.  This is what is known as a `trick'.

   Compatibility
       Every effort has	been made to make this module compatible with older
       versions.  The only known exceptions follow:

       The output format of the	default	"BROKEN" subroutine has	changed	twice,
       most recently between versions 1.31 and 1.40.

       Starting	in version 1.10, the $OUT variable is arrogated	for a special
       meaning.	 If you	had templates before version 1.10 that happened	to use
       a variable named	$OUT, you will have to change them to use some other
       variable	or all sorts of	strangeness will result.

       Between versions	0.1b and 1.00 the behavior of the \ metacharacter
       changed.	 In 0.1b, \\ was special everywhere, and the template
       processor always	replaced it with a single backslash before passing the
       code to Perl for	evaluation.  The rule now is more complicated but
       probably	more convenient.  See the section on backslash processing,
       below, for a full discussion.

   Backslash Processing
       In "Text::Template" beta	versions, the backslash	was special whenever
       it appeared before a brace or another backslash.	 That meant that while
       "{"\n"}"	did indeed generate a newline, "{"\\"}"	did not	generate a
       backslash, because the code passed to Perl for evaluation was "\" which
       is a syntax error.  If you wanted a backslash, you would	have had to
       write "{"\\\\"}".

       In "Text::Template" versions 1.00 through 1.10, there was a bug:
       Backslash was special everywhere.  In these versions, "{"\n"}"
       generated the letter "n".

       The bug has been	corrected in version 1.11, but I did not go back to
       exactly the old rule, because I did not like the	idea of	having to
       write "{"\\\\"}"	to get one backslash.  The rule	is now more
       complicated to remember,	but probably easier to use.  The rule is now:
       Backslashes are always passed to	Perl unchanged unless they occur as
       part of a sequence like "\\\\\\{" or "\\\\\\}".	In these contexts,
       they are	special; "\\" is replaced with "\", and	"\{" and "\}" signal a
       literal brace.

       Examples:

	   \{ foo \}

       is not evaluated, because the "\" before	the braces signals that	they
       should be taken literally.  The result in the output looks like this:

	   { foo }

       This is a syntax	error:

	   { "foo}" }

       because "Text::Template"	thinks that the	code ends at the first "}",
       and then	gets upset when	it sees	the second one.	 To make this work
       correctly, use

	   { "foo\}" }

       This passes "foo}" to Perl for evaluation.  Note	there's	no "\" in the
       evaluated code.	If you really want a "\" in the	evaluated code,	use

	   { "foo\\\}" }

       This passes "foo\}" to Perl for evaluation.

       Starting	with "Text::Template" version 1.20, backslash processing is
       disabled	if you use the "DELIMITERS" option to specify alternative
       delimiter strings.

   A short note	about $Text::Template::ERROR
       In the past some	people have fretted about `violating the package
       boundary' by examining a	variable inside	the "Text::Template" package.
       Don't feel this way.  $Text::Template::ERROR is part of the published,
       official	interface to this package.  It is perfectly OK to inspect this
       variable.  The interface	is not going to	change.

       If it really, really bothers you, you can import	a function called
       "TTerror" that returns the current value	of the $ERROR variable.	 So
       you can say:

	   use Text::Template 'TTerror';

	   my $template	= Text::Template->new(SOURCE =>	$filename);
	   unless ($template) {
	       my $err = TTerror;
	       die "Couldn't make template: $err; aborting";
	   }

       I don't see what	benefit	this has over just doing this:

	   use Text::Template;

	   my $template	= Text::Template->new(SOURCE =>	$filename)
	       or die "Couldn't	make template: $Text::Template::ERROR; aborting";

       But if it makes you happy to do it that way, go ahead.

   Sticky Widgets in Template Files
       The "CGI" module	provides functions for `sticky widgets', which are
       form input controls that	retain their values from one page to the next.
       Sometimes people	want to	know how to include these widgets into their
       template	output.

       It's totally straightforward.  Just call	the "CGI" functions from
       inside the template:

	   { $q->checkbox_group(NAME	  => 'toppings',
				LINEBREAK => true,
				COLUMNS	  => 3,
				VALUES	  => \@toppings,
			       );
	   }

   Automatic preprocessing of program fragments
       It may be useful	to preprocess the program fragments before they	are
       evaluated.  See "Text::Template::Preprocess" for	more details.

   Automatic postprocessing of template	hunks
       It may be useful	to process hunks of output before they are appended to
       the result text.	 For this, subclass and	replace	the
       "append_text_to_result" method.	It is passed a list of pairs with
       these entries:

	 handle	- a filehandle to which	to print the desired output
	 out	- a ref	to a string to which to	append,	to use if handle is not	given
	 text	- the text that	will be	appended
	 type	- where	the text came from: TEXT for literal text, PROG	for code

HISTORY
       Originally written by Mark Jason	Dominus, Plover	Systems	(versions 0.01
       - 1.46)

       Maintainership transferred to Michael Schout <mschout@cpan.org> in
       version 1.47

THANKS
       Many thanks to the following people for offering	support,
       encouragement, advice, bug reports, and all the other good stuff.

       o   Andrew G Wood

       o   Andy	Wardley

       o   AntA^3nio AragALo

       o   Archie Warnock

       o   Bek Oberin

       o   Bob Dougherty

       o   Brian C. Shensky

       o   Chris Nandor

       o   Chris Wesley

       o   Chris.Brezil

       o   Daini Xie

       o   Dan Franklin

       o   Daniel LaLiberte

       o   David H. Adler

       o   David Marshall

       o   Dennis Taylor

       o   Donald L. Greer Jr.

       o   Dr. Frank Bucolo

       o   Fred	Steinberg

       o   Gene	Damon

       o   Hans	Persson

       o   Hans	Stoop

       o   Itamar Almeida de Carvalho

       o   James H. Thompson

       o   James Mastros

       o   Jarko Hietaniemi

       o   Jason Moore

       o   Jennifer D. St Clair

       o   Joel	Appelbaum

       o   Joel	Meulenberg

       o   Jonathan Roy

       o   Joseph Cheek

       o   Juan	E. Camacho

       o   Kevin Atteson

       o   Kevin Madsen

       o   Klaus Arnhold

       o   Larry Virden

       o   Lieven Tomme

       o   Lorenzo Valdettaro

       o   Marek Grac

       o   Matt	Womer

       o   Matt	X. Hunter

       o   Michael G Schwern

       o   Michael J. Suzio

       o   Michaely Yeung

       o   Michelangelo	Grigni

       o   Mike	Brodhead

       o   Niklas Skoglund

       o   Randal L. Schwartz

       o   Reuven M. Lerner

       o   Robert M. Ioffe

       o   Ron Pero

       o   San Deng

       o   Sean	Roehnelt

       o   Sergey Myasnikov

       o   Shabbir J. Safdar

       o   Shad	Todd

       o   Steve Palincsar

       o   Tim Bunce

       o   Todd	A. Green

       o   Tom Brown

       o   Tom Henry

       o   Tom Snee

       o   Trip	Lilley

       o   Uwe Schneider

       o   Val Luck

       o   Yannis Livassof

       o   Yonat Sharon

       o   Zac Hansen

       o   gary	at dls.net

       Special thanks to:

       Jonathan	Roy
	 for telling me	how to do the "Safe" support (I	spent two years
	 worrying about	it, and	then Jonathan pointed out that it was
	 trivial.)

       Ranjit Bhatnagar
	 for demanding less verbose fragments like they	have in	ASP, for
	 helping me figure out the Right Thing,	and, especially, for talking
	 me out	of adding any new syntax.  These discussions resulted in the
	 $OUT feature.

   Bugs	and Caveats
       "my" variables in "fill_in" are still susceptible to being clobbered by
       template	evaluation.  They all begin with "fi_",	so avoid those names
       in your templates.

       The line	number information will	be wrong if the	template's lines are
       not terminated by "\n".	You should let me know if this is a problem.
       If you do, I will fix it.

       The $OUT	variable has a special meaning in templates, so	you cannot use
       it as if	it were	a regular variable.

       There are not quite enough tests	in the test suite.

SOURCE
       The development version is on github at
       <https://https://github.com/mschout/perl-text-template> and may be
       cloned from <git://https://github.com/mschout/perl-text-template.git>

BUGS
       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/mschout/perl-text-template/issues>

       When submitting a bug or	request, please	include	a test-file or a patch
       to an existing test-file	that illustrates the bug or desired feature.

AUTHOR
       Michael Schout <mschout@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2013 by Mark Jason Dominus
       <mjd@cpan.org>.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2020-07-03		     Text::Template(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Details | Convenience Functions | Miscellaneous | HISTORY | THANKS | SOURCE | BUGS | AUTHOR | COPYRIGHT AND LICENSE

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

home | help