1
2Text::Template v1.46
3
4This is a library for generating form letters, building HTML pages, or
5filling in templates generally. A `template' is a piece of text that
6has little Perl programs embedded in it here and there. When you
7`fill in' a template, you evaluate the little programs and replace
8them with their values.
9
10Here's an example of a template:
11
12 Dear {$title} {$lastname},
13
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.
18
19 Love,
20
21 Mark "{nickname(rand 20)}" Dominus
22
23
24The result of filling in this template is a string, which might look
25something like this:
26
27 Dear Mr. Gates,
28
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.
33
34
35 Love,
36
37 Mark "Vizopteryx" Dominus
38
39You can store a template in a file outside your program. People can
40modify the template without modifying the program. You can separate
41the formatting details from the main code, and put the formatting
42parts of the program into the template. That prevents code bloat and
43encourages functional separation.
44
45You can fill in the template in a `Safe' compartment. This means that
46if you don't trust the person who wrote the code in the template, you
47won't have to worry that they are tampering with your program when you
48execute it.
49
50----------------------------------------------------------------
51
52Text::Template was originally released some time in late 1995 or early
531996. After three years of study and investigation, I rewrote it from
54scratch in January 1999. The new version, 1.0, was much faster,
55delivered better functionality and was almost 100% backward-compatible
56with the previous beta versions.
57
58I have added a number of useful features and conveniences since the
591.0 release, while still retaining backward compatibility. With one
60merely cosmetic change, the current version of Text::Template passes
61the test suite that the old beta versions passed.
62
63Questions or comments should be addressed to
64mjd-perl-template+@plover.com. This address goes directly to me, and
65not to anyone else; it is not a mailing list address.
66
67To receive occasional announcements of new versions of T::T, send an
68empty note to mjd-perl-template-request@plover.com. This mailing list
69is not for discussion; it is for announcements only. Therefore, there
70is no address for sending messages to the list.
71
72You can get the most recent version of Text::Template, news, comments,
73and other collateral information from
74<URL:http://www.plover.com/~mjd/perl/Template/>.
75
76----------------------------------------------------------------
77
78What's new in v1.46 since v1.44:
79
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.
85
86 A spurious warning is no longer emitted when the TYPE
87 parameter to ->new is omitted.
88
89----------------------------------------------------------------
90What's new in v1.44 since v1.43:
91
92This is a maintentance release. There are no feature changes.
93
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.
99
100 Minor changes to the test suite to prevent spurious errors.
101
102 Minor documentation changes.
103
104----------------------------------------------------------------
105What's new in v1.43 since v1.42:
106
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.
112
113----------------------------------------------------------------
114
115What's new in v1.42 since v1.41:
116
117This is a maintentance release. There are no feature changes.
118
119 Fixed a bug relating to use of UNTAINT under perl 5.005_03 and
120 possibly other versions.
121
122 Taint-related tests are now more comprehensive.
123----------------------------------------------------------------
124
125What's new in v1.41 since v1.40:
126
127This is a maintentance release. There are no feature changes.
128
129 Tests now work correctly on Windows systems and possibly on
130 other non-unix systems.
131
132----------------------------------------------------------------
133
134What's new in v1.40 since v1.31:
135
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.
138
139 Code added to prevent memory leaks when filling many
140 templates. Thanks to Itamar Almeida de Carvalho.
141
142 Bug fix: $OUT was not correctly initialized when used in
143 conjunction with SAFE.
144
145 You may now use a glob ref when passing a filehandle to the
146 ->new funcion. Formerly, a glob was reuqired.
147
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
153 is evaluated.
154
155 Error messages passed to BROKEN subroutines will now report
156 the correct line number of the template at which the error
157 occurred:
158
159 Illegal division by zero at template line 37.
160
161 If the template comes from a file, the filename will be
162 reported as well:
163
164 Illegal division by zero at catalog.tmpl line 37.
165
166
167 INCOMPATIBLE CHANGE:
168
169 The format of the default error message has changed. It used
170 to look like:
171
172 Program fragment at line 30 delivered error ``Illegal division by zero''
173
174 It now looks like:
175
176 Program fragment delivered error ``Illegal division by zero at catalog.tmpl line 37''
177
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.
181
182----------------------------------------------------------------
183What's new in v1.31 since v1.23:
184
185 Just bug fixes---fill_in_string was failing. Thanks to
186 Donald L. Greer Jr. for the test case.
187
188----------------------------------------------------------------
189What's new in v1.23 since v1.22:
190
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.)
194
195----------------------------------------------------------------
196What's new in v1.22 since v1.20:
197
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.
205
206----------------------------------------------------------------
207What's new in v1.20 since v1.12:
208
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.
217
218 See the manual section on `Alternative Delimiters'.
219
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.
223
224----------------------------------------------------------------
225
226What's new in v1.12 since v1.11:
227
228 I forgot to say that Text::Template ISA Exporter, so the
229 exported functions never got exported. Duhhh!
230
231 Template TYPEs are now case-insensitive. The `new' method now
232 diagnoses attempts to use an invalid TYPE.
233
234 More tests for these things.
235
236----------------------------------------------------------------
237
238What's new in v1.11 since v1.10:
239
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.
246
247 Documentation for the new behavior, and tests for the bug.
248
249----------------------------------------------------------------
250
251What's new in v1.10 since v1.03:
252
253 New OUTPUT option delivers template results directly to a
254 filehandle instead of making them into a string. Saves space
255 and time.
256
257 PACKAGE and HASH now work intelligently with SAFE.
258
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:
262
263 { my $blist = '';
264 foreach $i (@items) {
265 $blist .= qq{ * $i\n};
266 }
267 $blist;
268 }
269
270 You can now write this instead, because $OUT is special.
271
272 { foreach $i (@items) {
273 $OUT.= " * $i\n";
274 }
275 }
276
277 (`A spoonful of sugar makes the medicine go down.')
278
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.
281
282 More documentation. Errors fixed.
283
284 Lots more tests.
285
286----------------------------------------------------------------
287
288What's new in v1.03 since v1.0:
289
290 Code added to support HASH option to fill_in.
291 (Incl. `_gensym' function.)
292
293 Documentation for HASH.
294
295 New test file for HASH.
296
297 Note about failure of lexical variables to propagate into
298 templates. Why does this surprise people?
299
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.
305
306 Fixed the test program.
307
308 Various minor documentation fixes.
309
310
311
312----------------------------------------------------------------
313
314Improvements of 1.0 over the old 0.1beta:
315
316New features:
317
318 At least twice as fast
319
320 Better support for filling out the same template more than once
321
322 Now supports evaluation of program fragments in Safe
323 compartments. (Thanks, Jonathan!)
324
325 Better argument syntax
326
327 More convenience functions
328
329 The parser is much better and simpler.
330
331 Once a template is parsed, the parsed version is stored so that
332 it needn't be parsed again.
333
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.
337
338 Documentation overhauled.
339
340