local-lib5/man/man3/Template::Manual::Config.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Manual::Config 3"
 132 .TH Template::Manual::Config 3 "2009-04-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Manual::Config \- Configuration options
 135 .SH "Template Style and Parsing Options"
 136 .IX Header "Template Style and Parsing Options"
 137 .Sh "\s-1START_TAG\s0, \s-1END_TAG\s0"
 138 .IX Subsection "START_TAG, END_TAG"
 139 The \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR options are used to specify character
 140 sequences or regular expressions that mark the start and end of a
 141 template directive.  The default values for \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR are
 142 \&'\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR' respectively, giving us the familiar directive style:
 143 .PP
 144 .Vb 1
 145 \&    [% example %]
 146 .Ve
 147 .PP
 148 Any Perl regex characters can be used and therefore should be escaped
 149 (or use the Perl \f(CW\*(C`quotemeta\*(C'\fR function) if they are intended to
 150 represent literal characters.
 151 .PP
 152 .Vb 4
 153 \&    my $template = Template\->new({
 154 \&        START_TAG => quotemeta('<+'),
 155 \&        END_TAG   => quotemeta('+>'),
 156 \&    });
 157 .Ve
 158 .PP
 159 Example:
 160 .PP
 161 .Vb 1
 162 \&    <+ INCLUDE foobar +>
 163 .Ve
 164 .PP
 165 The \f(CW\*(C`TAGS\*(C'\fR directive can also be used to set the \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR values
 166 on a per-template file basis.
 167 .PP
 168 .Vb 1
 169 \&    [% TAGS <+ +> %]
 170 .Ve
 171 .Sh "\s-1TAG_STYLE\s0"
 172 .IX Subsection "TAG_STYLE"
 173 The \f(CW\*(C`TAG_STYLE\*(C'\fR option can be used to set both \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR
 174 according to pre-defined tag styles.
 175 .PP
 176 .Vb 3
 177 \&    my $template = Template\->new({
 178 \&        TAG_STYLE => 'star',
 179 \&    });
 180 .Ve
 181 .PP
 182 Available styles are:
 183 .PP
 184 .Vb 8
 185 \&    template    [% ... %]               (default)
 186 \&    template1   [% ... %] or %% ... %%  (TT version 1)
 187 \&    metatext    %% ... %%               (Text::MetaText)
 188 \&    star        [* ... *]               (TT alternate)
 189 \&    php         <? ... ?>               (PHP)
 190 \&    asp         <% ... %>               (ASP)
 191 \&    mason       <% ...  >               (HTML::Mason)
 192 \&    html        <!\-\- ... \-\->            (HTML comments)
 193 .Ve
 194 .PP
 195 Any values specified for \f(CW\*(C`START_TAG\*(C'\fR and/or \f(CW\*(C`END_TAG\*(C'\fR will override
 196 those defined by a \f(CW\*(C`TAG_STYLE\*(C'\fR.
 197 .PP
 198 The \f(CW\*(C`TAGS\*(C'\fR directive may also be used to set a \f(CW\*(C`TAG_STYLE\*(C'\fR
 199 .PP
 200 .Vb 2
 201 \&    [% TAGS html %]
 202 \&    <!\-\- INCLUDE header \-\->
 203 .Ve
 204 .Sh "\s-1PRE_CHOMP\s0, \s-1POST_CHOMP\s0"
 205 .IX Subsection "PRE_CHOMP, POST_CHOMP"
 206 Anything outside a directive tag is considered plain text and is
 207 generally passed through unaltered (but see the \s-1INTERPOLATE\s0 option).
 208 This includes all whitespace and newlines characters surrounding
 209 directive tags.  Directives that don't generate any output will leave
 210 gaps in the output document.
 211 .PP
 212 Example:
 213 .PP
 214 .Vb 3
 215 \&    Foo
 216 \&    [% a = 10 %]
 217 \&    Bar
 218 .Ve
 219 .PP
 220 Output:
 221 .PP
 222 .Vb 1
 223 \&    Foo
 224 .Ve
 225 .PP
 226 .Vb 1
 227 \&    Bar
 228 .Ve
 229 .PP
 230 The \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR options can help to clean up some of this
 231 extraneous whitespace.  Both are disabled by default.
 232 .PP
 233 .Vb 4
 234 \&    my $template = Template\-E<gt>new({
 235 \&        PRE_CHOMP  => 1,
 236 \&        POST_CHOMP => 1,
 237 \&    });
 238 .Ve
 239 .PP
 240 With \f(CW\*(C`PRE_CHOMP\*(C'\fR set to \f(CW1\fR, the newline and whitespace preceding a directive
 241 at the start of a line will be deleted.  This has the effect of
 242 concatenating a line that starts with a directive onto the end of the
 243 previous line.
 244 .PP
 245 .Vb 9
 246 \&        Foo <\-\-\-\-\-\-\-\-\-\-.
 247 \&                       |
 248 \&    ,\-\-\-(PRE_CHOMP)\-\-\-\-'
 249 \&    |
 250 \&    `\-\- [% a = 10 %] \-\-.
 251 \&                       |
 252 \&    ,\-\-\-(POST_CHOMP)\-\-\-'
 253 \&    |
 254 \&    `\-> Bar
 255 .Ve
 256 .PP
 257 With \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW1\fR, any whitespace after a directive up to and
 258 including the newline will be deleted.  This has the effect of joining
 259 a line that ends with a directive onto the start of the next line.
 260 .PP
 261 If \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR is set to \f(CW2\fR, all whitespace including any
 262 number of newline will be removed and replaced with a single space.
 263 This is useful for \s-1HTML\s0, where (usually) a contiguous block of
 264 whitespace is rendered the same as a single space.
 265 .PP
 266 With \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW3\fR, all adjacent whitespace
 267 (including newlines) will be removed entirely.
 268 .PP
 269 These values are defined as \f(CW\*(C`CHOMP_NONE\*(C'\fR, \f(CW\*(C`CHOMP_ONE\*(C'\fR, \f(CW\*(C`CHOMP_COLLAPSE\*(C'\fR and
 270 \&\f(CW\*(C`CHOMP_GREEDY\*(C'\fR constants in the Template::Constants module.  \f(CW\*(C`CHOMP_ALL\*(C'\fR
 271 is also defined as an alias for \f(CW\*(C`CHOMP_ONE\*(C'\fR to provide backwards
 272 compatability with earlier version of the Template Toolkit.
 273 .PP
 274 Additionally the chomp tag modifiers listed below may also be used for
 275 the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration.
 276 .PP
 277 .Vb 4
 278 \&     my $template = Template\->new({
 279 \&        PRE_CHOMP  => '~',
 280 \&        POST_CHOMP => '\-',
 281 \&     });
 282 .Ve
 283 .PP
 284 \&\f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR can be activated for individual directives by
 285 placing a '\f(CW\*(C`\-\*(C'\fR' immediately at the start and/or end of the directive.
 286 .PP
 287 .Vb 3
 288 \&    [% FOREACH user IN userlist %]
 289 \&       [%\- user \-%]
 290 \&    [% END %]
 291 .Ve
 292 .PP
 293 This has the same effect as \f(CW\*(C`CHOMP_ONE\*(C'\fR in removing all whitespace
 294 before or after the directive up to and including the newline.  The
 295 template will be processed as if written:
 296 .PP
 297 .Vb 1
 298 \&    [% FOREACH user IN userlist %][% user %][% END %]
 299 .Ve
 300 .PP
 301 To remove all whitespace including any number of newlines, use the '\f(CW\*(C`~\*(C'\fR'
 302 character instead.
 303 .PP
 304 .Vb 1
 305 \&    [% FOREACH user IN userlist %]
 306 .Ve
 307 .PP
 308 .Vb 1
 309 \&       [%~ user ~%]
 310 .Ve
 311 .PP
 312 .Vb 1
 313 \&    [% END %]
 314 .Ve
 315 .PP
 316 To collapse all whitespace to a single space, use the '\f(CW\*(C`=\*(C'\fR' character.
 317 .PP
 318 .Vb 1
 319 \&    [% FOREACH user IN userlist %]
 320 .Ve
 321 .PP
 322 .Vb 1
 323 \&       [%= user =%]
 324 .Ve
 325 .PP
 326 .Vb 1
 327 \&    [% END %]
 328 .Ve
 329 .PP
 330 Here the template is processed as if written:
 331 .PP
 332 .Vb 1
 333 \&    [% FOREACH user IN userlist %] [% user %] [% END %]
 334 .Ve
 335 .PP
 336 If you have \f(CW\*(C`PRE_CHOMP\*(C'\fR or \f(CW\*(C`POST_CHOMP\*(C'\fR set as configuration options then
 337 you can use '\f(CW\*(C`+\*(C'\fR' to disable any chomping options (i.e.  leave the
 338 whitespace intact) on a per-directive basis.
 339 .PP
 340 .Vb 3
 341 \&    [% FOREACH user IN userlist %]
 342 \&    User: [% user +%]
 343 \&    [% END %]
 344 .Ve
 345 .PP
 346 With \f(CW\*(C`POST_CHOMP\*(C'\fR set to \f(CW\*(C`CHOMP_ONE\*(C'\fR, the above example would be parsed as
 347 if written:
 348 .PP
 349 .Vb 2
 350 \&    [% FOREACH user IN userlist %]User: [% user %]
 351 \&    [% END %]
 352 .Ve
 353 .PP
 354 For reference, the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration options may be
 355 set to any of the following:
 356 .PP
 357 .Vb 6
 358 \&     Constant      Value   Tag Modifier
 359 \&     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 360 \&     CHOMP_NONE      0          +
 361 \&     CHOMP_ONE       1          \-
 362 \&     CHOMP_COLLAPSE  2          =
 363 \&     CHOMP_GREEDY    3          ~
 364 .Ve
 365 .Sh "\s-1TRIM\s0"
 366 .IX Subsection "TRIM"
 367 The \f(CW\*(C`TRIM\*(C'\fR option can be set to have any leading and trailing whitespace
 368 automatically removed from the output of all template files and \f(CW\*(C`BLOCK\*(C'\fRs.
 369 .PP
 370 By example, the following \f(CW\*(C`BLOCK\*(C'\fR definition
 371 .PP
 372 .Vb 3
 373 \&    [% BLOCK foo %]
 374 \&    Line 1 of foo
 375 \&    [% END %]
 376 .Ve
 377 .PP
 378 will be processed is as "\f(CW\*(C`\enLine 1 of foo\en\*(C'\fR".  When \f(CW\*(C`INCLUDE\*(C'\fRd, the surrounding
 379 newlines will also be introduced.
 380 .PP
 381 .Vb 3
 382 \&    before
 383 \&    [% INCLUDE foo %]
 384 \&    after
 385 .Ve
 386 .PP
 387 Generated output:
 388 .PP
 389 .Vb 1
 390 \&    before
 391 .Ve
 392 .PP
 393 .Vb 1
 394 \&    Line 1 of foo
 395 .Ve
 396 .PP
 397 .Vb 1
 398 \&    after
 399 .Ve
 400 .PP
 401 With the \f(CW\*(C`TRIM\*(C'\fR option set to any true value, the leading and trailing
 402 newlines (which count as whitespace) will be removed from the output
 403 of the \f(CW\*(C`BLOCK\*(C'\fR.
 404 .PP
 405 .Vb 3
 406 \&    before
 407 \&    Line 1 of foo
 408 \&    after
 409 .Ve
 410 .PP
 411 The \f(CW\*(C`TRIM\*(C'\fR option is disabled (\f(CW0\fR) by default.
 412 .Sh "\s-1INTERPOLATE\s0"
 413 .IX Subsection "INTERPOLATE"
 414 The \f(CW\*(C`INTERPOLATE\*(C'\fR flag, when set to any true value will cause variable
 415 references in plain text (i.e. not surrounded by \f(CW\*(C`START_TAG\*(C'\fR and \f(CW\*(C`END_TAG\*(C'\fR)
 416 to be recognised and interpolated accordingly.
 417 .PP
 418 .Vb 3
 419 \&    my $template = Template\->new({
 420 \&        INTERPOLATE => 1,
 421 \&    });
 422 .Ve
 423 .PP
 424 Variables should be prefixed by a '\f(CW\*(C`$\*(C'\fR' to identify them.  Curly braces
 425 can be used in the familiar Perl/shell style to explicitly scope the
 426 variable name where required.
 427 .PP
 428 .Vb 4
 429 \&    # INTERPOLATE => 0
 430 \&    <a href="http://[% server %]/[% help %]">
 431 \&    <img src="[% images %]/help.gif"></a>
 432 \&    [% myorg.name %]
 433 .Ve
 434 .PP
 435 .Vb 4
 436 \&    # INTERPOLATE => 1
 437 \&    <a href="http://$server/$help">
 438 \&    <img src="$images/help.gif"></a>
 439 \&    $myorg.name
 440 .Ve
 441 .PP
 442 .Vb 2
 443 \&    # explicit scoping with {  }
 444 \&    <img src="$images/${icon.next}.gif">
 445 .Ve
 446 .PP
 447 Note that a limitation in Perl's regex engine restricts the maximum length
 448 of an interpolated template to around 32 kilobytes or possibly less.  Files
 449 that exceed this limit in size will typically cause Perl to dump core with
 450 a segmentation fault.  If you routinely process templates of this size
 451 then you should disable \f(CW\*(C`INTERPOLATE\*(C'\fR or split the templates in several
 452 smaller files or blocks which can then be joined backed together via
 453 \&\f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`INCLUDE\*(C'\fR.
 454 .Sh "\s-1ANYCASE\s0"
 455 .IX Subsection "ANYCASE"
 456 By default, directive keywords should be expressed in \s-1UPPER\s0 \s-1CASE\s0.  The
 457 \&\f(CW\*(C`ANYCASE\*(C'\fR option can be set to allow directive keywords to be specified
 458 in any case.
 459 .PP
 460 .Vb 4
 461 \&    # ANYCASE => 0 (default)
 462 \&    [% INCLUDE foobar %]        # OK
 463 \&    [% include foobar %]        # ERROR
 464 \&    [% include = 10   %]        # OK, 'include' is a variable
 465 .Ve
 466 .PP
 467 .Vb 4
 468 \&    # ANYCASE => 1
 469 \&    [% INCLUDE foobar %]        # OK
 470 \&    [% include foobar %]        # OK
 471 \&    [% include = 10   %]        # ERROR, 'include' is reserved word
 472 .Ve
 473 .PP
 474 One side-effect of enabling \f(CW\*(C`ANYCASE\*(C'\fR is that you cannot use a variable
 475 of the same name as a reserved word, regardless of case.  The reserved
 476 words are currently:
 477 .PP
 478 .Vb 5
 479 \&    GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
 480 \&    IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
 481 \&    USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
 482 \&    TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
 483 \&    CLEAR TO STEP AND OR NOT MOD DIV END
 484 .Ve
 485 .PP
 486 The only lower case reserved words that cannot be used for variables,
 487 regardless of the \f(CW\*(C`ANYCASE\*(C'\fR option, are the operators:
 488 .PP
 489 .Vb 1
 490 \&    and or not mod div
 491 .Ve
 492 .SH "Template Files and Blocks"
 493 .IX Header "Template Files and Blocks"
 494 .Sh "\s-1INCLUDE_PATH\s0"
 495 .IX Subsection "INCLUDE_PATH"
 496 The \f(CW\*(C`INCLUDE_PATH\*(C'\fR is used to specify one or more directories in which
 497 template files are located.  When a template is requested that isn't
 498 defined locally as a \f(CW\*(C`BLOCK\*(C'\fR, each of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories is
 499 searched in turn to locate the template file.  Multiple directories
 500 can be specified as a reference to a list or as a single string where
 501 each directory is delimited by '\f(CW\*(C`:\*(C'\fR'.
 502 .PP
 503 .Vb 3
 504 \&    my $template = Template\->new({
 505 \&        INCLUDE_PATH => '/usr/local/templates',
 506 \&    });
 507 .Ve
 508 .PP
 509 .Vb 3
 510 \&    my $template = Template\->new({
 511 \&        INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
 512 \&    });
 513 .Ve
 514 .PP
 515 .Vb 4
 516 \&    my $template = Template\->new({
 517 \&        INCLUDE_PATH => [ '/usr/local/templates',
 518 \&                          '/tmp/my/templates' ],
 519 \&    });
 520 .Ve
 521 .PP
 522 On Win32 systems, a little extra magic is invoked, ignoring delimiters
 523 that have '\f(CW\*(C`:\*(C'\fR' followed by a '\f(CW\*(C`/\*(C'\fR' or '\f(CW\*(C`\e\*(C'\fR'.  This avoids confusion when using
 524 directory names like '\f(CW\*(C`C:\eBlah Blah\*(C'\fR'.
 525 .PP
 526 When specified as a list, the \f(CW\*(C`INCLUDE_PATH\*(C'\fR path can contain elements
 527 which dynamically generate a list of \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories.  These
 528 generator elements can be specified as a reference to a subroutine or
 529 an object which implements a \f(CW\*(C`paths()\*(C'\fR method.
 530 .PP
 531 .Vb 5
 532 \&    my $template = Template\->new({
 533 \&        INCLUDE_PATH => [ '/usr/local/templates',
 534 \&                          \e&incpath_generator,
 535 \&                          My::IncPath::Generator\->new( ... ) ],
 536 \&    });
 537 .Ve
 538 .PP
 539 Each time a template is requested and the \f(CW\*(C`INCLUDE_PATH\*(C'\fR examined, the
 540 subroutine or object method will be called.  A reference to a list of
 541 directories should be returned.  Generator subroutines should report
 542 errors using \f(CW\*(C`die()\*(C'\fR.  Generator objects should return undef and make an
 543 error available via its \f(CW\*(C`error()\*(C'\fR method.
 544 .PP
 545 For example:
 546 .PP
 547 .Vb 2
 548 \&    sub incpath_generator {
 549 \&        # ...some code...
 550 .Ve
 551 .PP
 552 .Vb 7
 553 \&        if ($all_is_well) {
 554 \&            return \e@list_of_directories;
 555 \&        }
 556 \&        else {
 557 \&            die "cannot generate INCLUDE_PATH...\en";
 558 \&        }
 559 \&    }
 560 .Ve
 561 .PP
 562 or:
 563 .PP
 564 .Vb 1
 565 \&    package My::IncPath::Generator;
 566 .Ve
 567 .PP
 568 .Vb 3
 569 \&    # Template::Base (or Class::Base) provides error() method
 570 \&    use Template::Base;
 571 \&    use base qw( Template::Base );
 572 .Ve
 573 .PP
 574 .Vb 2
 575 \&    sub paths {
 576 \&        my $self = shift;
 577 .Ve
 578 .PP
 579 .Vb 1
 580 \&        # ...some code...
 581 .Ve
 582 .PP
 583 .Vb 7
 584 \&        if ($all_is_well) {
 585 \&            return \e@list_of_directories;
 586 \&        }
 587 \&        else {
 588 \&            return $self\->error("cannot generate INCLUDE_PATH...\en");
 589 \&        }
 590 \&    }
 591 .Ve
 592 .PP
 593 .Vb 1
 594 \&    1;
 595 .Ve
 596 .Sh "\s-1DELIMITER\s0"
 597 .IX Subsection "DELIMITER"
 598 Used to provide an alternative delimiter character sequence for
 599 separating paths specified in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR.  The default
 600 value for \f(CW\*(C`DELIMITER\*(C'\fR is '\f(CW\*(C`:\*(C'\fR'.
 601 .PP
 602 .Vb 4
 603 \&    my $template = Template\->new({
 604 \&        DELIMITER    => '; ',
 605 \&        INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
 606 \&    });
 607 .Ve
 608 .PP
 609 On Win32 systems, the default delimiter is a little more intelligent,
 610 splitting paths only on '\f(CW\*(C`:\*(C'\fR' characters that aren't followed by a '\f(CW\*(C`/\*(C'\fR'.
 611 This means that the following should work as planned, splitting the
 612 \&\f(CW\*(C`INCLUDE_PATH\*(C'\fR into 2 separate directories, \f(CW\*(C`C:/foo\*(C'\fR and \f(CW\*(C`C:/bar\*(C'\fR.
 613 .PP
 614 .Vb 4
 615 \&    # on Win32 only
 616 \&    my $template = Template\->new({
 617 \&        INCLUDE_PATH => 'C:/Foo:C:/Bar'
 618 \&    });
 619 .Ve
 620 .PP
 621 However, if you're using Win32 then it's recommended that you
 622 explicitly set the \f(CW\*(C`DELIMITER\*(C'\fR character to something else (e.g. '\f(CW\*(C`;\*(C'\fR')
 623 rather than rely on this subtle magic.
 624 .Sh "\s-1ABSOLUTE\s0"
 625 .IX Subsection "ABSOLUTE"
 626 The \f(CW\*(C`ABSOLUTE\*(C'\fR flag is used to indicate if templates specified with
 627 absolute filenames (e.g. '\f(CW\*(C`/foo/bar\*(C'\fR') should be processed.  It is
 628 disabled by default and any attempt to load a template by such a
 629 name will cause a '\f(CW\*(C`file\*(C'\fR' exception to be raised.
 630 .PP
 631 .Vb 3
 632 \&    my $template = Template\->new({
 633 \&        ABSOLUTE => 1,
 634 \&    });
 635 .Ve
 636 .PP
 637 .Vb 2
 638 \&    # this is why it's disabled by default
 639 \&    [% INSERT /etc/passwd %]
 640 .Ve
 641 .PP
 642 On Win32 systems, the regular expression for matching absolute
 643 pathnames is tweaked slightly to also detect filenames that start
 644 with a driver letter and colon, such as:
 645 .PP
 646 .Vb 1
 647 \&    C:/Foo/Bar
 648 .Ve
 649 .Sh "\s-1RELATIVE\s0"
 650 .IX Subsection "RELATIVE"
 651 The \f(CW\*(C`RELATIVE\*(C'\fR flag is used to indicate if templates specified with
 652 filenames relative to the current directory (e.g. '\f(CW\*(C`./foo/bar\*(C'\fR' or
 653 \&'\f(CW\*(C`../../some/where/else\*(C'\fR') should be loaded.  It is also disabled by
 654 default, and will raise a '\f(CW\*(C`file\*(C'\fR' error if such template names are
 655 encountered.
 656 .PP
 657 .Vb 3
 658 \&    my $template = Template\->new({
 659 \&        RELATIVE => 1,
 660 \&    });
 661 .Ve
 662 .PP
 663 .Vb 1
 664 \&    [% INCLUDE ../logs/error.log %]
 665 .Ve
 666 .Sh "\s-1DEFAULT\s0"
 667 .IX Subsection "DEFAULT"
 668 The \f(CW\*(C`DEFAULT\*(C'\fR option can be used to specify a default template which should
 669 be used whenever a specified template can't be found in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR.
 670 .PP
 671 .Vb 3
 672 \&    my $template = Template\->new({
 673 \&        DEFAULT => 'notfound.html',
 674 \&    });
 675 .Ve
 676 .PP
 677 If a non-existant template is requested through the Template
 678 \&\fIprocess()\fR method, or by an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or
 679 \&\f(CW\*(C`WRAPPER\*(C'\fR directive, then the \f(CW\*(C`DEFAULT\*(C'\fR template will instead be processed, if
 680 defined. Note that the \f(CW\*(C`DEFAULT\*(C'\fR template is not used when templates are
 681 specified with absolute or relative filenames, or as a reference to a input
 682 file handle or text string.
 683 .Sh "\s-1BLOCKS\s0"
 684 .IX Subsection "BLOCKS"
 685 The \f(CW\*(C`BLOCKS\*(C'\fR option can be used to pre-define a default set of template
 686 blocks.  These should be specified as a reference to a hash array
 687 mapping template names to template text, subroutines or Template::Document
 688 objects.
 689 .PP
 690 .Vb 7
 691 \&    my $template = Template\->new({
 692 \&        BLOCKS => {
 693 \&            header  => 'The Header.  [% title %]',
 694 \&            footer  => sub { return $some_output_text },
 695 \&            another => Template::Document\->new({ ... }),
 696 \&        },
 697 \&    });
 698 .Ve
 699 .Sh "\s-1VIEWS\s0"
 700 .IX Subsection "VIEWS"
 701 The \s-1VIEWS\s0 option can be used to define one or more Template::View
 702 objects.  They can be specified as a reference to a hash array or list
 703 reference.
 704 .PP
 705 .Vb 5
 706 \&    my $template = Template\->new({
 707 \&        VIEWS => {
 708 \&            my_view => { prefix => 'my_templates/' },
 709 \&        },
 710 \&    });
 711 .Ve
 712 .PP
 713 Be aware of the fact that Perl's hash array are unordered, so if you want to
 714 specify multiple views of which one or more are based on other views, then
 715 you should use a list reference to preserve the order of definition.
 716 .PP
 717 .Vb 7
 718 \&    my $template = Template\->new({
 719 \&        VIEWS => [
 720 \&            bottom => { prefix => 'bottom/' },
 721 \&            middle => { prefix => 'middle/', base => 'bottom' },
 722 \&            top    => { prefix => 'top/',    base => 'middle' },
 723 \&        ],
 724 \&    });
 725 .Ve
 726 .Sh "\s-1AUTO_RESET\s0"
 727 .IX Subsection "AUTO_RESET"
 728 The \f(CW\*(C`AUTO_RESET\*(C'\fR option is set by default and causes the local \f(CW\*(C`BLOCKS\*(C'\fR
 729 cache for the Template::Context object to be reset on each call to the
 730 Template \fIprocess()\fR method. This ensures that any \f(CW\*(C`BLOCK\*(C'\fRs
 731 defined within a template will only persist until that template is finished
 732 processing. This prevents \f(CW\*(C`BLOCK\*(C'\fRs defined in one processing request from
 733 interfering with other independent requests subsequently processed by the same
 734 context object.
 735 .PP
 736 The \f(CW\*(C`BLOCKS\*(C'\fR item may be used to specify a default set of block definitions
 737 for the Template::Context object. Subsequent \f(CW\*(C`BLOCK\*(C'\fR definitions in
 738 templates will over-ride these but they will be reinstated on each reset if
 739 \&\f(CW\*(C`AUTO_RESET\*(C'\fR is enabled (default), or if the Template::Context
 740 \&\fIreset()\fR method is called.
 741 .Sh "\s-1RECURSION\s0"
 742 .IX Subsection "RECURSION"
 743 The template processor will raise a file exception if it detects
 744 direct or indirect recursion into a template.  Setting this option to
 745 any true value will allow templates to include each other recursively.
 746 .SH "Template Variables"
 747 .IX Header "Template Variables"
 748 .Sh "\s-1VARIABLES\s0"
 749 .IX Subsection "VARIABLES"
 750 The \f(CW\*(C`VARIABLES\*(C'\fR option (or \f(CW\*(C`PRE_DEFINE\*(C'\fR \- they're equivalent) can be used
 751 to specify a hash array of template variables that should be used to
 752 pre-initialise the stash when it is created.  These items are ignored
 753 if the \f(CW\*(C`STASH\*(C'\fR item is defined.
 754 .PP
 755 .Vb 7
 756 \&    my $template = Template\->new({
 757 \&        VARIABLES => {
 758 \&            title   => 'A Demo Page',
 759 \&            author  => 'Joe Random Hacker',
 760 \&            version => 3.14,
 761 \&        },
 762 \&    };
 763 .Ve
 764 .PP
 765 or
 766 .PP
 767 .Vb 7
 768 \&    my $template = Template\->new({
 769 \&        PRE_DEFINE => {
 770 \&            title   => 'A Demo Page',
 771 \&            author  => 'Joe Random Hacker',
 772 \&            version => 3.14,
 773 \&        },
 774 \&    };
 775 .Ve
 776 .Sh "\s-1CONSTANTS\s0"
 777 .IX Subsection "CONSTANTS"
 778 The \f(CW\*(C`CONSTANTS\*(C'\fR option can be used to specify a hash array of template
 779 variables that are compile-time constants.  These variables are
 780 resolved once when the template is compiled, and thus don't require
 781 further resolution at runtime.  This results in significantly faster
 782 processing of the compiled templates and can be used for variables that
 783 don't change from one request to the next.
 784 .PP
 785 .Vb 7
 786 \&    my $template = Template\->new({
 787 \&        CONSTANTS => {
 788 \&            title   => 'A Demo Page',
 789 \&            author  => 'Joe Random Hacker',
 790 \&            version => 3.14,
 791 \&        },
 792 \&    };
 793 .Ve
 794 .Sh "\s-1CONSTANT_NAMESPACE\s0"
 795 .IX Subsection "CONSTANT_NAMESPACE"
 796 Constant variables are accessed via the \f(CW\*(C`constants\*(C'\fR namespace by
 797 default.
 798 .PP
 799 .Vb 1
 800 \&    [% constants.title %]
 801 .Ve
 802 .PP
 803 The \f(CW\*(C`CONSTANTS_NAMESPACE\*(C'\fR option can be set to specify an alternate
 804 namespace.
 805 .PP
 806 .Vb 7
 807 \&    my $template = Template\->new({
 808 \&        CONSTANTS => {
 809 \&            title   => 'A Demo Page',
 810 \&            # ...etc...
 811 \&        },
 812 \&        CONSTANTS_NAMESPACE => 'const',
 813 \&    };
 814 .Ve
 815 .PP
 816 In this case the constants would then be accessed as:
 817 .PP
 818 .Vb 1
 819 \&    [% const.title %]
 820 .Ve
 821 .Sh "\s-1NAMESPACE\s0"
 822 .IX Subsection "NAMESPACE"
 823 The constant folding mechanism described above is an example of a
 824 namespace handler.  Namespace handlers can be defined to provide
 825 alternate parsing mechanisms for variables in different namespaces.
 826 .PP
 827 Under the hood, the Template module converts a constructor configuration
 828 such as:
 829 .PP
 830 .Vb 7
 831 \&    my $template = Template\->new({
 832 \&        CONSTANTS => {
 833 \&            title   => 'A Demo Page',
 834 \&            # ...etc...
 835 \&        },
 836 \&        CONSTANTS_NAMESPACE => 'const',
 837 \&    };
 838 .Ve
 839 .PP
 840 into one like:
 841 .PP
 842 .Vb 8
 843 \&    my $template = Template\->new({
 844 \&        NAMESPACE => {
 845 \&            const => Template:::Namespace::Constants\->new({
 846 \&                title   => 'A Demo Page',
 847 \&                # ...etc...
 848 \&            }),
 849 \&        },
 850 \&    };
 851 .Ve
 852 .PP
 853 You can use this mechanism to define multiple constant namespaces, or
 854 to install custom handlers of your own.
 855 .PP
 856 .Vb 13
 857 \&    my $template = Template\->new({
 858 \&        NAMESPACE => {
 859 \&            site => Template:::Namespace::Constants\->new({
 860 \&                title   => "Wardley's Widgets",
 861 \&                version => 2.718,
 862 \&            }),
 863 \&            author => Template:::Namespace::Constants\->new({
 864 \&                name  => 'Andy Wardley',
 865 \&                email => 'abw@andywardley.com',
 866 \&            }),
 867 \&            voodoo => My::Namespace::Handler\->new( ... ),
 868 \&        },
 869 \&    };
 870 .Ve
 871 .PP
 872 Now you have two constant namespaces, for example:
 873 .PP
 874 .Vb 2
 875 \&    [% site.title %]
 876 \&    [% author.name %]
 877 .Ve
 878 .PP
 879 as well as your own custom namespace handler installed for the 'voodoo'
 880 namespace.
 881 .PP
 882 .Vb 1
 883 \&    [% voodoo.magic %]
 884 .Ve
 885 .PP
 886 See Template::Namespace::Constants
 887 for an example of what a namespace handler looks like on the inside.
 888 .SH "Template Processing Options"
 889 .IX Header "Template Processing Options"
 890 The following options are used to specify any additional templates that should
 891 be processed before, after, around or instead of the template passed as the
 892 first argument to the Template \fIprocess()\fR method.
 893 These options can be perform various useful tasks such as adding standard
 894 headers or footers to all pages, wrapping page output in other templates,
 895 pre-defining variables or performing initialisation or cleanup tasks,
 896 automatically generating page summary information, navigation elements, and so
 897 on.
 898 .PP
 899 The task of processing the template is delegated internally to the
 900 Template::Service module which, unsurprisingly, also has a
 901 \&\fIprocess()\fR method. Any templates defined by the
 902 \&\f(CW\*(C`PRE_PROCESS\*(C'\fR option are processed first and any output generated is added to
 903 the output buffer. Then the main template is processed, or if one or more
 904 \&\f(CW\*(C`PROCESS\*(C'\fR templates are defined then they are instead processed in turn. In this
 905 case, one of the \f(CW\*(C`PROCESS\*(C'\fR templates is responsible for processing the main
 906 template, by a directive such as:
 907 .PP
 908 .Vb 1
 909 \&    [% PROCESS $template %]
 910 .Ve
 911 .PP
 912 The output of processing the main template or the \f(CW\*(C`PROCESS\*(C'\fR template(s)
 913 is then wrapped in any \f(CW\*(C`WRAPPER\*(C'\fR templates, if defined.  \f(CW\*(C`WRAPPER\*(C'\fR
 914 templates don't need to worry about explicitly processing the template
 915 because it will have been done for them already.  Instead \f(CW\*(C`WRAPPER\*(C'\fR
 916 templates access the content they are wrapping via the \f(CW\*(C`content\*(C'\fR
 917 variable.
 918 .PP
 919 .Vb 3
 920 \&    wrapper before
 921 \&    [% content %]
 922 \&    wrapper after
 923 .Ve
 924 .PP
 925 This output generated from processing the main template, and/or any
 926 \&\f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR templates is added to the output buffer.  Finally,
 927 any \f(CW\*(C`POST_PROCESS\*(C'\fR templates are processed and their output is also
 928 added to the output buffer which is then returned.
 929 .PP
 930 If the main template throws an exception during processing then any relevant
 931 template(s) defined via the \f(CW\*(C`ERROR\*(C'\fR option will be processed instead. If
 932 defined and successfully processed, the output from the error template will be
 933 added to the output buffer in place of the template that generated the error
 934 and processing will continue, applying any \f(CW\*(C`WRAPPER\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR
 935 templates. If no relevant \f(CW\*(C`ERROR\*(C'\fR option is defined, or if the error occurs
 936 in one of the \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR or \f(CW\*(C`POST_PROCESS\*(C'\fR templates, then
 937 the process will terminate immediately and the error will be returned.
 938 .Sh "\s-1PRE_PROCESS\s0, \s-1POST_PROCESS\s0"
 939 .IX Subsection "PRE_PROCESS, POST_PROCESS"
 940 These values may be set to contain the name(s) of template files
 941 (relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR) which should be processed immediately
 942 before and/or after each template.  These do not get added to
 943 templates processed into a document via directives such as \f(CW\*(C`INCLUDE\*(C'\fR,
 944 \&\f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`WRAPPER\*(C'\fR etc.
 945 .PP
 946 .Vb 4
 947 \&    my $template = Template\->new({
 948 \&        PRE_PROCESS  => 'header',
 949 \&        POST_PROCESS => 'footer',
 950 \&    };
 951 .Ve
 952 .PP
 953 Multiple templates may be specified as a reference to a list.  Each is
 954 processed in the order defined.
 955 .PP
 956 .Vb 4
 957 \&    my $template = Template\->new({
 958 \&        PRE_PROCESS  => [ 'config', 'header' ],
 959 \&        POST_PROCESS => 'footer',
 960 \&    };
 961 .Ve
 962 .PP
 963 Alternately, multiple template may be specified as a single string,
 964 delimited by '\f(CW\*(C`:\*(C'\fR'.  This delimiter string can be changed via the
 965 \&\f(CW\*(C`DELIMITER\*(C'\fR option.
 966 .PP
 967 .Vb 4
 968 \&    my $template = Template\->new({
 969 \&        PRE_PROCESS  => 'config:header',
 970 \&        POST_PROCESS => 'footer',
 971 \&    };
 972 .Ve
 973 .PP
 974 The \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates are evaluated in the same
 975 variable context as the main document and may define or update
 976 variables for subsequent use.
 977 .PP
 978 config:
 979 .PP
 980 .Vb 4
 981 \&    [% # set some site\-wide variables
 982 \&       bgcolor = '#ffffff'
 983 \&       version = 2.718
 984 \&    %]
 985 .Ve
 986 .PP
 987 header:
 988 .PP
 989 .Vb 6
 990 \&    [% DEFAULT title = 'My Funky Web Site' %]
 991 \&    <html>
 992 \&      <head>
 993 \&        <title>[% title %]</title>
 994 \&      </head>
 995 \&      <body bgcolor="[% bgcolor %]">
 996 .Ve
 997 .PP
 998 footer:
 999 .PP
1000 .Vb 4
1001 \&        <hr>
1002 \&        Version [% version %]
1003 \&      </body>
1004 \&    </html>
1005 .Ve
1006 .PP
1007 The Template::Document object representing the main template being processed
1008 is available within \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates as the \f(CW\*(C`template\*(C'\fR
1009 variable.  Metadata items defined via the \f(CW\*(C`META\*(C'\fR directive may be accessed
1010 accordingly.
1011 .PP
1012 .Vb 1
1013 \&    $template\->process('mydoc.html', $vars);
1014 .Ve
1015 .PP
1016 mydoc.html:
1017 .PP
1018 .Vb 3
1019 \&    [% META title = 'My Document Title' %]
1020 \&    blah blah blah
1021 \&    ...
1022 .Ve
1023 .PP
1024 header:
1025 .PP
1026 .Vb 5
1027 \&    <html>
1028 \&      <head>
1029 \&        <title>[% template.title %]</title>
1030 \&      </head>
1031 \&      <body bgcolor="[% bgcolor %]">
1032 .Ve
1033 .Sh "\s-1PROCESS\s0"
1034 .IX Subsection "PROCESS"
1035 The \f(CW\*(C`PROCESS\*(C'\fR option may be set to contain the name(s) of template files
1036 (relative to \f(CW\*(C`INCLUDE_PATH\*(C'\fR) which should be processed instead of the main
1037 template passed to the Template \fIprocess()\fR method.
1038 This can be used to apply consistent wrappers around all templates, similar to
1039 the use of \f(CW\*(C`PRE_PROCESS\*(C'\fR and \f(CW\*(C`POST_PROCESS\*(C'\fR templates.
1040 .PP
1041 .Vb 3
1042 \&    my $template = Template\->new({
1043 \&        PROCESS  => 'content',
1044 \&    };
1045 .Ve
1046 .PP
1047 .Vb 2
1048 \&    # processes 'content' instead of 'foo.html'
1049 \&    $template\->process('foo.html');
1050 .Ve
1051 .PP
1052 A reference to the original template is available in the \f(CW\*(C`template\*(C'\fR
1053 variable.  Metadata items can be inspected and the template can be
1054 processed by specifying it as a variable reference (i.e. prefixed by
1055 \&\f(CW\*(C`$\*(C'\fR) to an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive.
1056 .PP
1057 content:
1058 .PP
1059 .Vb 12
1060 \&    <html>
1061 \&      <head>
1062 \&        <title>[% template.title %]</title>
1063 \&      </head>
1064 \&      <body>
1065 \&    <!\-\- begin content \-\->
1066 \&    [% PROCESS $template %]
1067 \&    <!\-\- end content \-\->
1068 \&        <hr>
1069 \&        &copy; Copyright [% template.copyright %]
1070 \&      </body>
1071 \&    </html>
1072 .Ve
1073 .PP
1074 foo.html:
1075 .PP
1076 .Vb 7
1077 \&    [% META
1078 \&       title     = 'The Foo Page'
1079 \&       author    = 'Fred Foo'
1080 \&       copyright = '2000 Fred Foo'
1081 \&    %]
1082 \&    <h1>[% template.title %]</h1>
1083 \&    Welcome to the Foo Page, blah blah blah
1084 .Ve
1085 .PP
1086 output:
1087 .PP
1088 .Vb 13
1089 \&    <html>
1090 \&      <head>
1091 \&        <title>The Foo Page</title>
1092 \&      </head>
1093 \&      <body>
1094 \&    <!\-\- begin content \-\->
1095 \&    <h1>The Foo Page</h1>
1096 \&    Welcome to the Foo Page, blah blah blah
1097 \&    <!\-\- end content \-\->
1098 \&        <hr>
1099 \&        &copy; Copyright 2000 Fred Foo
1100 \&      </body>
1101 \&    </html>
1102 .Ve
1103 .Sh "\s-1WRAPPER\s0"
1104 .IX Subsection "WRAPPER"
1105 The \f(CW\*(C`WRAPPER\*(C'\fR option can be used to specify one or more templates which
1106 should be used to wrap around the output of the main page template.
1107 The main template is processed first (or any \f(CW\*(C`PROCESS\*(C'\fR template(s)) and
1108 the output generated is then passed as the \f(CW\*(C`content\*(C'\fR variable to the
1109 \&\f(CW\*(C`WRAPPER\*(C'\fR template(s) as they are processed.
1110 .PP
1111 .Vb 3
1112 \&    my $template = Template\->new({
1113 \&        WRAPPER => 'wrapper',
1114 \&    };
1115 .Ve
1116 .PP
1117 .Vb 2
1118 \&    # process 'foo' then wrap in 'wrapper'
1119 \&    $template\->process('foo', { message => 'Hello World!' });
1120 .Ve
1121 .PP
1122 wrapper:
1123 .PP
1124 .Vb 3
1125 \&    <wrapper>
1126 \&    [% content %]
1127 \&    </wrapper>
1128 .Ve
1129 .PP
1130 foo:
1131 .PP
1132 .Vb 2
1133 \&    This is the foo file!
1134 \&    Message: [% message %]
1135 .Ve
1136 .PP
1137 The output generated from this example is:
1138 .PP
1139 .Vb 4
1140 \&    <wrapper>
1141 \&    This is the foo file!
1142 \&    Message: Hello World!
1143 \&    </wrapper>
1144 .Ve
1145 .PP
1146 You can specify more than one \f(CW\*(C`WRAPPER\*(C'\fR template by setting the value to
1147 be a reference to a list of templates.  The \f(CW\*(C`WRAPPER\*(C'\fR templates will be
1148 processed in reverse order with the output of each being passed to the
1149 next (or previous, depending on how you look at it) as the 'content'
1150 variable.  It sounds complicated, but the end result is that it just
1151 \&\*(L"Does The Right Thing\*(R" to make wrapper templates nest in the order you
1152 specify.
1153 .PP
1154 .Vb 3
1155 \&    my $template = Template\->new({
1156 \&        WRAPPER => [ 'outer', 'inner' ],
1157 \&    };
1158 .Ve
1159 .PP
1160 .Vb 2
1161 \&    # process 'foo' then wrap in 'inner', then in 'outer'
1162 \&    $template\->process('foo', { message => 'Hello World!' });
1163 .Ve
1164 .PP
1165 outer:
1166 .PP
1167 .Vb 3
1168 \&    <outer>
1169 \&    [% content %]
1170 \&    </outer>
1171 .Ve
1172 .PP
1173 inner:
1174 .PP
1175 .Vb 3
1176 \&    <inner>
1177 \&    [% content %]
1178 \&    </inner>
1179 .Ve
1180 .PP
1181 The output generated is then:
1182 .PP
1183 .Vb 6
1184 \&    <outer>
1185 \&    <inner>
1186 \&    This is the foo file!
1187 \&    Message: Hello World!
1188 \&    </inner>
1189 \&    </outer>
1190 .Ve
1191 .PP
1192 One side-effect of the \*(L"inside\-out\*(R" processing of the \f(CW\*(C`WRAPPER\*(C'\fR
1193 configuration item (and also the \f(CW\*(C`WRAPPER\*(C'\fR directive) is that any
1194 variables set in the template being wrapped will be visible to the
1195 template doing the wrapping, but not the other way around.
1196 .PP
1197 You can use this to good effect in allowing page templates to set
1198 pre-defined values which are then used in the wrapper templates.  For
1199 example, our main page template 'foo' might look like this:
1200 .PP
1201 foo:
1202 .PP
1203 .Vb 6
1204 \&    [% page = {
1205 \&           title    = 'Foo Page'
1206 \&           subtitle = 'Everything There is to Know About Foo'
1207 \&           author   = 'Frank Oliver Octagon'
1208 \&       }
1209 \&    %]
1210 .Ve
1211 .PP
1212 .Vb 4
1213 \&    <p>
1214 \&    Welcome to the page that tells you everything about foo
1215 \&    blah blah blah...
1216 \&    </p>
1217 .Ve
1218 .PP
1219 The \f(CW\*(C`foo\*(C'\fR template is processed before the wrapper template meaning
1220 that the \f(CW\*(C`page\*(C'\fR data structure will be defined for use in the wrapper
1221 template.
1222 .PP
1223 wrapper:
1224 .PP
1225 .Vb 11
1226 \&    <html>
1227 \&      <head>
1228 \&        <title>[% page.title %]</title>
1229 \&      </head>
1230 \&      <body>
1231 \&        <h1>[% page.title %]</h1>
1232 \&        <h2>[% page.subtitle %]</h1>
1233 \&        <h3>by [% page.author %]</h3>
1234 \&        [% content %]
1235 \&      </body>
1236 \&    </html>
1237 .Ve
1238 .PP
1239 It achieves the same effect as defining \f(CW\*(C`META\*(C'\fR items which are then
1240 accessed via the \f(CW\*(C`template\*(C'\fR variable (which you are still free to
1241 use within \f(CW\*(C`WRAPPER\*(C'\fR templates), but gives you more flexibility in
1242 the type and complexity of data that you can define.
1243 .Sh "\s-1ERROR\s0"
1244 .IX Subsection "ERROR"
1245 The \f(CW\*(C`ERROR\*(C'\fR (or \f(CW\*(C`ERRORS\*(C'\fR if you prefer) configuration item can be used to
1246 name a single template or specify a hash array mapping exception types
1247 to templates which should be used for error handling.  If an uncaught
1248 exception is raised from within a template then the appropriate error
1249 template will instead be processed.
1250 .PP
1251 If specified as a single value then that template will be processed
1252 for all uncaught exceptions.
1253 .PP
1254 .Vb 3
1255 \&    my $template = Template\->new({
1256 \&        ERROR => 'error.html'
1257 \&    });
1258 .Ve
1259 .PP
1260 If the \f(CW\*(C`ERROR\*(C'\fR item is a hash reference the keys are assumed to be
1261 exception types and the relevant template for a given exception will
1262 be selected.  A \f(CW\*(C`default\*(C'\fR template may be provided for the general
1263 case.  Note that \f(CW\*(C`ERROR\*(C'\fR can be pluralised to \f(CW\*(C`ERRORS\*(C'\fR if you find
1264 it more appropriate in this case.
1265 .PP
1266 .Vb 7
1267 \&    my $template = Template\->new({
1268 \&        ERRORS => {
1269 \&            user     => 'user/index.html',
1270 \&            dbi      => 'error/database',
1271 \&            default  => 'error/default',
1272 \&        },
1273 \&    });
1274 .Ve
1275 .PP
1276 In this example, any \f(CW\*(C`user\*(C'\fR exceptions thrown will cause the
1277 \&\fIuser/index.html\fR template to be processed, \f(CW\*(C`dbi\*(C'\fR errors are handled
1278 by \fIerror/database\fR and all others by the \fIerror/default\fR template.
1279 Any \f(CW\*(C`PRE_PROCESS\*(C'\fR and/or \f(CW\*(C`POST_PROCESS\*(C'\fR templates will also be applied
1280 to these error templates.
1281 .PP
1282 Note that exception types are hierarchical and a \f(CW\*(C`foo\*(C'\fR handler will
1283 catch all \f(CW\*(C`foo.*\*(C'\fR errors (e.g. \f(CW\*(C`foo.bar\*(C'\fR, \f(CW\*(C`foo.bar.baz\*(C'\fR) if a more
1284 specific handler isn't defined.  Be sure to quote any exception types
1285 that contain periods to prevent Perl concatenating them into a single
1286 string (i.e. \f(CW\*(C`user.passwd\*(C'\fR is parsed as \f(CW'user'.'passwd'\fR).
1287 .PP
1288 .Vb 8
1289 \&    my $template = Template\->new({
1290 \&        ERROR => {
1291 \&            'user.login'  => 'user/login.html',
1292 \&            'user.passwd' => 'user/badpasswd.html',
1293 \&            'user'        => 'user/index.html',
1294 \&            'default'     => 'error/default',
1295 \&        },
1296 \&    });
1297 .Ve
1298 .PP
1299 In this example, any template processed by the \f(CW$template\fR object, or
1300 other templates or code called from within, can raise a \f(CW\*(C`user.login\*(C'\fR
1301 exception and have the service redirect to the \fIuser/login.html\fR
1302 template.  Similarly, a \f(CW\*(C`user.passwd\*(C'\fR exception has a specific
1303 handling template, \fIuser/badpasswd.html\fR, while all other \f(CW\*(C`user\*(C'\fR or
1304 \&\f(CW\*(C`user.*\*(C'\fR exceptions cause a redirection to the \fIuser/index.html\fR page.
1305 All other exception types are handled by \fIerror/default\fR.
1306 .PP
1307 Exceptions can be raised in a template using the \f(CW\*(C`THROW\*(C'\fR directive,
1308 .PP
1309 .Vb 1
1310 \&    [% THROW user.login 'no user id: please login' %]
1311 .Ve
1312 .PP
1313 or by calling the \fIthrow()\fR method on the
1314 current Template::Context object,
1315 .PP
1316 .Vb 2
1317 \&    $context\->throw('user.passwd', 'Incorrect Password');
1318 \&    $context\->throw('Incorrect Password');    # type 'undef'
1319 .Ve
1320 .PP
1321 or from Perl code by calling \f(CW\*(C`die()\*(C'\fR with a Template::Exception object,
1322 .PP
1323 .Vb 1
1324 \&    die (Template::Exception\->new('user.denied', 'Invalid User ID'));
1325 .Ve
1326 .PP
1327 or by simply calling \fIdie()\fR with an error string.  This is
1328 automagically caught and converted to an  exception of '\f(CW\*(C`undef\*(C'\fR'
1329 type which can then be handled in the usual way.
1330 .PP
1331 .Vb 1
1332 \&    die "I'm sorry Dave, I can't do that";
1333 .Ve
1334 .PP
1335 Note that the '\f(CW\*(C`undef\*(C'\fR' we're talking about here is a literal string
1336 rather than Perl's \f(CW\*(C`undef\*(C'\fR used to represent undefined values.
1337 .SH "Template Runtime Options"
1338 .IX Header "Template Runtime Options"
1339 .Sh "\s-1EVAL_PERL\s0"
1340 .IX Subsection "EVAL_PERL"
1341 This flag is used to indicate if \f(CW\*(C`PERL\*(C'\fR and/or \f(CW\*(C`RAWPERL\*(C'\fR blocks should be
1342 evaluated.  It is disabled by default and any \f(CW\*(C`PERL\*(C'\fR or \f(CW\*(C`RAWPERL\*(C'\fR blocks
1343 encountered will raise exceptions of type '\f(CW\*(C`perl\*(C'\fR' with the message
1344 \&'\f(CW\*(C`EVAL_PERL not set\*(C'\fR'.  Note however that any \f(CW\*(C`RAWPERL\*(C'\fR blocks should
1345 always contain valid Perl code, regardless of the \f(CW\*(C`EVAL_PERL\*(C'\fR flag.  The
1346 parser will fail to compile templates that contain invalid Perl code
1347 in \f(CW\*(C`RAWPERL\*(C'\fR blocks and will throw a '\f(CW\*(C`file\*(C'\fR' exception.
1348 .PP
1349 When using compiled templates (see
1350 \&\*(L"Caching and Compiling Options\*(R"),
1351 the \f(CW\*(C`EVAL_PERL\*(C'\fR has an affect when the template is compiled, and again
1352 when the templates is subsequently processed, possibly in a different
1353 context to the one that compiled it.
1354 .PP
1355 If the \f(CW\*(C`EVAL_PERL\*(C'\fR is set when a template is compiled, then all \f(CW\*(C`PERL\*(C'\fR and
1356 \&\f(CW\*(C`RAWPERL\*(C'\fR blocks will be included in the compiled template.  If the
1357 \&\f(CW\*(C`EVAL_PERL\*(C'\fR option isn't set, then Perl code will be generated which
1358 \&\fBalways\fR throws a '\f(CW\*(C`perl\*(C'\fR' exception with the message '\f(CW\*(C`EVAL_PERL not
1359 set\*(C'\fR' \fBwhenever\fR the compiled template code is run.
1360 .PP
1361 Thus, you must have \f(CW\*(C`EVAL_PERL\*(C'\fR set if you want your compiled templates
1362 to include \f(CW\*(C`PERL\*(C'\fR and \f(CW\*(C`RAWPERL\*(C'\fR blocks.
1363 .PP
1364 At some point in the future, using a different invocation of the
1365 Template Toolkit, you may come to process such a pre-compiled
1366 template.  Assuming the \f(CW\*(C`EVAL_PERL\*(C'\fR option was set at the time the
1367 template was compiled, then the output of any \f(CW\*(C`RAWPERL\*(C'\fR blocks will be
1368 included in the compiled template and will get executed when the
1369 template is processed.  This will happen regardless of the runtime
1370 \&\f(CW\*(C`EVAL_PERL\*(C'\fR status.
1371 .PP
1372 Regular \f(CW\*(C`PERL\*(C'\fR blocks are a little more cautious, however.  If the
1373 \&\f(CW\*(C`EVAL_PERL\*(C'\fR flag isn't set for the \fIcurrent\fR context, that is, the
1374 one which is trying to process it, then it will throw the familiar '\f(CW\*(C`perl\*(C'\fR'
1375 exception with the message, '\f(CW\*(C`EVAL_PERL not set\*(C'\fR'.
1376 .PP
1377 Thus you can compile templates to include \f(CW\*(C`PERL\*(C'\fR blocks, but optionally
1378 disable them when you process them later.  Note however that it is
1379 possible for a \f(CW\*(C`PERL\*(C'\fR block to contain a Perl "\f(CW\*(C`BEGIN { # some code }\*(C'\fR"
1380 block which will always get run regardless of the runtime \f(CW\*(C`EVAL_PERL\*(C'\fR
1381 status.  Thus, if you set \f(CW\*(C`EVAL_PERL\*(C'\fR when compiling templates, it is
1382 assumed that you trust the templates to Do The Right Thing.  Otherwise
1383 you must accept the fact that there's no bulletproof way to prevent
1384 any included code from trampling around in the living room of the
1385 runtime environment, making a real nuisance of itself if it really
1386 wants to.  If you don't like the idea of such uninvited guests causing
1387 a bother, then you can accept the default and keep \f(CW\*(C`EVAL_PERL\*(C'\fR disabled.
1388 .Sh "\s-1OUTPUT\s0"
1389 .IX Subsection "OUTPUT"
1390 Default output location or handler.  This may be specified as one of:
1391 a file name (relative to \f(CW\*(C`OUTPUT_PATH\*(C'\fR, if defined, or the current
1392 working directory if not specified absolutely); a file handle
1393 (e.g. \f(CW\*(C`GLOB\*(C'\fR or IO::Handle) opened for writing; a reference to a text
1394 string to which the output is appended (the string isn't cleared); a
1395 reference to a subroutine which is called, passing the output text as
1396 an argument; as a reference to an array, onto which the content will be
1397 \&\f(CW\*(C`push()\*(C'\fRed; or as a reference to any object that supports the \f(CW\*(C`print()\*(C'\fR
1398 method.  This latter option includes the \f(CW\*(C`Apache::Request\*(C'\fR object which
1399 is passed as the argument to Apache/mod_perl handlers.
1400 .PP
1401 example 1 (file name):
1402 .PP
1403 .Vb 3
1404 \&    my $template = Template\->new({
1405 \&        OUTPUT => "/tmp/foo",
1406 \&    });
1407 .Ve
1408 .PP
1409 example 2 (text string):
1410 .PP
1411 .Vb 4
1412 \&    my $output   = '';
1413 \&    my $template = Template\->new({
1414 \&        OUTPUT => \e$output,
1415 \&    });
1416 .Ve
1417 .PP
1418 example 3 (file handle):
1419 .PP
1420 .Vb 4
1421 \&    open (TOUT, "> $file") || die "$file: $!\en";
1422 \&    my $template = Template\->new({
1423 \&        OUTPUT => \e*TOUT,
1424 \&    });
1425 .Ve
1426 .PP
1427 example 4 (subroutine):
1428 .PP
1429 .Vb 4
1430 \&    sub output { my $out = shift; print "OUTPUT: $out" }
1431 \&    my $template = Template\->new({
1432 \&        OUTPUT => \e&output,
1433 \&    });
1434 .Ve
1435 .PP
1436 example 5 (array reference):
1437 .PP
1438 .Vb 3
1439 \&    my $template = Template\->new({
1440 \&        OUTPUT => \e@output,
1441 \&    })
1442 .Ve
1443 .PP
1444 example 6 (Apache/mod_perl handler):
1445 .PP
1446 .Vb 7
1447 \&    sub handler {
1448 \&        my $r = shift;
1449 \&        my $t = Template\->new({
1450 \&            OUTPUT => $r,
1451 \&        });
1452 \&        ...
1453 \&    }
1454 .Ve
1455 .PP
1456 The default \f(CW\*(C`OUTPUT\*(C'\fR location be overridden by passing a third parameter to
1457 the Template \fIprocess()\fR method. This can be specified
1458 as any of the above argument types.
1459 .PP
1460 .Vb 6
1461 \&    $t\->process($file, $vars, "/tmp/foo");
1462 \&    $t\->process($file, $vars, \e$output);
1463 \&    $t\->process($file, $vars, \e*MYGLOB);
1464 \&    $t\->process($file, $vars, \e@output);
1465 \&    $t\->process($file, $vars, $r);  # Apache::Request
1466 \&    ...
1467 .Ve
1468 .Sh "\s-1OUTPUT_PATH\s0"
1469 .IX Subsection "OUTPUT_PATH"
1470 The \f(CW\*(C`OUTPUT_PATH\*(C'\fR allows a directory to be specified into which output
1471 files should be written.  An output file can be specified by the
1472 \&\f(CW\*(C`OUTPUT\*(C'\fR option, or passed by name as the third parameter to the
1473 Template \fIprocess()\fR method.
1474 .PP
1475 .Vb 4
1476 \&    my $template = Template\->new({
1477 \&        INCLUDE_PATH => "/tmp/src",
1478 \&        OUTPUT_PATH  => "/tmp/dest",
1479 \&    });
1480 .Ve
1481 .PP
1482 .Vb 3
1483 \&    my $vars = {
1484 \&        ...
1485 \&    };
1486 .Ve
1487 .PP
1488 .Vb 4
1489 \&    foreach my $file ('foo.html', 'bar.html') {
1490 \&        $template\->process($file, $vars, $file)
1491 \&            || die $template\->error();
1492 \&    }
1493 .Ve
1494 .PP
1495 This example will read the input files \fI/tmp/src/foo.html\fR and
1496 \&\fI/tmp/src/bar.html\fR and write the processed output to \fI/tmp/dest/foo.html\fR
1497 and \fI/tmp/dest/bar.html\fR, respectively.
1498 .Sh "\s-1STRICT\s0"
1499 .IX Subsection "STRICT"
1500 By default the Template Toolkit will silently ignore the use of undefined
1501 variables (a bad design decision that I regret).
1502 .PP
1503 When the \f(CW\*(C`STRICT\*(C'\fR option is set, the use of any undefined variables or
1504 values will cause an exception to be throw.  The exception will have a
1505 \&\f(CW\*(C`type\*(C'\fR of \f(CW\*(C`var.undefined\*(C'\fR and a message of the form
1506 \&\*(L"undefined variable: xxx\*(R".
1507 .PP
1508 .Vb 3
1509 \&    my $template = Template\->new(
1510 \&        STRICT => 1
1511 \&    );
1512 .Ve
1513 .Sh "\s-1DEBUG\s0"
1514 .IX Subsection "DEBUG"
1515 The \f(CW\*(C`DEBUG\*(C'\fR option can be used to enable debugging within the various
1516 different modules that comprise the Template Toolkit.  The
1517 Template::Constants module defines a set of
1518 \&\f(CW\*(C`DEBUG_XXXX\*(C'\fR constants which can be combined using the logical \s-1OR\s0
1519 operator, '\f(CW\*(C`|\*(C'\fR'.
1520 .PP
1521 .Vb 1
1522 \&    use Template::Constants qw( :debug );
1523 .Ve
1524 .PP
1525 .Vb 3
1526 \&    my $template = Template\->new({
1527 \&        DEBUG => DEBUG_PARSER | DEBUG_PROVIDER,
1528 \&    });
1529 .Ve
1530 .PP
1531 For convenience, you can also provide a string containing a list
1532 of lower case debug options, separated by any non-word characters.
1533 .PP
1534 .Vb 3
1535 \&    my $template = Template\->new({
1536 \&        DEBUG => 'parser, provider',
1537 \&    });
1538 .Ve
1539 .PP
1540 The following \f(CW\*(C`DEBUG_XXXX\*(C'\fR flags can be used:
1541 .IP "\s-1DEBUG_SERVICE\s0" 4
1542 .IX Item "DEBUG_SERVICE"
1543 Enables general debugging messages for the
1544 Template::Service module.
1545 .IP "\s-1DEBUG_CONTEXT\s0" 4
1546 .IX Item "DEBUG_CONTEXT"
1547 Enables general debugging messages for the
1548 Template::Context module.
1549 .IP "\s-1DEBUG_PROVIDER\s0" 4
1550 .IX Item "DEBUG_PROVIDER"
1551 Enables general debugging messages for the
1552 Template::Provider module.
1553 .IP "\s-1DEBUG_PLUGINS\s0" 4
1554 .IX Item "DEBUG_PLUGINS"
1555 Enables general debugging messages for the
1556 Template::Plugins module.
1557 .IP "\s-1DEBUG_FILTERS\s0" 4
1558 .IX Item "DEBUG_FILTERS"
1559 Enables general debugging messages for the
1560 Template::Filters module.
1561 .IP "\s-1DEBUG_PARSER\s0" 4
1562 .IX Item "DEBUG_PARSER"
1563 This flag causes the Template::Parser to generate
1564 debugging messages that show the Perl code generated by parsing and
1565 compiling each template.
1566 .IP "\s-1DEBUG_UNDEF\s0" 4
1567 .IX Item "DEBUG_UNDEF"
1568 This option causes the Template Toolkit to throw an '\f(CW\*(C`undef\*(C'\fR' error
1569 whenever it encounters an undefined variable value.
1570 .IP "\s-1DEBUG_DIRS\s0" 4
1571 .IX Item "DEBUG_DIRS"
1572 This option causes the Template Toolkit to generate comments
1573 indicating the source file, line and original text of each directive
1574 in the template.  These comments are embedded in the template output
1575 using the format defined in the \f(CW\*(C`DEBUG_FORMAT\*(C'\fR configuration item, or a
1576 simple default format if unspecified.
1577 .Sp
1578 For example, the following template fragment:
1579 .Sp
1580 .Vb 1
1581 \&    Hello World
1582 .Ve
1583 .Sp
1584 would generate this output:
1585 .Sp
1586 .Vb 4
1587 \&    ## input text line 1 :  ##
1588 \&    Hello
1589 \&    ## input text line 2 : World ##
1590 \&    World
1591 .Ve
1592 .IP "\s-1DEBUG_ALL\s0" 4
1593 .IX Item "DEBUG_ALL"
1594 Enables all debugging messages.
1595 .IP "\s-1DEBUG_CALLER\s0" 4
1596 .IX Item "DEBUG_CALLER"
1597 This option causes all debug messages that aren't newline terminated
1598 to have the file name and line number of the caller appended to them.
1599 .Sh "\s-1DEBUG_FORMAT\s0"
1600 .IX Subsection "DEBUG_FORMAT"
1601 The \f(CW\*(C`DEBUG_FORMAT\*(C'\fR option can be used to specify a format string for the
1602 debugging messages generated via the \f(CW\*(C`DEBUG_DIRS\*(C'\fR option described
1603 above.  Any occurances of \f(CW$file\fR, \f(CW$line\fR or \f(CW$text\fR will be
1604 replaced with the current file name, line or directive text,
1605 respectively.  Notice how the format is single quoted to prevent Perl
1606 from interpolating those tokens as variables.
1607 .PP
1608 .Vb 4
1609 \&    my $template = Template\->new({
1610 \&        DEBUG => 'dirs',
1611 \&        DEBUG_FORMAT => '<!\-\- $file line $line : [% $text %] \-\->',
1612 \&    });
1613 .Ve
1614 .PP
1615 The following template fragment:
1616 .PP
1617 .Vb 2
1618 \&    [% foo = 'World' %]
1619 \&    Hello [% foo %]
1620 .Ve
1621 .PP
1622 would then generate this output:
1623 .PP
1624 .Vb 2
1625 \&    <!\-\- input text line 2 : [% foo = 'World' %] \-\->
1626 \&    Hello <!\-\- input text line 3 : [% foo %] \-\->World
1627 .Ve
1628 .PP
1629 The \s-1DEBUG\s0 directive can also be used to set a debug format within
1630 a template.
1631 .PP
1632 .Vb 1
1633 \&    [% DEBUG format '<!\-\- $file line $line : [% $text %] \-\->' %]
1634 .Ve
1635 .SH "Caching and Compiling Options"
1636 .IX Header "Caching and Compiling Options"
1637 .Sh "\s-1CACHE_SIZE\s0"
1638 .IX Subsection "CACHE_SIZE"
1639 The Template::Provider module caches compiled templates to avoid the need
1640 to re-parse template files or blocks each time they are used. The \f(CW\*(C`CACHE_SIZE\*(C'\fR
1641 option is used to limit the number of compiled templates that the module
1642 should cache.
1643 .PP
1644 By default, the \f(CW\*(C`CACHE_SIZE\*(C'\fR is undefined and all compiled templates are
1645 cached.  When set to any positive value, the cache will be limited to
1646 storing no more than that number of compiled templates.  When a new
1647 template is loaded and compiled and the cache is full (i.e. the number
1648 of entries == \f(CW\*(C`CACHE_SIZE\*(C'\fR), the least recently used compiled template
1649 is discarded to make room for the new one.
1650 .PP
1651 The \f(CW\*(C`CACHE_SIZE\*(C'\fR can be set to \f(CW0\fR to disable caching altogether.
1652 .PP
1653 .Vb 3
1654 \&    my $template = Template\->new({
1655 \&        CACHE_SIZE => 64,   # only cache 64 compiled templates
1656 \&    });
1657 .Ve
1658 .PP
1659 .Vb 3
1660 \&    my $template = Template\->new({
1661 \&        CACHE_SIZE => 0,   # don't cache any compiled templates
1662 \&    });
1663 .Ve
1664 .PP
1665 As well as caching templates as they are found, the Template::Provider
1666 also implements negative caching to keep track of templates that are
1667 \&\fInot\fR found.  This allows the provider to quickly decline a request
1668 for a template that it has previously failed to locate, saving the effort
1669 of going to look for it again.  This is useful when an \f(CW\*(C`INCLUDE_PATH\*(C'\fR includes
1670 multiple providers, ensuring that the request is passed down through the
1671 providers as quickly as possible.
1672 .Sh "\s-1STAT_TTL\s0"
1673 .IX Subsection "STAT_TTL"
1674 This value can be set to control how long the Template::Provider will keep a
1675 template cached in memory before checking to see if the source template has
1676 changed.
1677 .PP
1678 .Vb 3
1679 \&    my $provider = Template::Provider\->new({
1680 \&        STAT_TTL => 60,  # one minute
1681 \&    });
1682 .Ve
1683 .PP
1684 The default value is 1 (second). You'll probably want to set this to a higher
1685 value if you're running the Template Toolkit inside a persistent web server
1686 application (e.g. mod_perl). For example, set it to 60 and the provider will
1687 only look for changes to templates once a minute at most. However, during
1688 development (or any time you're making frequent changes to templates) you'll
1689 probably want to keep it set to a low value so that you don't have to wait
1690 for the provider to notice that your templates have changed.
1691 .Sh "\s-1COMPILE_EXT\s0"
1692 .IX Subsection "COMPILE_EXT"
1693 From version 2 onwards, the Template Toolkit has the ability to
1694 compile templates to Perl code and save them to disk for subsequent
1695 use (i.e. cache persistence).  The \f(CW\*(C`COMPILE_EXT\*(C'\fR option may be
1696 provided to specify a filename extension for compiled template files.
1697 It is undefined by default and no attempt will be made to read or write
1698 any compiled template files.
1699 .PP
1700 .Vb 3
1701 \&    my $template = Template\->new({
1702 \&        COMPILE_EXT => '.ttc',
1703 \&    });
1704 .Ve
1705 .PP
1706 If \f(CW\*(C`COMPILE_EXT\*(C'\fR is defined (and \f(CW\*(C`COMPILE_DIR\*(C'\fR isn't, see below) then compiled
1707 template files with the \f(CW\*(C`COMPILE_EXT\*(C'\fR extension will be written to the same
1708 directory from which the source template files were loaded.
1709 .PP
1710 Compiling and subsequent reuse of templates happens automatically
1711 whenever the \f(CW\*(C`COMPILE_EXT\*(C'\fR or \f(CW\*(C`COMPILE_DIR\*(C'\fR options are set.  The Template
1712 Toolkit will automatically reload and reuse compiled files when it
1713 finds them on disk.  If the corresponding source file has been modified
1714 since the compiled version as written, then it will load and re-compile
1715 the source and write a new compiled version to disk.
1716 .PP
1717 This form of cache persistence offers significant benefits in terms of
1718 time and resources required to reload templates.  Compiled templates can
1719 be reloaded by a simple call to Perl's \f(CW\*(C`require()\*(C'\fR, leaving Perl to handle
1720 all the parsing and compilation.  This is a Good Thing.
1721 .Sh "\s-1COMPILE_DIR\s0"
1722 .IX Subsection "COMPILE_DIR"
1723 The \f(CW\*(C`COMPILE_DIR\*(C'\fR option is used to specify an alternate directory root
1724 under which compiled template files should be saved.
1725 .PP
1726 .Vb 3
1727 \&    my $template = Template\->new({
1728 \&        COMPILE_DIR => '/tmp/ttc',
1729 \&    });
1730 .Ve
1731 .PP
1732 The \f(CW\*(C`COMPILE_EXT\*(C'\fR option may also be specified to have a consistent file
1733 extension added to these files.
1734 .PP
1735 .Vb 4
1736 \&    my $template1 = Template\->new({
1737 \&        COMPILE_DIR => '/tmp/ttc',
1738 \&        COMPILE_EXT => '.ttc1',
1739 \&    });
1740 .Ve
1741 .PP
1742 .Vb 4
1743 \&    my $template2 = Template\->new({
1744 \&        COMPILE_DIR => '/tmp/ttc',
1745 \&        COMPILE_EXT => '.ttc2',
1746 \&    });
1747 .Ve
1748 .PP
1749 When \f(CW\*(C`COMPILE_EXT\*(C'\fR is undefined, the compiled template files have the
1750 same name as the original template files, but reside in a different
1751 directory tree.
1752 .PP
1753 Each directory in the \f(CW\*(C`INCLUDE_PATH\*(C'\fR is replicated in full beneath the
1754 \&\f(CW\*(C`COMPILE_DIR\*(C'\fR directory.  This example:
1755 .PP
1756 .Vb 4
1757 \&    my $template = Template\->new({
1758 \&        COMPILE_DIR  => '/tmp/ttc',
1759 \&        INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
1760 \&    });
1761 .Ve
1762 .PP
1763 would create the following directory structure:
1764 .PP
1765 .Vb 2
1766 \&    /tmp/ttc/home/abw/templates/
1767 \&    /tmp/ttc/usr/share/templates/
1768 .Ve
1769 .PP
1770 Files loaded from different \f(CW\*(C`INCLUDE_PATH\*(C'\fR directories will have their
1771 compiled forms save in the relevant \f(CW\*(C`COMPILE_DIR\*(C'\fR directory.
1772 .PP
1773 On Win32 platforms a filename may by prefixed by a drive letter and
1774 colon.  e.g.
1775 .PP
1776 .Vb 1
1777 \&    C:/My Templates/header
1778 .Ve
1779 .PP
1780 The colon will be silently stripped from the filename when it is added
1781 to the \f(CW\*(C`COMPILE_DIR\*(C'\fR value(s) to prevent illegal filename being generated.
1782 Any colon in \f(CW\*(C`COMPILE_DIR\*(C'\fR elements will be left intact.  For example:
1783 .PP
1784 .Vb 6
1785 \&    # Win32 only
1786 \&    my $template = Template\->new({
1787 \&        DELIMITER    => ';',
1788 \&        COMPILE_DIR  => 'C:/TT2/Cache',
1789 \&        INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
1790 \&    });
1791 .Ve
1792 .PP
1793 This would create the following cache directories:
1794 .PP
1795 .Vb 2
1796 \&    C:/TT2/Cache/C/TT2/Templates
1797 \&    C:/TT2/Cache/D/My Templates
1798 .Ve
1799 .SH "Plugins and Filters"
1800 .IX Header "Plugins and Filters"
1801 .Sh "\s-1PLUGINS\s0"
1802 .IX Subsection "PLUGINS"
1803 The \f(CW\*(C`PLUGINS\*(C'\fR options can be used to provide a reference to a hash array
1804 that maps plugin names to Perl module names.  A number of standard
1805 plugins are defined (e.g. \f(CW\*(C`table\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`cgi\*(C'\fR, etc.) which map to
1806 their corresponding \f(CW\*(C`Template::Plugin::*\*(C'\fR counterparts.  These can be
1807 redefined by values in the \f(CW\*(C`PLUGINS\*(C'\fR hash.
1808 .PP
1809 .Vb 7
1810 \&    my $template = Template\->new({
1811 \&        PLUGINS => {
1812 \&            cgi => 'MyOrg::Template::Plugin::CGI',
1813 \&            foo => 'MyOrg::Template::Plugin::Foo',
1814 \&            bar => 'MyOrg::Template::Plugin::Bar',
1815 \&        },
1816 \&    });
1817 .Ve
1818 .PP
1819 The recommended convention is to specify these plugin names in lower
1820 case.  The Template Toolkit first looks for an exact case-sensitive
1821 match and then tries the lower case conversion of the name specified.
1822 .PP
1823 .Vb 1
1824 \&    [% USE Foo %]      # look for 'Foo' then 'foo'
1825 .Ve
1826 .PP
1827 If you define all your \f(CW\*(C`PLUGINS\*(C'\fR with lower case names then they will be
1828 located regardless of how the user specifies the name in the \s-1USE\s0
1829 directive.  If, on the other hand, you define your \f(CW\*(C`PLUGINS\*(C'\fR with upper
1830 or mixed case names then the name specified in the \f(CW\*(C`USE\*(C'\fR directive must
1831 match the case exactly.
1832 .PP
1833 The \f(CW\*(C`USE\*(C'\fR directive is used to create plugin objects and does so by calling
1834 the \fIplugin()\fR method on the current
1835 Template::Context object. If the plugin name is defined in the \f(CW\*(C`PLUGINS\*(C'\fR
1836 hash then the corresponding Perl module is loaded via \f(CW\*(C`require()\*(C'\fR. The
1837 context then calls the \fIload()\fR class method which
1838 should return the class name (default and general case) or a prototype object
1839 against which the \fInew()\fR method can be called to
1840 instantiate individual plugin objects.
1841 .PP
1842 If the plugin name is not defined in the \f(CW\*(C`PLUGINS\*(C'\fR hash then the
1843 \&\f(CW\*(C`PLUGIN_BASE\*(C'\fR and/or \f(CW\*(C`LOAD_PERL\*(C'\fR options come into effect.
1844 .Sh "\s-1PLUGIN_BASE\s0"
1845 .IX Subsection "PLUGIN_BASE"
1846 If a plugin is not defined in the \f(CW\*(C`PLUGINS\*(C'\fR hash then the \f(CW\*(C`PLUGIN_BASE\*(C'\fR is used
1847 to attempt to construct a correct Perl module name which can be successfully
1848 loaded.
1849 .PP
1850 The \f(CW\*(C`PLUGIN_BASE\*(C'\fR can be specified as a reference to an array of module
1851 namespaces, or as a single value which is automatically converted to a
1852 list.  The default \f(CW\*(C`PLUGIN_BASE\*(C'\fR value (\f(CW\*(C`Template::Plugin\*(C'\fR) is then added
1853 to the end of this list.
1854 .PP
1855 example 1:
1856 .PP
1857 .Vb 3
1858 \&    my $template = Template\->new({
1859 \&        PLUGIN_BASE => 'MyOrg::Template::Plugin',
1860 \&    });
1861 .Ve
1862 .PP
1863 .Vb 2
1864 \&    [% USE Foo %]    # => MyOrg::Template::Plugin::Foo
1865 \&                       or        Template::Plugin::Foo
1866 .Ve
1867 .PP
1868 example 2:
1869 .PP
1870 .Vb 4
1871 \&    my $template = Template\->new({
1872 \&        PLUGIN_BASE => [   'MyOrg::Template::Plugin',
1873 \&                           'YourOrg::Template::Plugin'  ],
1874 \&    });
1875 .Ve
1876 .PP
1877 template:
1878 .PP
1879 .Vb 3
1880 \&    [% USE Foo %]    # =>   MyOrg::Template::Plugin::Foo
1881 \&                       or YourOrg::Template::Plugin::Foo
1882 \&                       or          Template::Plugin::Foo
1883 .Ve
1884 .PP
1885 If you don't want the default \f(CW\*(C`Template::Plugin\*(C'\fR namespace added to the
1886 end of the \f(CW\*(C`PLUGIN_BASE\*(C'\fR, then set the \f(CW$Template::Plugins::PLUGIN_BASE\fR
1887 variable to a false value before calling the \fInew()\fR Template#\fInew()\fR
1888 constructor method.  This is shown in the example below where the
1889 \&\f(CW\*(C`Foo\*(C'\fR plugin is located as \f(CW\*(C`My::Plugin::Foo\*(C'\fR or \f(CW\*(C`Your::Plugin::Foo\*(C'\fR but not
1890 as \f(CW\*(C`Template::Plugin::Foo\*(C'\fR.
1891 .PP
1892 example 3:
1893 .PP
1894 .Vb 2
1895 \&    use Template::Plugins;
1896 \&    $Template::Plugins::PLUGIN_BASE = '';
1897 .Ve
1898 .PP
1899 .Vb 4
1900 \&    my $template = Template\->new({
1901 \&        PLUGIN_BASE => [   'My::Plugin',
1902 \&                           'Your::Plugin'  ],
1903 \&    });
1904 .Ve
1905 .PP
1906 template:
1907 .PP
1908 .Vb 2
1909 \&    [% USE Foo %]    # =>   My::Plugin::Foo
1910 \&                       or Your::Plugin::Foo
1911 .Ve
1912 .Sh "\s-1LOAD_PERL\s0"
1913 .IX Subsection "LOAD_PERL"
1914 If a plugin cannot be loaded using the \f(CW\*(C`PLUGINS\*(C'\fR or \f(CW\*(C`PLUGIN_BASE\*(C'\fR
1915 approaches then the provider can make a final attempt to load the
1916 module without prepending any prefix to the module path.  This allows
1917 regular Perl modules (i.e. those that don't reside in the
1918 Template::Plugin or some other such namespace) to be loaded and used
1919 as plugins.
1920 .PP
1921 By default, the \f(CW\*(C`LOAD_PERL\*(C'\fR option is set to \f(CW0\fR and no attempt will be made
1922 to load any Perl modules that aren't named explicitly in the \f(CW\*(C`PLUGINS\*(C'\fR
1923 hash or reside in a package as named by one of the \f(CW\*(C`PLUGIN_BASE\*(C'\fR
1924 components.
1925 .PP
1926 Plugins loaded using the \f(CW\*(C`PLUGINS\*(C'\fR or \f(CW\*(C`PLUGIN_BASE\*(C'\fR receive a reference to
1927 the current context object as the first argument to the
1928 \&\fInew()\fR constructor. Modules loaded using \f(CW\*(C`LOAD_PERL\*(C'\fR
1929 are assumed to not conform to the plugin interface. They must provide a \f(CW\*(C`new()\*(C'\fR
1930 class method for instantiating objects but it will not receive a reference to
1931 the context as the first argument.
1932 .PP
1933 Plugin modules should provide a \fIload()\fR class method
1934 (or inherit the default one from the Template::Plugin base class) which is
1935 called the first time the plugin is loaded. Regular Perl modules need not. In
1936 all other respects, regular Perl objects and Template Toolkit plugins are
1937 identical.
1938 .PP
1939 If a particular Perl module does not conform to the common, but not
1940 unilateral, \f(CW\*(C`new()\*(C'\fR constructor convention then a simple plugin wrapper
1941 can be written to interface to it.
1942 .Sh "\s-1FILTERS\s0"
1943 .IX Subsection "FILTERS"
1944 The \f(CW\*(C`FILTERS\*(C'\fR option can be used to specify custom filters which can
1945 then be used with the \f(CW\*(C`FILTER\*(C'\fR directive like any other.  These are
1946 added to the standard filters which are available by default.  Filters
1947 specified via this option will mask any standard filters of the same
1948 name.
1949 .PP
1950 The \f(CW\*(C`FILTERS\*(C'\fR option should be specified as a reference to a hash array
1951 in which each key represents the name of a filter.  The corresponding
1952 value should contain a reference to an array containing a subroutine
1953 reference and a flag which indicates if the filter is static (\f(CW0\fR) or
1954 dynamic (\f(CW1\fR).  A filter may also be specified as a solitary subroutine
1955 reference and is assumed to be static.
1956 .PP
1957 .Vb 7
1958 \&    $template = Template\->new({
1959 \&        FILTERS => {
1960 \&            'sfilt1' =>   \e&static_filter,      # static
1961 \&            'sfilt2' => [ \e&static_filter, 0 ], # same as above
1962 \&            'dfilt1' => [ \e&dyanamic_filter_factory, 1 ],
1963 \&        },
1964 \&    });
1965 .Ve
1966 .PP
1967 Additional filters can be specified at any time by calling the
1968 \&\fIdefine_filter()\fR method on the current
1969 Template::Context object. The method accepts a filter name, a reference to a
1970 filter subroutine and an optional flag to indicate if the filter is dynamic.
1971 .PP
1972 .Vb 3
1973 \&    my $context = $template\->context();
1974 \&    $context\->define_filter('new_html', \e&new_html);
1975 \&    $context\->define_filter('new_repeat', \e&new_repeat, 1);
1976 .Ve
1977 .PP
1978 Static filters are those where a single subroutine reference is used
1979 for all invocations of a particular filter.  Filters that don't accept
1980 any configuration parameters (e.g. \f(CW\*(C`html\*(C'\fR) can be implemented
1981 statically.  The subroutine reference is simply returned when that
1982 particular filter is requested.  The subroutine is called to filter
1983 the output of a template block which is passed as the only argument.
1984 The subroutine should return the modified text.
1985 .PP
1986 .Vb 5
1987 \&    sub static_filter {
1988 \&        my $text = shift;
1989 \&        # do something to modify $text...
1990 \&        return $text;
1991 \&    }
1992 .Ve
1993 .PP
1994 The following template fragment:
1995 .PP
1996 .Vb 3
1997 \&    [% FILTER sfilt1 %]
1998 \&    Blah blah blah.
1999 \&    [% END %]
2000 .Ve
2001 .PP
2002 is approximately equivalent to:
2003 .PP
2004 .Vb 1
2005 \&    &static_filter("\enBlah blah blah.\en");
2006 .Ve
2007 .PP
2008 Filters that can accept parameters (e.g. \f(CW\*(C`truncate\*(C'\fR) should be
2009 implemented dynamically.  In this case, the subroutine is taken to be
2010 a filter 'factory' that is called to create a unique filter subroutine
2011 each time one is requested.  A reference to the current
2012 Template::Context object is passed as the first parameter, followed by
2013 any additional parameters specified.  The subroutine should return
2014 another subroutine reference (usually a closure) which implements the
2015 filter.
2016 .PP
2017 .Vb 2
2018 \&    sub dynamic_filter_factory {
2019 \&        my ($context, @args) = @_;
2020 .Ve
2021 .PP
2022 .Vb 6
2023 \&        return sub {
2024 \&            my $text = shift;
2025 \&            # do something to modify $text...
2026 \&            return $text;
2027 \&        }
2028 \&    }
2029 .Ve
2030 .PP
2031 The following template fragment:
2032 .PP
2033 .Vb 3
2034 \&    [% FILTER dfilt1(123, 456) %]
2035 \&    Blah blah blah
2036 \&    [% END %]
2037 .Ve
2038 .PP
2039 is approximately equivalent to:
2040 .PP
2041 .Vb 2
2042 \&    my $filter = &dynamic_filter_factory($context, 123, 456);
2043 \&    &$filter("\enBlah blah blah.\en");
2044 .Ve
2045 .PP
2046 See the \f(CW\*(C`FILTER\*(C'\fR directive for further examples.
2047 .SH "Customisation and Extension"
2048 .IX Header "Customisation and Extension"
2049 .Sh "\s-1LOAD_TEMPLATES\s0"
2050 .IX Subsection "LOAD_TEMPLATES"
2051 The \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR option can be used to provide a reference to a list
2052 of Template::Provider objects or sub-classes thereof which will take
2053 responsibility for loading and compiling templates.
2054 .PP
2055 .Vb 6
2056 \&    my $template = Template\->new({
2057 \&        LOAD_TEMPLATES => [
2058 \&            MyOrg::Template::Provider\->new({ ... }),
2059 \&            Template::Provider\->new({ ... }),
2060 \&        ],
2061 \&    });
2062 .Ve
2063 .PP
2064 When a \f(CW\*(C`PROCESS\*(C'\fR, \f(CW\*(C`INCLUDE\*(C'\fR or \f(CW\*(C`WRAPPER\*(C'\fR directive is encountered, the
2065 named template may refer to a locally defined \f(CW\*(C`BLOCK\*(C'\fR or a file relative to
2066 the \f(CW\*(C`INCLUDE_PATH\*(C'\fR (or an absolute or relative path if the appropriate
2067 \&\f(CW\*(C`ABSOLUTE\*(C'\fR or \f(CW\*(C`RELATIVE\*(C'\fR options are set). If a \f(CW\*(C`BLOCK\*(C'\fR definition can't be
2068 found (see the Template::Context \fItemplate()\fR
2069 method for a discussion of \f(CW\*(C`BLOCK\*(C'\fR locality) then each of the
2070 \&\f(CW\*(C`LOAD_TEMPLATES\*(C'\fR provider objects is queried in turn via the
2071 \&\fIfetch()\fR method to see if it can supply the
2072 required template.
2073 .PP
2074 Each provider can return a compiled template, an error, or decline to service
2075 the request in which case the responsibility is passed to the next provider.
2076 If none of the providers can service the request then a 'not found' error is
2077 returned. The same basic provider mechanism is also used for the \f(CW\*(C`INSERT\*(C'\fR
2078 directive but it bypasses any \f(CW\*(C`BLOCK\*(C'\fR definitions and doesn't attempt is to
2079 parse or process the contents of the template file.
2080 .PP
2081 If \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR is undefined, a single default provider will be
2082 instantiated using the current configuration parameters. For example, the
2083 Template::Provider \f(CW\*(C`INCLUDE_PATH\*(C'\fR option can be specified in the Template
2084 configuration and will be correctly passed to the provider's constructor
2085 method.
2086 .PP
2087 .Vb 3
2088 \&    my $template = Template\->new({
2089 \&        INCLUDE_PATH => '/here:/there',
2090 \&    });
2091 .Ve
2092 .Sh "\s-1LOAD_PLUGINS\s0"
2093 .IX Subsection "LOAD_PLUGINS"
2094 The \f(CW\*(C`LOAD_PLUGINS\*(C'\fR options can be used to specify a list of provider objects
2095 (i.e. they implement the \fIfetch()\fR method) which
2096 are responsible for loading and instantiating template plugin objects. The
2097 Template::Context \fIplugin()\fR method queries
2098 each provider in turn in a \*(L"Chain of Responsibility\*(R" as per the
2099 \&\fItemplate()\fR and
2100 \&\fIfilter()\fR methods.
2101 .PP
2102 .Vb 6
2103 \&    my $template = Template\->new({
2104 \&        LOAD_PLUGINS => [
2105 \&            MyOrg::Template::Plugins\->new({ ... }),
2106 \&            Template::Plugins\->new({ ... }),
2107 \&        ],
2108 \&    });
2109 .Ve
2110 .PP
2111 By default, a single Template::Plugins object is created using the
2112 current configuration hash.  Configuration items destined for the
2113 Template::Plugins constructor may be added to the Template
2114 constructor.
2115 .PP
2116 .Vb 4
2117 \&    my $template = Template\->new({
2118 \&        PLUGIN_BASE => 'MyOrg::Template::Plugins',
2119 \&        LOAD_PERL   => 1,
2120 \&    });
2121 .Ve
2122 .Sh "\s-1LOAD_FILTERS\s0"
2123 .IX Subsection "LOAD_FILTERS"
2124 The \f(CW\*(C`LOAD_FILTERS\*(C'\fR option can be used to specify a list of provider objects
2125 (i.e. they implement the \fIfetch()\fR method) which
2126 are responsible for returning and/or creating filter subroutines. The
2127 Template::Context \fIfilter()\fR method queries
2128 each provider in turn in a \*(L"Chain of Responsibility\*(R" as per the
2129 \&\fItemplate()\fR and
2130 \&\fIplugin()\fR methods.
2131 .PP
2132 .Vb 6
2133 \&    my $template = Template\->new({
2134 \&        LOAD_FILTERS => [
2135 \&            MyTemplate::Filters\->new(),
2136 \&            Template::Filters\->new(),
2137 \&        ],
2138 \&    });
2139 .Ve
2140 .PP
2141 By default, a single Template::Filters object is created for the
2142 \&\f(CW\*(C`LOAD_FILTERS\*(C'\fR list.
2143 .Sh "\s-1TOLERANT\s0"
2144 .IX Subsection "TOLERANT"
2145 The \f(CW\*(C`TOLERANT\*(C'\fR flag is used by the various Template Toolkit provider modules
2146 (Template::Provider, Template::Plugins, Template::Filters) to control
2147 their behaviour when errors are encountered. By default, any errors are
2148 reported as such, with the request for the particular resource (\f(CW\*(C`template\*(C'\fR,
2149 \&\f(CW\*(C`plugin\*(C'\fR, \f(CW\*(C`filter\*(C'\fR) being denied and an exception raised.
2150 .PP
2151 When the \f(CW\*(C`TOLERANT\*(C'\fR flag is set to any true values, errors will be silently
2152 ignored and the provider will instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR. This allows a
2153 subsequent provider to take responsibility for providing the resource, rather
2154 than failing the request outright. If all providers decline to service the
2155 request, either through tolerated failure or a genuine disinclination to
2156 comply, then a '\f(CW\*(C`<resource> not found\*(C'\fR' exception is raised.
2157 .Sh "\s-1SERVICE\s0"
2158 .IX Subsection "SERVICE"
2159 A reference to a Template::Service object, or sub-class thereof, to which
2160 the Template module should delegate.  If unspecified, a Template::Service
2161 object is automatically created using the current configuration hash.
2162 .PP
2163 .Vb 3
2164 \&    my $template = Template\->new({
2165 \&        SERVICE => MyOrg::Template::Service\->new({ ... }),
2166 \&    });
2167 .Ve
2168 .Sh "\s-1CONTEXT\s0"
2169 .IX Subsection "CONTEXT"
2170 A reference to a Template::Context object which is used to define a
2171 specific environment in which template are processed. A Template::Context
2172 object is passed as the only parameter to the Perl subroutines that represent
2173 \&\*(L"compiled\*(R" template documents. Template subroutines make callbacks into the
2174 context object to access Template Toolkit functionality, for example, to to
2175 \&\f(CW\*(C`INCLUDE\*(C'\fR or \f(CW\*(C`PROCESS\*(C'\fR another template
2176 (\fIinclude()\fR and
2177 \&\fIprocess()\fR methods, respectively), to \f(CW\*(C`USE\*(C'\fR a
2178 plugin (\fIplugin()\fR) or instantiate a filter
2179 (\fIfilter()\fR) or to access the stash
2180 (\fIstash()\fR) which manages variable definitions via
2181 the \fIget()\fR and \fIset()\fR methods.
2182 .PP
2183 .Vb 3
2184 \&    my $template = Template\->new({
2185 \&        CONTEXT => MyOrg::Template::Context\->new({ ... }),
2186 \&    });
2187 .Ve
2188 .Sh "\s-1STASH\s0"
2189 .IX Subsection "STASH"
2190 A reference to a Template::Stash object or sub-class which will take
2191 responsibility for managing template variables.
2192 .PP
2193 .Vb 4
2194 \&    my $stash = MyOrg::Template::Stash\->new({ ... });
2195 \&    my $template = Template\->new({
2196 \&        STASH => $stash,
2197 \&    });
2198 .Ve
2199 .PP
2200 If unspecified, a default stash object is created using the \f(CW\*(C`VARIABLES\*(C'\fR
2201 configuration item to initialise the stash variables.
2202 .PP
2203 .Vb 6
2204 \&    my $template = Template\->new({
2205 \&        VARIABLES => {
2206 \&            id    => 'abw',
2207 \&            name  => 'Andy Wardley',
2208 \&        },
2209 \&    };
2210 .Ve
2211 .Sh "\s-1PARSER\s0"
2212 .IX Subsection "PARSER"
2213 The Template::Parser module implements a parser object for compiling
2214 templates into Perl code which can then be executed.  A default object
2215 of this class is created automatically and then used by the
2216 Template::Provider whenever a template is loaded and requires
2217 compilation.  The \f(CW\*(C`PARSER\*(C'\fR option can be used to provide a reference to
2218 an alternate parser object.
2219 .PP
2220 .Vb 3
2221 \&    my $template = Template\->new({
2222 \&        PARSER => MyOrg::Template::Parser\->new({ ... }),
2223 \&    });
2224 .Ve
2225 .Sh "\s-1GRAMMAR\s0"
2226 .IX Subsection "GRAMMAR"
2227 The \f(CW\*(C`GRAMMAR\*(C'\fR configuration item can be used to specify an alternate
2228 grammar for the parser.  This allows a modified or entirely new
2229 template language to be constructed and used by the Template Toolkit.
2230 .PP
2231 Source templates are compiled to Perl code by the Template::Parser
2232 using the Template::Grammar (by default) to define the language
2233 structure and semantics.  Compiled templates are thus inherently
2234 \&\*(L"compatible\*(R" with each other and there is nothing to prevent any
2235 number of different template languages being compiled and used within
2236 the same Template Toolkit processing environment (other than the usual
2237 time and memory constraints).
2238 .PP
2239 The Template::Grammar file is constructed from a \s-1YACC\s0 like grammar
2240 (using \f(CW\*(C`Parse::YAPP\*(C'\fR) and a skeleton module template.  These files are
2241 provided, along with a small script to rebuild the grammar, in the
2242 \&\fIparser\fR sub-directory of the distribution.
2243 .PP
2244 You don't have to know or worry about these unless you want to hack on the
2245 template language or define your own variant. There is a \fI\s-1README\s0\fR file in the
2246 same directory which provides some small guidance but it is assumed that you
2247 know what you're doing if you venture herein. If you grok \s-1LALR\s0 parsers, then
2248 you should find it comfortably familiar.
2249 .PP
2250 By default, an instance of the default Template::Grammar will be
2251 created and used automatically if a \f(CW\*(C`GRAMMAR\*(C'\fR item isn't specified.
2252 .PP
2253 .Vb 1
2254 \&    use MyOrg::Template::Grammar;
2255 .Ve
2256 .PP
2257 .Vb 3
2258 \&    my $template = Template\->new({
2259 \&        GRAMMAR = MyOrg::Template::Grammar\->new();
2260 \&    });
2261 .Ve