external/perl/Text-Template-1.46/README

   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 mjd-perl-template+@plover.com.  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 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.
  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