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