local-lib5/man/man3/Template::Modules.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::Modules 3"
 132 .TH Template::Modules 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Modules \- Template Toolkit Modules
 135 .SH "Template Toolkit Modules"
 136 .IX Header "Template Toolkit Modules"
 137 This documentation provides an overview of the different modules that
 138 comprise the Template Toolkit.
 139 .Sh "Template"
 140 .IX Subsection "Template"
 141 The Template module is the front-end to the Template Toolkit for
 142 Perl programmers.
 143 .PP
 144 .Vb 3
 145 \&    use Template;
 146 \&    my $tt = Template\->new();
 147 \&    $tt\->process('hello.html', message => 'Hello World');
 148 .Ve
 149 .Sh "Template::Base"
 150 .IX Subsection "Template::Base"
 151 The Template::Base module implements a base class from which the other
 152 Template Toolkit modules are derived.  It implements common functionality
 153 for creating objects, error reporting, debugging, and so on.
 154 .Sh "Template::Config"
 155 .IX Subsection "Template::Config"
 156 The Template::Config module defines the configuration of the Template
 157 Toolkit for your system. It is an example of a \fIfactory module\fR which is
 158 responsible for instantiating the various other modules used in the Template
 159 Toolkit.
 160 .PP
 161 For example, the Template::Config module defines the \f(CW$STASH\fR package
 162 variable which indicates which version of the Template::Stash you are
 163 using by default.  If you elected to use the faster \s-1XS\s0
 164 stash when you installed the Template Toolkit, then this will be set as:
 165 .PP
 166 .Vb 1
 167 \&    $STASH = 'Template::Stash::XS';
 168 .Ve
 169 .PP
 170 Otherwise you'll get the regular Perl stash:
 171 .PP
 172 .Vb 1
 173 \&    $STASH = 'Template::Stash';
 174 .Ve
 175 .PP
 176 This approach means that other parts of the Template Toolkit don't have to
 177 worry about which stash you're using.  They just ask the Template::Config
 178 module to create a stash of the right kind.
 179 .Sh "Template::Constants"
 180 .IX Subsection "Template::Constants"
 181 The Template::Constants defines a number of constants that are used by
 182 the Template Toolkit.
 183 .PP
 184 For example, the \f(CW\*(C`:chomp\*(C'\fR tagset defines the \f(CW\*(C`CHOMP_???\*(C'\fR constants that
 185 can be used with the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR configuration options.
 186 .PP
 187 .Vb 4
 188 \&    use Template::Constants ':chomp';
 189 \&    my $tt = Template\->new({
 190 \&        PRE_CHOMP => CHOMP_COLLAPSE,
 191 \&    });
 192 .Ve
 193 .Sh "Template::Context"
 194 .IX Subsection "Template::Context"
 195 The Template::Context module defines a runtime context in which templates
 196 are processed. A context keeps track of all the templates, variables, plugins,
 197 and other resources that are available (either directly or through delegate
 198 objects) and provides methods to fetch, store, and perform various operations
 199 on them.
 200 .Sh "Template::Document"
 201 .IX Subsection "Template::Document"
 202 The Template::Document module implements a compiled template document
 203 object.  This is generated by the Template::Parser module.
 204 .Sh "Template::Exception"
 205 .IX Subsection "Template::Exception"
 206 The Template::Exception module implements an exception object which
 207 is used for runtime error reporting.
 208 .Sh "Template::Filters"
 209 .IX Subsection "Template::Filters"
 210 The Template::Filters module implements a filter provider.  It includes
 211 the core collection of filters that can be used via the \f(CW\*(C`FILTER\*(C'\fR directive.
 212 .Sh "Template::Iterator"
 213 .IX Subsection "Template::Iterator"
 214 The Template::Iterator module implements a data iterator which steps
 215 through each item in a list in turn.  It is used by the \f(CW\*(C`FOREACH\*(C'\fR directive.
 216 Within a \f(CW\*(C`FOREACH\*(C'\fR block, the \f(CW\*(C`loop\*(C'\fR variable always references the
 217 current iterator object.
 218 .PP
 219 .Vb 10
 220 \&    [%  FOREACH item IN list;
 221 \&          IF loop.first;
 222 \&             # first item in loop
 223 \&          ELSIF loop.last;
 224 \&             # last item in loop
 225 \&          ELSE;
 226 \&             # any other item in loop
 227 \&          END;
 228 \&        END
 229 \&    %]
 230 .Ve
 231 .Sh "Template::Namespace::Constants"
 232 .IX Subsection "Template::Namespace::Constants"
 233 The Template::Namespace::Constants module is used internally to represent
 234 constants. These can be resolved immediately at the point that a template is
 235 compiled.
 236 .Sh "Template::Parser"
 237 .IX Subsection "Template::Parser"
 238 The Template::Parser module is used to parse a source template and turn it
 239 into Perl code which can be executed.
 240 .Sh "Template::Plugin"
 241 .IX Subsection "Template::Plugin"
 242 The Template::Plugin module is a base class for Template Toolkit plugins
 243 that can be loaded on demand from within a template using the \f(CW\*(C`USE\*(C'\fR directive.
 244 .Sh "Template::Plugins"
 245 .IX Subsection "Template::Plugins"
 246 The Template::Plugins module is the plugins provider.  It loads and prepares
 247 plugins as and when they are requested from within a template.
 248 .Sh "Template::Provider"
 249 .IX Subsection "Template::Provider"
 250 The Template::Provider module is responsible for loading, compiling and
 251 caching templates.
 252 .Sh "Template::Service"
 253 .IX Subsection "Template::Service"
 254 The Template::Service module implements a service layer that sits just
 255 behind the Template module, and just in front of a Template::Context. It
 256 handles each request to process a template (forwarded from the Template
 257 module). It adds any headers and/or footers (specified via the \f(CW\*(C`PRE_PROCESS\*(C'\fR
 258 and \f(CW\*(C`POST_PROCESS\*(C'\fR options), applies any wrapper (the \f(CW\*(C`WRAPPER\*(C'\fR option) and
 259 catches any errors returned (the \f(CW\*(C`ERRORS\*(C'\fR option).
 260 .Sh "Template::Stash"
 261 .IX Subsection "Template::Stash"
 262 The Template::Stash module is used to fetch and store template variables.
 263 It implements all of the magic associated with the dot operator.
 264 .Sh "Template::Stash::XS"
 265 .IX Subsection "Template::Stash::XS"
 266 The Template::Stash::XS module is a high-speed implementation of
 267 Template::Stash written in C.
 268 .Sh "Template::Test"
 269 .IX Subsection "Template::Test"
 270 The Template::Test module is used to automate the Template Toolkit
 271 test scripts.