| 1 |
|
|---|
| 2 | Text::Template v1.46
|
|---|
| 3 |
|
|---|
| 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.
|
|---|
| 9 |
|
|---|
| 10 | Here'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 |
|
|---|
| 24 | The result of filling in this template is a string, which might look
|
|---|
| 25 | something 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 |
|
|---|
| 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.
|
|---|
| 44 |
|
|---|
| 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
|
|---|
| 48 | execute it.
|
|---|
| 49 |
|
|---|
| 50 | ----------------------------------------------------------------
|
|---|
| 51 |
|
|---|
| 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.
|
|---|
| 57 |
|
|---|
| 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.
|
|---|
| 62 |
|
|---|
| 63 | Questions or comments should be addressed to
|
|---|
| 64 | [email protected]. This address goes directly to me, and
|
|---|
| 65 | not to anyone else; it is not a mailing list address.
|
|---|
| 66 |
|
|---|
| 67 | To receive occasional announcements of new versions of T::T, send an
|
|---|
| 68 | empty note to [email protected]. 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.
|
|---|
| 71 |
|
|---|
| 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/>.
|
|---|
| 75 |
|
|---|
| 76 | ----------------------------------------------------------------
|
|---|
| 77 |
|
|---|
| 78 | What'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 | ----------------------------------------------------------------
|
|---|
| 90 | What's new in v1.44 since v1.43:
|
|---|
| 91 |
|
|---|
| 92 | This 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 | ----------------------------------------------------------------
|
|---|
| 105 | What'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 |
|
|---|
| 115 | What's new in v1.42 since v1.41:
|
|---|
| 116 |
|
|---|
| 117 | This 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 |
|
|---|
| 125 | What's new in v1.41 since v1.40:
|
|---|
| 126 |
|
|---|
| 127 | This 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 |
|
|---|
| 134 | What'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 | ----------------------------------------------------------------
|
|---|
| 183 | What'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 | ----------------------------------------------------------------
|
|---|
| 189 | What'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 | ----------------------------------------------------------------
|
|---|
| 196 | What'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 | ----------------------------------------------------------------
|
|---|
| 207 | What'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 |
|
|---|
| 226 | What'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 |
|
|---|
| 238 | What'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 |
|
|---|
| 251 | What'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 |
|
|---|
| 288 | What'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 |
|
|---|
| 314 | Improvements of 1.0 over the old 0.1beta:
|
|---|
| 315 |
|
|---|
| 316 | New 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 |
|
|---|
