local-lib5/man/man3/Template::Manual::Internals.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::Internals 3"
 132 .TH Template::Manual::Internals 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Manual::Internals \- Template Toolkit internals
 135 .SH "Introduction"
 136 .IX Header "Introduction"
 137 This section of the documentation is aimed at developers wishing to
 138 know more about how the Template Toolkit works on the inside in order
 139 to extend or adapt it to their own needs.
 140 .PP
 141 If that doesn't sound like you then you probably don't need to read this.
 142 There is no test afterwards.
 143 .SH "Outside Looking In"
 144 .IX Header "Outside Looking In"
 145 The Template module is simply a front end module which creates and
 146 uses a Template::Service and pipes the output wherever you want it to
 147 go (\f(CW\*(C`STDOUT\*(C'\fR by default, or maybe a file, scalar, etc).  The
 148 \&\f(CW\*(C`Apache::Template\*(C'\fR module (available separately from \s-1CPAN\s0) is another
 149 front end.  That creates a \f(CW\*(C`Template::Service::Apache\*(C'\fR object, calls on
 150 it as required and sends the output back to the relevant
 151 \&\f(CW\*(C`Apache::Request\*(C'\fR object.
 152 .PP
 153 These front-end modules are really only there to handle any specifics
 154 of the environment in which they're being used.  The \f(CW\*(C`Apache::Template\*(C'\fR
 155 front end, for example, handles \f(CW\*(C`Apache::Request\*(C'\fR specifics and
 156 configuration via the \fIhttpd.conf\fR.  The regular Template front-end
 157 deals with \f(CW\*(C`STDOUT\*(C'\fR, variable refs, etc.  Otherwise it is
 158 Template::Service (or subclass) which does all the work.
 159 .PP
 160 The Template::Service module provides a high-quality template
 161 delivery service, with bells, whistles, signed up service level
 162 agreement and a 30\-day no quibble money back guarantee.  \*(L"Have
 163 a good time, all the time\*(R", that's our motto.
 164 .PP
 165 Within the lower levels of the Template Toolkit, there are lots of messy
 166 details that we generally don't want to have to worry about most of the time.
 167 Things like templates not being found, or failing to parse correctly, uncaught
 168 exceptions being thrown, missing plugin modules or dependencies, and so on.
 169 Template::Service hides that all away and makes everything look simple to
 170 the outsider. It provides extra features, like \f(CW\*(C`PRE_PROCESS\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR and
 171 \&\f(CW\*(C`POST_PROCESS\*(C'\fR, and also provides the error recovery mechanism via \f(CW\*(C`ERROR\*(C'\fR.
 172 You ask it to process a template and it takes care of everything for you. The
 173 \&\f(CW\*(C`Template::Service::Apache\*(C'\fR module goes a little bit further, adding some extra
 174 headers to the Apache::Request, setting a few extra template variables, and so
 175 on.
 176 .PP
 177 For the most part, the job of a service is really just one of scheduling and
 178 dispatching. It receives a request in the form of a call to its
 179 \&\fIprocess()\fR method and schedules the named
 180 template specified as an argument, and possibly several other templates
 181 (\f(CW\*(C`PRE_PROCESS\*(C'\fR, etc) to be processed in order. It doesn't actually process
 182 the templates itself, but instead makes a
 183 \&\fIprocess()\fR call against a Template::Context
 184 object.
 185 .PP
 186 Template::Context is the runtime engine for the Template Toolkit \-
 187 the module that hangs everything together in the lower levels of the
 188 Template Toolkit and that one that does most of the real work, albeit
 189 by crafty delegation to various other friendly helper modules.
 190 .PP
 191 Given a template name (or perhaps a reference to a scalar or file
 192 handle) the context \fIprocess()\fR method must load and compile, or fetch a
 193 cached copy of a previously compiled template, corresponding to that
 194 name.  It does this by calling on a list of one or more
 195 Template::Provider objects (the \f(CW\*(C`LOAD_TEMPLATES\*(C'\fR posse) who themselves
 196 might get involved with a Template::Parser to help turn source
 197 templates into executable Perl code (but more on that later).
 198 .PP
 199 Thankfully, all of this complexity is hidden away behind a simple
 200 \&\fItemplate()\fR method. You call it passing a
 201 template name as an argument, and it returns a compiled template in the form
 202 of a Template::Document object, or otherwise raises an exception.
 203 .PP
 204 A Template::Document is a thin object wrapper around a compiled template
 205 subroutine. The object implements a \fIprocess()\fR
 206 method which performs a little bit of housekeeping and then calls the template
 207 subroutine. The object also defines template metadata (defined in \f(CW\*(C`[% META
 208 \&... %]\*(C'\fR directives) and has a \fIblock()\fR method
 209 which returns a hash of any additional \f(CW\*(C`[% BLOCK xxxx %]\*(C'\fR definitions found
 210 in the template source.
 211 .PP
 212 So the context fetches a compiled document via its own
 213 \&\fItemplate()\fR method and then gets ready to
 214 process it. It first updates the stash (the place where template variables get
 215 defined \- more on that shortly) to set any template variable definitions
 216 specified as the second argument by reference to hash array. Then, it calls
 217 the document \fIprocess()\fR method, passing a
 218 reference to itself, the context object, as an argument. In doing this, it
 219 provides itself as an object against which template code can make callbacks to
 220 access runtime resources and Template Toolkit functionality.
 221 .PP
 222 What we're trying to say here is this:  not only does the Template::Context
 223 object receive calls from the \fIoutside\fR, i.e. those originating in user
 224 code calling the \fIprocess()\fR method on a Template object, but it also
 225 receives calls from the \fIinside\fR, i.e. those originating in template
 226 directives of the form \f(CW\*(C`[% PROCESS template %]\*(C'\fR.
 227 .PP
 228 Before we move on to that, here's a simple structure diagram showing
 229 the outer layers of the Template Toolkit heading inwards, with pseudo
 230 code annotations showing a typical invocation sequence.
 231 .PP
 232 .Vb 46
 233 \&     ,\-\-\-\-\-\-\-\-.
 234 \&     | Caller |     use Template;
 235 \&     `\-\-\-\-\-\-\-\-'     my $tt = Template\->new( ... );
 236 \&          |         $tt\->process($template, \e%vars);
 237 \&          |                                                     Outside
 238 \&    \- \- \- | \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- \- T T
 239 \&          |         package Template;                            Inside
 240 \&          V
 241 \&    +\-\-\-\-\-\-\-\-\-\-+    sub process($template, \e%vars) {
 242 \&    | Template |        $out = $self\->SERVICE\->process($template, $vars);
 243 \&    +\-\-\-\-\-\-\-\-\-\-+        print $out or send it to $self\->OUTPUT;
 244 \&          |         }
 245 \&          |
 246 \&          |         package Template::Service;
 247 \&          |
 248 \&          |         sub process($template, \e%vars) {
 249 \&          |             try {
 250 \&    +\-\-\-\-\-\-\-\-\-\-+            foreach $p in @self\->PRE_PROCESS
 251 \&    | Service  |                $self\->CONTEXT\->process($p, $vars);
 252 \&    +\-\-\-\-\-\-\-\-\-\-+
 253 \&          |                 $self\->CONTEXT\->process($template, $vars);
 254 \&          |
 255 \&          |                 foreach $p @self\->POST_PROCESS
 256 \&          |                     $self\->CONTEXT\->process($p, $vars);
 257 \&          |             }
 258 \&          |             catch {
 259 \&          |                 $self\->CONTEXT\->process($self\->ERROR);
 260 \&          |             }
 261 \&          |         }
 262 \&          |
 263 \&          V         package Template::Context;
 264 \&    +\-\-\-\-\-\-\-\-\-\-+
 265 \&    | Context  |    sub process($template, \e%vars) {
 266 \&    +\-\-\-\-\-\-\-\-\-\-+        # fetch compiled template
 267 \&          |             $template = $self\->template($template)
 268 \&          |             # update stash
 269 \&          |             $self\->STASH\->update($vars);
 270 \&          |             # process template
 271 \&          |             $template\->process($self)
 272 \&          |         }
 273 \&          V
 274 \&    +\-\-\-\-\-\-\-\-\-\-+    package Template::Document;
 275 \&    | Document |
 276 \&    +\-\-\-\-\-\-\-\-\-\-+    sub process($context) {
 277 \&                        $output = &{ $self\->BLOCK }($context);
 278 \&                    }
 279 .Ve
 280 .SH "Inside Looking Out"
 281 .IX Header "Inside Looking Out"
 282 To understand more about what's going on in these lower levels, we
 283 need to look at what a compiled template looks like.  In fact, a
 284 compiled template is just a regular Perl sub\-routine.  Here's a very
 285 simple one.
 286 .PP
 287 .Vb 3
 288 \&    sub my_compiled_template {
 289 \&        return "This is a compiled template.\en";
 290 \&    }
 291 .Ve
 292 .PP
 293 You're unlikely to see a compiled template this simple unless you
 294 wrote it yourself but it is entirely valid.  All a template subroutine
 295 is obliged to do is return some output (which may be an empty of
 296 course).  If it can't for some reason, then it should raise an error
 297 via \f(CW\*(C`die()\*(C'\fR.
 298 .PP
 299 .Vb 3
 300 \&    sub my_todo_template {
 301 \&        die "This template not yet implemented\en";
 302 \&    }
 303 .Ve
 304 .PP
 305 If it wants to get fancy, it can raise an error as a
 306 Template::Exception object.  An exception object is really just a
 307 convenient wrapper for the '\f(CW\*(C`type\*(C'\fR' and '\f(CW\*(C`info\*(C'\fR' fields.
 308 .PP
 309 .Vb 3
 310 \&    sub my_solilique_template {
 311 \&        die (Template::Exception\->new('yorrick', 'Fellow of infinite jest'));
 312 \&    }
 313 .Ve
 314 .PP
 315 Templates generally need to do a lot more than just generate static output or
 316 raise errors. They may want to inspect variable values, process another
 317 template, load a plugin, run a filter, and so on. Whenever a template
 318 subroutine is called, it gets passed a reference to a Template::Context
 319 object. It is through this context object that template code can access the
 320 features of the Template Toolkit.
 321 .PP
 322 We described earlier how the Template::Service object calls on
 323 Template::Context to handle a \fIprocess()\fR
 324 request from the \fIoutside\fR. We can make a similar request on a context to
 325 process a template, but from within the code of another template. This is a
 326 call from the \fIinside\fR.
 327 .PP
 328 .Vb 6
 329 \&    sub my_process_template {
 330 \&        my $context = shift;
 331 \&        my $output = $context\->process('header', { title => 'Hello World' })
 332 \&                   . "\ensome content\en"
 333 \&                   . $context\->process('footer');
 334 \&    }
 335 .Ve
 336 .PP
 337 This is then roughly equivalent to a source template something
 338 like this:
 339 .PP
 340 .Vb 5
 341 \&    [% PROCESS header
 342 \&        title = 'Hello World'
 343 \&    %]
 344 \&    some content
 345 \&    [% PROCESS footer %]
 346 .Ve
 347 .PP
 348 Template variables are stored in, and managed by a Template::Stash object.
 349 This is a blessed hash array in which template variables are defined. The
 350 object wrapper provides \fIget()\fR and
 351 \&\fIset()\fR method which implement all the
 352 \&\fImagical.variable.features\fR of the Template Toolkit.
 353 .PP
 354 Each context object has its own stash, a reference to which can be returned by
 355 the appropriately named \fIstash()\fR method. So to
 356 print the value of some template variable, or for example, to represent the
 357 following source template:
 358 .PP
 359 .Vb 1
 360 \&    <title>[% title %]</title>
 361 .Ve
 362 .PP
 363 we might have a subroutine definition something like this:
 364 .PP
 365 .Vb 5
 366 \&    sub {
 367 \&        my $context = shift;
 368 \&        my $stash = $context\->stash();
 369 \&        return '<title>' . $stash\->get('title') . '</title>';
 370 \&    }
 371 .Ve
 372 .PP
 373 The stash \fIget()\fR method hides the details of the
 374 underlying variable types, automatically calling code references, checking
 375 return values, and performing other such tricks. If '\f(CW\*(C`title\*(C'\fR' happens to be
 376 bound to a subroutine then we can specify additional parameters as a list
 377 reference passed as the second argument to \fIget()\fR.
 378 .PP
 379 .Vb 1
 380 \&    [% title('The Cat Sat on the Mat') %]
 381 .Ve
 382 .PP
 383 This translates to the stash call:
 384 .PP
 385 .Vb 1
 386 \&    $stash\->get([ 'title', ['The Cat Sat on the Mat'] ]);
 387 .Ve
 388 .PP
 389 Dotted compound variables can be requested by passing a single
 390 list reference to the \f(CW\*(C`get()\*(C'\fR method in place of the variable
 391 name.  Each pair of elements in the list should correspond to the
 392 variable name and reference to a list of arguments for each
 393 dot-delimited element of the variable.
 394 .PP
 395 .Vb 1
 396 \&    [% foo(1, 2).bar(3, 4).baz(5) %]
 397 .Ve
 398 .PP
 399 is thus equivalent to
 400 .PP
 401 .Vb 1
 402 \&    $stash\->get([ foo => [1,2], bar => [3,4], baz => [5] ]);
 403 .Ve
 404 .PP
 405 If there aren't any arguments for an element, you can specify an
 406 empty, zero or null argument list.
 407 .PP
 408 .Vb 2
 409 \&    [% foo.bar %]
 410 \&    $stash\->get([ 'foo', 0, 'bar', 0 ]);
 411 .Ve
 412 .PP
 413 The \fIset()\fR method works in a similar way. It takes a
 414 variable name and a variable value which should be assigned to it.
 415 .PP
 416 .Vb 2
 417 \&    [% x = 10 %]
 418 \&    $stash\->set('x', 10);
 419 .Ve
 420 .PP
 421 .Vb 2
 422 \&    [% x.y = 10 %]
 423 \&    $stash\->set([ 'x', 0, 'y', 0 ], 10);
 424 .Ve
 425 .PP
 426 So the stash gives us access to template variables and the context provides
 427 the higher level functionality.
 428 .PP
 429 Alongside the \fIprocess()\fR method lies the
 430 \&\fIinclude()\fR method. Just as with the \f(CW\*(C`PROCESS\*(C'\fR /
 431 \&\f(CW\*(C`INCLUDE\*(C'\fR directives, the key difference is in variable localisation. Before
 432 processing a template, the \f(CW\*(C`process()\*(C'\fR method simply updates the stash to set
 433 any new variable definitions, overwriting any existing values. In contrast,
 434 the \f(CW\*(C`include()\*(C'\fR method creates a copy of the existing stash, in a process known
 435 as \fIcloning\fR the stash, and then uses that as a temporary variable store. Any
 436 previously existing variables are still defined, but any changes made to
 437 variables, including setting the new variable values passed aas arguments will
 438 affect only the local copy of the stash (although note that it's only a
 439 shallow copy, so it's not foolproof). When the template has been processed,
 440 the \f(CW\*(C`include()\*(C'\fR method restores the previous variable state by \fIdecloning\fR the
 441 stash.
 442 .PP
 443 The context also provides an \fIinsert()\fR method to
 444 implement the \f(CW\*(C`INSERT\*(C'\fR directive, but no \f(CW\*(C`wrapper()\*(C'\fR method. This functionality
 445 can be implemented by rewriting the Perl code and calling \f(CW\*(C`include()\*(C'\fR.
 446 .PP
 447 .Vb 3
 448 \&    [% WRAPPER foo \-%]
 449 \&       blah blah [% x %]
 450 \&    [%\- END %]
 451 .Ve
 452 .PP
 453 .Vb 3
 454 \&    $context\->include('foo', {
 455 \&        content => 'blah blah ' . $stash\->get('x'),
 456 \&    });
 457 .Ve
 458 .PP
 459 Other than the template processing methods \f(CW\*(C`process()\*(C'\fR, \f(CW\*(C`include()\*(C'\fR and
 460 \&\f(CW\*(C`insert()\*(C'\fR, the context defines methods for fetching plugin objects,
 461 \&\fIplugin()\fR, and filters,
 462 \&\fIfilter()\fR.
 463 .PP
 464 .Vb 2
 465 \&    # TT USE directive
 466 \&    [% USE foo = Bar(10) %]
 467 .Ve
 468 .PP
 469 .Vb 2
 470 \&    # equivalent Perl
 471 \&    $stash\->set('foo', $context\->plugin('Bar', [10]));
 472 .Ve
 473 .PP
 474 .Vb 4
 475 \&    # TT FILTER block
 476 \&    [% FILTER bar(20) %]
 477 \&       blah blah blah
 478 \&    [% END %]
 479 .Ve
 480 .PP
 481 .Vb 3
 482 \&    # equivalent Perl
 483 \&    my $filter = $context\->filter('bar', [20]);
 484 \&    &$filter('blah blah blah');
 485 .Ve
 486 .PP
 487 Pretty much everything else you might want to do in a template can be done in
 488 Perl code. Things like \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR, \f(CW\*(C`FOREACH\*(C'\fR and so on all have direct
 489 counterparts in Perl.
 490 .PP
 491 .Vb 4
 492 \&    # TT IF directive
 493 \&    [% IF msg %]
 494 \&       Message: [% msg %]
 495 \&    [% END %];
 496 .Ve
 497 .PP
 498 .Vb 5
 499 \&    # equivalent Perl
 500 \&    if ($stash\->get('msg')) {
 501 \&        $output .=  'Message: ';
 502 \&        $output .= $stash\->get('msg');
 503 \&    }
 504 .Ve
 505 .PP
 506 The best way to get a better understanding of what's going on underneath
 507 the hood is to set the \f(CW$Template::Parser::DEBUG\fR flag to a true value
 508 and start processing templates.  This will cause the parser to print the
 509 generated Perl code for each template it compiles to \f(CW\*(C`STDERR\*(C'\fR.  You'll
 510 probably also want to set the \f(CW$Template::Directive::PRETTY\fR option to
 511 have the Perl pretty-printed for human consumption.
 512 .PP
 513 .Vb 3
 514 \&    use Template;
 515 \&    use Template::Parser;
 516 \&    use Template::Directive;
 517 .Ve
 518 .PP
 519 .Vb 2
 520 \&    $Template::Parser::DEBUG = 1;
 521 \&    $Template::Directive::PRETTY = 1;
 522 .Ve
 523 .PP
 524 .Vb 2
 525 \&    my $template = Template\->new();
 526 \&    $template\->process(\e*DATA, { cat => 'dog', mat => 'log' });
 527 .Ve
 528 .PP
 529 .Vb 2
 530 \&    __DATA__
 531 \&    The [% cat %] sat on the [% mat %]
 532 .Ve
 533 .PP
 534 The output sent to \f(CW\*(C`STDOUT\*(C'\fR remains as you would expect:
 535 .PP
 536 .Vb 1
 537 \&    The dog sat on the log
 538 .Ve
 539 .PP
 540 The output sent to \f(CW\*(C`STDERR\*(C'\fR would look something like this:
 541 .PP
 542 .Vb 6
 543 \&    compiled main template document block:
 544 \&    sub {
 545 \&        my $context = shift || die "template sub called without context\en";
 546 \&        my $stash   = $context\->stash;
 547 \&        my $output  = '';
 548 \&        my $error;
 549 .Ve
 550 .PP
 551 .Vb 11
 552 \&        eval { BLOCK: {
 553 \&            $output .=  "The ";
 554 \&            $output .=  $stash\->get('cat');
 555 \&            $output .=  " sat on the ";
 556 \&            $output .=  $stash\->get('mat');
 557 \&            $output .=  "\en";
 558 \&        } };
 559 \&        if ($@) {
 560 \&            $error = $context\->catch($@, \e$output);
 561 \&            die $error unless $error\->type eq 'return';
 562 \&        }
 563 .Ve
 564 .PP
 565 .Vb 2
 566 \&        return $output;
 567 \&    }
 568 .Ve
 569 .SH "Hacking on the Template Toolkit"
 570 .IX Header "Hacking on the Template Toolkit"
 571 Please feel free to hack on the Template Toolkit.  If you find a bug
 572 that needs fixing, if you have an idea for something that's missing,
 573 or you feel inclined to tackle something on the \s-1TODO\s0 list, then by all
 574 means go ahead and do it!
 575 .PP
 576 If you're contemplating something non-trivial then you'll probably
 577 want to bring it up on the mailing list first to get an idea about the
 578 current state of play, find out if anyone's already working on it, and
 579 so on.
 580 .PP
 581 When you start to hack on the Template Toolkit, please make sure you
 582 start from the latest developer release.  Stable releases are uploaded
 583 to \s-1CPAN\s0 and have all-numerical version numbers, e.g. 2.04, 2.05.
 584 Developer releases are available from the Template Toolkit web site
 585 and have a character suffix on the version, e.g. 2.04a, 2.04b, etc.
 586 .PP
 587 Once you've made your changes, please remember to update the test
 588 suite by adding extra tests to one of the existing test scripts in
 589 the \f(CW\*(C`t\*(C'\fR sub\-directory, or by adding a new test script of your own.
 590 And of course, run \f(CW\*(C`make test\*(C'\fR to ensure that all the tests pass
 591 with your new code.
 592 .PP
 593 Don't forget that any files you do add will need to be added to the
 594 \&\s-1MANIFEST\s0.  Running \f(CW\*(C`make manifest\*(C'\fR will do this for you, but you need
 595 to make sure you haven't got any other temporary files lying around
 596 that might also get added to it.
 597 .PP
 598 Documentation is often something that gets overlooked but it's just as
 599 important as the code. If you're adding a new module, a plugin module, for
 600 example, then it's \s-1OK\s0 to include the \s-1POD\s0 documentation in with the module, but
 601 \&\fIplease\fR write it all in one piece at the end of the file, \fIafter\fR the code
 602 (just look at any other \f(CW\*(C`Template::*\*(C'\fR module for an example). It's a
 603 religious issue, I know, but I have a strong distaste for \s-1POD\s0 documentation
 604 interspersed throughout the code. In my not-so-humble opinion, it makes both
 605 the code and the documentation harder to read (same kinda problem as embedding
 606 Perl in \s-1HTML\s0).
 607 .PP
 608 To share your changes with the rest of the world, you'll need to
 609 prepare a patch file.  To do this you should have 2 directories
 610 side\-by\-side, one which is the original, unmodified distribution
 611 directory for the latest developer release, and the other is a
 612 copy of that same directory which includes your changes.
 613 .PP
 614 The following example shows a typical hacking session.  First we
 615 unpack the latest developer release.
 616 .PP
 617 .Vb 1
 618 \&    $ tar zxf Template\-Toolkit\-2.05c.tar.gz
 619 .Ve
 620 .PP
 621 At this point, it's a good idea to rename the directory to give
 622 some indicate of what it contains.
 623 .PP
 624 .Vb 1
 625 \&    $ mv Template\-Toolkit\-2.05c Template\-Toolkit\-2.05c\-abw\-xyz\-hack
 626 .Ve
 627 .PP
 628 Then go hack!
 629 .PP
 630 .Vb 1
 631 \&    $ cd Template\-Toolkit\-2.05c\-abw\-xyz\-hack
 632 .Ve
 633 .PP
 634 .Vb 1
 635 \&      [ hacking ]
 636 .Ve
 637 .PP
 638 .Vb 1
 639 \&    $ cd ..
 640 .Ve
 641 .PP
 642 When you're all done and ready to prepare a patch, unpack the
 643 distribution archive again so that you've got the original to
 644 \&\f(CW\*(C`diff\*(C'\fR against your new code.
 645 .PP
 646 .Vb 1
 647 \&    $ tar zxf Template\-Toolkit\-2.05c.tar.gz
 648 .Ve
 649 .PP
 650 You should now have an original distribution directory and a modified
 651 version of that same directory, side\-by\-side.
 652 .PP
 653 .Vb 2
 654 \&    $ ls
 655 \&    Template\-Toolkit\-2.05c  Template\-Toolkit\-2.05c\-abw\-xyz\-hack
 656 .Ve
 657 .PP
 658 Now run \f(CW\*(C`diff\*(C'\fR and save the output into an appropriately named patch
 659 file.
 660 .PP
 661 .Vb 1
 662 \&    $ diff \-Naur Template\-Toolkit\-2.05c Template\-Toolkit\-2.05c\-abw\-xyz\-hack > patch\-TT205c\-abw\-xyz\-hack
 663 .Ve
 664 .PP
 665 You can then post the generated patch file to the mailing list,
 666 describing what it does, why it does it, how it does it and any
 667 other relevant information.
 668 .PP
 669 If you want to apply someone else's patch then you should start with the
 670 same original distribution source on which the patch is based.  From within
 671 the root of the distribution, run \f(CW\*(C`patch\*(C'\fR feeding in the patch file as
 672 standard input.  The '\f(CW\*(C`p1\*(C'\fR' option is required to strip the first element
 673 of the path name (e.g. \f(CW\*(C`Template\-Toolkit\-2.05c/README\*(C'\fR becomes \f(CW\*(C`README\*(C'\fR which
 674 is then the correct path).
 675 .PP
 676 .Vb 3
 677 \&    $ tar zxf Template\-Toolkit\-2.05c.tar.gz
 678 \&    $ cd Template\-Toolkit\-2.05c
 679 \&    $ patch \-p1 < ../patch\-TT205c\-abw\-xyz\-hack
 680 .Ve
 681 .PP
 682 The output generated by \f(CW\*(C`patch\*(C'\fR should be something like the following:
 683 .PP
 684 .Vb 4
 685 \&    patching file README
 686 \&    patching file lib/Template.pm
 687 \&    patching file lib/Template/Provider.pm
 688 \&    patching file t/provider.t
 689 .Ve