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