4 This is a library for generating form letters, building HTML pages, or
5 filling in templates generally. A `template' is a piece of text that
6 has little Perl programs embedded in it here and there. When you
7 `fill in' a template, you evaluate the little programs and replace
8 them with their values.
10 Here's an example of a template:
12 Dear {$title} {$lastname},
14 It has come to our attention that you are delinquent in your
15 {$monthname[$last_paid_month]} payment. Please remit
16 ${sprintf("%.2f", $amount)} immediately, or your patellae may
17 be needlessly endangered.
21 Mark "{nickname(rand 20)}" Dominus
24 The result of filling in this template is a string, which might look
29 It has come to our attention that you are delinquent in your
30 February payment. Please remit
31 $392.12 immediately, or your patellae may
32 be needlessly endangered.
37 Mark "Vizopteryx" Dominus
39 You can store a template in a file outside your program. People can
40 modify the template without modifying the program. You can separate
41 the formatting details from the main code, and put the formatting
42 parts of the program into the template. That prevents code bloat and
43 encourages functional separation.
45 You can fill in the template in a `Safe' compartment. This means that
46 if you don't trust the person who wrote the code in the template, you
47 won't have to worry that they are tampering with your program when you
50 ----------------------------------------------------------------
52 Text::Template was originally released some time in late 1995 or early
53 1996. After three years of study and investigation, I rewrote it from
54 scratch in January 1999. The new version, 1.0, was much faster,
55 delivered better functionality and was almost 100% backward-compatible
56 with the previous beta versions.
58 I have added a number of useful features and conveniences since the
59 1.0 release, while still retaining backward compatibility. With one
60 merely cosmetic change, the current version of Text::Template passes
61 the test suite that the old beta versions passed.
63 Questions or comments should be addressed to
64 mjd-perl-template+@plover.com. This address goes directly to me, and
65 not to anyone else; it is not a mailing list address.
67 To receive occasional announcements of new versions of T::T, send an
68 empty note to mjd-perl-template-request@plover.com. This mailing list
69 is not for discussion; it is for announcements only. Therefore, there
70 is no address for sending messages to the list.
72 You can get the most recent version of Text::Template, news, comments,
73 and other collateral information from
74 <URL:http://www.plover.com/~mjd/perl/Template/>.
76 ----------------------------------------------------------------
78 What's new in v1.46 since v1.44:
80 Thanks to Rik Signes, there is a new
81 Text::Template->append_text_to_output method, which
82 Text::Template always uses whenever it wants to emit output.
83 You can subclass this to get control over the output, for
84 example for postprocessing.
86 A spurious warning is no longer emitted when the TYPE
87 parameter to ->new is omitted.
89 ----------------------------------------------------------------
90 What's new in v1.44 since v1.43:
92 This is a maintentance release. There are no feature changes.
94 _scrubpkg, which was responsible for eptying out temporary
95 packages after the module had done with them, wasn't always
96 working; the result was memory-leaks in long-running
97 applications. This should be fixed now, and there is a test
98 in the test suite for it.
100 Minor changes to the test suite to prevent spurious errors.
102 Minor documentation changes.
104 ----------------------------------------------------------------
105 What's new in v1.43 since v1.42:
107 The ->new method now fails immediately and sets
108 $Text::Template::ERROR if the file that is named by a filename
109 argument does not exist or cannot be opened for some other
110 reason. Formerly, the constructor would succeed and the
111 ->fill_in call would fail.
113 ----------------------------------------------------------------
115 What's new in v1.42 since v1.41:
117 This is a maintentance release. There are no feature changes.
119 Fixed a bug relating to use of UNTAINT under perl 5.005_03 and
120 possibly other versions.
122 Taint-related tests are now more comprehensive.
123 ----------------------------------------------------------------
125 What's new in v1.41 since v1.40:
127 This is a maintentance release. There are no feature changes.
129 Tests now work correctly on Windows systems and possibly on
130 other non-unix systems.
132 ----------------------------------------------------------------
134 What's new in v1.40 since v1.31:
136 New UNTAINT option tells the module that it is safe to 'eval'
137 code even though it has come from a file or filehandle.
139 Code added to prevent memory leaks when filling many
140 templates. Thanks to Itamar Almeida de Carvalho.
142 Bug fix: $OUT was not correctly initialized when used in
143 conjunction with SAFE.
145 You may now use a glob ref when passing a filehandle to the
146 ->new funcion. Formerly, a glob was reuqired.
148 New subclass: Text::Template::Preprocess. Just like
149 Text::Template, but you may supply a PREPROCESS option in the
150 constructor or the fill_in call; this is a function which
151 receives each code fragment prior to evaluation, and which may
152 modify and return the fragment; the modified fragment is what
155 Error messages passed to BROKEN subroutines will now report
156 the correct line number of the template at which the error
159 Illegal division by zero at template line 37.
161 If the template comes from a file, the filename will be
164 Illegal division by zero at catalog.tmpl line 37.
169 The format of the default error message has changed. It used
172 Program fragment at line 30 delivered error ``Illegal division by zero''
176 Program fragment delivered error ``Illegal division by zero at catalog.tmpl line 37''
178 Note that the default message used to report the line number
179 at which the program fragment began; it now reports the line
180 number at which the error actually occurred.
182 ----------------------------------------------------------------
183 What's new in v1.31 since v1.23:
185 Just bug fixes---fill_in_string was failing. Thanks to
186 Donald L. Greer Jr. for the test case.
188 ----------------------------------------------------------------
189 What's new in v1.23 since v1.22:
191 Small bug fix: DELIMITER and other arguments were being
192 ignored in calls to fill_in_file and fill_this_in. (Thanks to
193 Jonathan Roy for reporting this.)
195 ----------------------------------------------------------------
196 What's new in v1.22 since v1.20:
198 You can now specify that certain Perl statements be prepended
199 to the beginning of every program fragment in a template,
200 either per template, or for all templates, or for the duration
201 of only one call to fill_in. This is useful, for example, if
202 you want to enable `strict' checks in your templates but you
203 don't want to manually add `use strict' to the front of every
204 program fragment everywhere.
206 ----------------------------------------------------------------
207 What's new in v1.20 since v1.12:
209 You can now specify that the program fragment delimiters are
210 strings other than { and }. This has three interesting
211 effects: First, it changes the delimiter strings. Second, it
212 disables the special meaning of \, so you have to be really,
213 really sure that the delimiters will not appear in your
214 templates. And third, because of the simplifications
215 introduced by the elimination of \ processing, template
216 parsing is 20-25% faster.
218 See the manual section on `Alternative Delimiters'.
220 Fixed bug having to do with undefined values in HASH options.
221 In particular, Text::Template no longer generates a warning if
222 you try to give a variable an undefined value.
224 ----------------------------------------------------------------
226 What's new in v1.12 since v1.11:
228 I forgot to say that Text::Template ISA Exporter, so the
229 exported functions never got exported. Duhhh!
231 Template TYPEs are now case-insensitive. The `new' method now
232 diagnoses attempts to use an invalid TYPE.
234 More tests for these things.
236 ----------------------------------------------------------------
238 What's new in v1.11 since v1.10:
240 Fixed a bug in the way backslashes were processed. The 1.10
241 behavior was incompatible with the beta versions and was also
242 inconvenient. (`\n' in templates was replaced with `n' before
243 it was given to Perl for evaluation.) The new behavior is
244 also incompatible with the beta versions, but it is only a
245 little bit incompatible, and it is probbaly better.
247 Documentation for the new behavior, and tests for the bug.
249 ----------------------------------------------------------------
251 What's new in v1.10 since v1.03:
253 New OUTPUT option delivers template results directly to a
254 filehandle instead of making them into a string. Saves space
257 PACKAGE and HASH now work intelligently with SAFE.
259 Fragments may now output data directly to the template, rather
260 than having to arrange to return it as a return value at the
261 end. This means that where you used to have to write this:
264 foreach $i (@items) {
265 $blist .= qq{ * $i\n};
270 You can now write this instead, because $OUT is special.
272 { foreach $i (@items) {
277 (`A spoonful of sugar makes the medicine go down.')
279 Fixed some small bugs. Worked around a bug in Perl that does
280 the wrong thing with $x = <Y> when $x contains a glob.
282 More documentation. Errors fixed.
286 ----------------------------------------------------------------
288 What's new in v1.03 since v1.0:
290 Code added to support HASH option to fill_in.
291 (Incl. `_gensym' function.)
293 Documentation for HASH.
295 New test file for HASH.
297 Note about failure of lexical variables to propagate into
298 templates. Why does this surprise people?
300 Bug fix: program fragments are evaluated in an environment with
301 `no strict' by default. Otherwise, you get a lot of `Global
302 symbol "$v" requires explicit package name' failures. Why didn't
303 the test program pick this up? Because the only variable the test
304 program ever used was `$a', which is exempt. Duhhhhh.
306 Fixed the test program.
308 Various minor documentation fixes.
312 ----------------------------------------------------------------
314 Improvements of 1.0 over the old 0.1beta:
318 At least twice as fast
320 Better support for filling out the same template more than once
322 Now supports evaluation of program fragments in Safe
323 compartments. (Thanks, Jonathan!)
325 Better argument syntax
327 More convenience functions
329 The parser is much better and simpler.
331 Once a template is parsed, the parsed version is stored so that
332 it needn't be parsed again.
334 BROKEN function behavior is rationalized. You can now pass an
335 arbitrary argument to your BROKEN function, or return a value
336 from it to the main program.
338 Documentation overhauled.