If any of the program fragments fails to compile or aborts for any
reason, and you have set the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> option to a function reference,
<CODE>Text::Template</CODE> will invoke the function. This function is called
the <EM><A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function</EM>. The <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function will tell
<CODE>Text::Template</CODE> what to do next.
<P>If the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A>, <CODE>Text::Template</CODE> 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 <CODE>fill_in</CODE> returns so that you can
tell whether there was a premature return or not.</P>
<P>If the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> 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
<A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> 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.</P>
<P>If you don't specify a <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function, <CODE>Text::Template</CODE> supplies
a default one that returns something like</P>
<PRE>
Program fragment at line 17 delivered error ``Illegal
division by 0''</PRE>
<P>Since this is interpolated into the template at the place the error
occurred, a template like this one:</P>
<PRE>
(3+4)*5 = { 3+4)*5 }</PRE>
<P>yields this result:</P>
<PRE>
(3+4)*5 = Program fragment at line 1 delivered error
``syntax error''</PRE>
<P>If you specify a value for the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> attribute, it should be a
reference to a function that <CODE>fill_in</CODE> can call instead of the
default function.</P>
<P><CODE>fill_in</CODE> will pass a hash to the <CODE>broken</CODE> function.
The hash will have at least these three members:</P>
If you supply the <A HREF="#item_BROKEN_ARG"><CODE>BROKEN_ARG</CODE></A> option to <CODE>fill_in</CODE>, the value of the
option is passed to the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function whenever it is called. The
default <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function ignores the <A HREF="#item_BROKEN_ARG"><CODE>BROKEN_ARG</CODE></A>, but you can
write a custom <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function that uses the <A HREF="#item_BROKEN_ARG"><CODE>BROKEN_ARG</CODE></A> to get
more information about what went wrong.
<P>The <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function could also use the <A HREF="#item_BROKEN_ARG"><CODE>BROKEN_ARG</CODE></A> as a reference
to store an error message or some other information that it wants to
communicate back to the caller. For example:</P>
<PRE>
$error = '';</PRE>
<PRE>
sub my_broken {
my %args = @_;
my $err_ref = $args{arg};
...
$$err_ref = "Some error message";
return undef;
}</PRE>
<PRE>
$template->fill_in(BROKEN => \&my_broken,
BROKEN_ARG => \$error,
);</PRE>
<PRE>
if ($error) {
die "It didn't work: $error";
}</PRE>
<P>If one of the program fragments in the template fails, it will call
the <A HREF="#item_BROKEN"><CODE>BROKEN</CODE></A> function, <CODE>my_broken</CODE>, and pass it the <A HREF="#item_BROKEN_ARG"><CODE>BROKEN_ARG</CODE></A>,
which is a reference to <CODE>$error</CODE>. <CODE>my_broken</CODE> can store an error
message into <CODE>$error</CODE> this way. Then the function that called
<CODE>fill_in</CODE> can see if <CODE>my_broken</CODE> has left an error message for it
You can have some Perl code prepended automatically to the beginning
of every program fragment. See <A HREF="#c<prepend> feature and using c<strict> in templates"><A HREF="#item_PREPEND"><CODE>PREPEND</CODE></A> feature and using <CODE>strict</CODE> in templates</A> below.
<P></P>
<DT><STRONG><CODE>DELIMITERS</CODE></STRONG><BR>
<DD>
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
<P>People are frequently surprised when this doesn't work:</P>
<PRE>
my $recipient = 'The King';
my $text = fill_in_file('formletter.tmpl');</PRE>
<P>The text <CODE>The King</CODE> doesn't get into the form letter. Why not?
Because <CODE>$recipient</CODE> is a <A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my</CODE></A> variable, and the whole point of
<A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my</CODE></A> 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 <CODE>$recipient</CODE>.</P>
<P>If that's not the behavior you want, don't use <A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my</CODE></A>. <A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my</CODE></A> 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 <A HREF="#item_PACKAGE"><CODE>PACKAGE</CODE></A> option to <CODE>fill_in</CODE>:</P>
<PRE>
$Q::recipient = $recipient;
my $text = fill_in_file('formletter.tmpl', PACKAGE => 'Q');</PRE>
<P>or pass the names and values in a hash with the <A HREF="#item_HASH"><CODE>HASH</CODE></A> option:</P>
<P>Note that these delimiters are <EM>literal strings</EM>, not regexes. (I
tried for regexes, but it complicates the lexical analysis too much.)
Note also that <A HREF="#item_DELIMITERS"><CODE>DELIMITERS</CODE></A> 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:</P>
<PRE>
[@--
print "Oh no, a delimiter: --@]\n"
--@]</PRE>
<P>you may be able to make it work by doing this instead:</P>
<PRE>
[@--
# Fake matching delimiter in a comment: [@--
print "Oh no, a delimiter: --@]\n"
--@]</PRE>
<P>It may be safer to choose delimiters that begin with a newline
character.</P>
<P>Because the parsing of templates is simplified by the absence of
backslash escapes, using alternative <A HREF="#item_DELIMITERS"><CODE>DELIMITERS</CODE></A> <EM>speeds up</EM> the
parsing process by 20-25%. This shows that my original choice of <CODE>{</CODE>
and <CODE>}</CODE> was very bad. I therefore recommend that you use alternative
delimiters whenever possible.</P>
<P>
<H2><A NAME="prepend feature and using strict in templates"><A HREF="#item_PREPEND"><CODE>PREPEND</CODE></A> feature and using <CODE>strict</CODE> in templates</A></H2>
<P>Suppose you would like to use <CODE>strict</CODE> 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 <CODE>strict</CODE> at the top of
each and every code fragment:</P>
<PRE>
{ use strict;
use vars '$foo';
$foo = 14;
...
}</PRE>
<PRE>
...</PRE>
<PRE>
{ # we forgot to put `use strict' here
my $result = $boo + 12; # $boo is misspelled and should be $foo
# No error is raised on `$boo'
}</PRE>
<P>Because we didn't put <CODE>use strict</CODE> at the top of the second fragment,
it was only active in the first fragment, and we didn't get any
<CODE>strict</CODE> checking in the second fragment. Then we mispelled <CODE>$foo</CODE>
and the error wasn't caught.</P>
<P><CODE>Text::Template</CODE> 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.</P>
<P>When you make a call to <CODE>fill_in</CODE>, you can specify a</P>
<PRE>
PREPEND => 'some perl statements here'</PRE>
<P>option; the statements will be prepended to each program fragment for
that one call only. Suppose that the <CODE>fill_in</CODE> call included a</P>
<PRE>
PREPEND => 'use strict;'</PRE>
<P>option, and that the template looked like this:</P>
<PRE>
{ use vars '$foo';
$foo = 14;
...
}</PRE>
<PRE>
...</PRE>
<PRE>
{ my $result = $boo + 12; # $boo is misspelled and should be $foo
...
}</PRE>
<P>The code in the second fragment would fail, because <CODE>$boo</CODE> has not
been declared. <CODE>use strict</CODE> was implied, even though you did not
write it explicitly, because the <A HREF="#item_PREPEND"><CODE>PREPEND</CODE></A> option added it for you
automatically.</P>
<P>There are two other ways to do this. At the time you create the
template object with <CODE>new</CODE>, you can also supply a <A HREF="#item_PREPEND"><CODE>PREPEND</CODE></A> option,
in which case the statements will be prepended each time you fill in
that template. If the <CODE>fill_in</CODE> call has its own <A HREF="#item_PREPEND"><CODE>PREPEND</CODE></A> option,
this overrides the one specified at the time you created the
template. Finally, you can make the class method call</P>
