local-lib5/man/man3/Template::Provider.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::Provider 3"
 132 .TH Template::Provider 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Provider \- Provider module for loading/compiling templates
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    $provider = Template::Provider\->new(\e%options);
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    ($template, $error) = $provider\->fetch($name);
 143 .Ve
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 The Template::Provider is used to load, parse, compile and cache template
 147 documents. This object may be sub-classed to provide more specific facilities
 148 for loading, or otherwise providing access to templates.
 149 .PP
 150 The Template::Context objects maintain a list of Template::Provider
 151 objects which are polled in turn (via \fIfetch()\fR) to
 152 return a requested template. Each may return a compiled template, raise an
 153 error, or decline to serve the request, giving subsequent providers a chance
 154 to do so.
 155 .PP
 156 The Template::Provider can also be subclassed to provide templates from
 157 a different source, e.g. a database. See \s-1SUBCLASSING\s0 below.
 158 .PP
 159 This documentation needs work.
 160 .SH "PUBLIC METHODS"
 161 .IX Header "PUBLIC METHODS"
 162 .Sh "new(\e%options)"
 163 .IX Subsection "new(%options)"
 164 Constructor method which instantiates and returns a new \f(CW\*(C`Template::Provider\*(C'\fR
 165 object.  A reference to a hash array of configuration options may be passed.
 166 .PP
 167 See \*(L"\s-1CONFIGURATION\s0 \s-1OPTIONS\s0\*(R" below for a summary of configuration options
 168 and Template::Manual::Config for full details.
 169 .Sh "fetch($name)"
 170 .IX Subsection "fetch($name)"
 171 Returns a compiled template for the name specified. If the template cannot be
 172 found then \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR is returned. If an error occurs (e.g.
 173 read error, parse error) then \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR is returned, where
 174 \&\f(CW$error\fR is the error message generated. If the \s-1TOLERANT\s0 option is set the
 175 the method returns \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR instead of returning an error.
 176 .ie n .Sh "store($name, $template)"
 177 .el .Sh "store($name, \f(CW$template\fP)"
 178 .IX Subsection "store($name, $template)"
 179 Stores the compiled template, \f(CW$template\fR, in the cache under the name,
 180 \&\f(CW$name\fR.  Susbequent calls to \f(CW\*(C`fetch($name)\*(C'\fR will return this template in
 181 preference to any disk-based file.
 182 .Sh "include_path(\e@newpath)"
 183 .IX Subsection "include_path(@newpath)"
 184 Accessor method for the \f(CW\*(C`INCLUDE_PATH\*(C'\fR setting.  If called with an
 185 argument, this method will replace the existing \f(CW\*(C`INCLUDE_PATH\*(C'\fR with
 186 the new value.
 187 .Sh "\fIpaths()\fP"
 188 .IX Subsection "paths()"
 189 This method generates a copy of the \f(CW\*(C`INCLUDE_PATH\*(C'\fR list.  Any elements in the
 190 list which are dynamic generators (e.g. references to subroutines or objects
 191 implementing a \f(CW\*(C`paths()\*(C'\fR method) will be called and the list of directories
 192 returned merged into the output list.
 193 .PP
 194 It is possible to provide a generator which returns itself, thus sending
 195 this method into an infinite loop.  To detect and prevent this from happening,
 196 the \f(CW$MAX_DIRS\fR package variable, set to \f(CW64\fR by default, limits the maximum
 197 number of paths that can be added to, or generated for the output list.  If
 198 this number is exceeded then the method will immediately return an error
 199 reporting as much.
 200 .SH "CONFIGURATION OPTIONS"
 201 .IX Header "CONFIGURATION OPTIONS"
 202 The following list summarises the configuration options that can be provided
 203 to the \f(CW\*(C`Template::Provider\*(C'\fR \fInew()\fR constructor. Please consult
 204 Template::Manual::Config for further details and examples of each
 205 configuration option in use.
 206 .Sh "\s-1INCLUDE_PATH\s0"
 207 .IX Subsection "INCLUDE_PATH"
 208 The \s-1INCLUDE_PATH\s0 option is used to
 209 specify one or more directories in which template files are located.
 210 .PP
 211 .Vb 4
 212 \&    # single path
 213 \&    my $provider = Template::Provider\->new({
 214 \&        INCLUDE_PATH => '/usr/local/templates',
 215 \&    });
 216 .Ve
 217 .PP
 218 .Vb 5
 219 \&    # multiple paths
 220 \&    my $provider = Template::Provider\->new({
 221 \&        INCLUDE_PATH => [ '/usr/local/templates',
 222 \&                          '/tmp/my/templates' ],
 223 \&    });
 224 .Ve
 225 .Sh "\s-1ABSOLUTE\s0"
 226 .IX Subsection "ABSOLUTE"
 227 The \s-1ABSOLUTE\s0 flag is used to indicate if
 228 templates specified with absolute filenames (e.g. '\f(CW\*(C`/foo/bar\*(C'\fR') should be
 229 processed. It is disabled by default and any attempt to load a template by
 230 such a name will cause a '\f(CW\*(C`file\*(C'\fR' exception to be raised.
 231 .PP
 232 .Vb 3
 233 \&    my $provider = Template::Provider\->new({
 234 \&        ABSOLUTE => 1,
 235 \&    });
 236 .Ve
 237 .Sh "\s-1RELATIVE\s0"
 238 .IX Subsection "RELATIVE"
 239 The \s-1RELATIVE\s0 flag is used to indicate if
 240 templates specified with filenames relative to the current directory (e.g.
 241 \&\f(CW\*(C`./foo/bar\*(C'\fR or \f(CW\*(C`../../some/where/else\*(C'\fR) should be loaded. It is also disabled
 242 by default, and will raise a \f(CW\*(C`file\*(C'\fR error if such template names are
 243 encountered.
 244 .PP
 245 .Vb 3
 246 \&    my $provider = Template::Provider\->new({
 247 \&        RELATIVE => 1,
 248 \&    });
 249 .Ve
 250 .Sh "\s-1DEFAULT\s0"
 251 .IX Subsection "DEFAULT"
 252 The \s-1DEFAULT\s0 option can be used to specify
 253 a default template which should be used whenever a specified template can't be
 254 found in the \s-1INCLUDE_PATH\s0.
 255 .PP
 256 .Vb 3
 257 \&    my $provider = Template::Provider\->new({
 258 \&        DEFAULT => 'notfound.html',
 259 \&    });
 260 .Ve
 261 .PP
 262 If a non-existant template is requested through the Template
 263 \&\fIprocess()\fR method, or by an \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR or
 264 \&\f(CW\*(C`WRAPPER\*(C'\fR directive, then the \f(CW\*(C`DEFAULT\*(C'\fR template will instead be processed, if
 265 defined. Note that the \f(CW\*(C`DEFAULT\*(C'\fR template is not used when templates are
 266 specified with absolute or relative filenames, or as a reference to a input
 267 file handle or text string.
 268 .Sh "\s-1ENCODING\s0"
 269 .IX Subsection "ENCODING"
 270 The Template Toolkit will automatically decode Unicode templates that
 271 have a Byte Order Marker (\s-1BOM\s0) at the start of the file.  This option
 272 can be used to set the default encoding for templates that don't define
 273 a \s-1BOM\s0.
 274 .PP
 275 .Vb 3
 276 \&    my $provider = Template::Provider\->new({
 277 \&        ENCODING => 'utf8',
 278 \&    });
 279 .Ve
 280 .PP
 281 See Encode for further information.
 282 .Sh "\s-1CACHE_SIZE\s0"
 283 .IX Subsection "CACHE_SIZE"
 284 The \s-1CACHE_SIZE\s0 option can be used to
 285 limit the number of compiled templates that the module should cache. By
 286 default, the \s-1CACHE_SIZE\s0 is undefined
 287 and all compiled templates are cached.
 288 .PP
 289 .Vb 3
 290 \&    my $provider = Template::Provider\->new({
 291 \&        CACHE_SIZE => 64,   # only cache 64 compiled templates
 292 \&    });
 293 .Ve
 294 .Sh "\s-1STAT_TTL\s0"
 295 .IX Subsection "STAT_TTL"
 296 The \s-1STAT_TTL\s0 value can be set to control
 297 how long the \f(CW\*(C`Template::Provider\*(C'\fR will keep a template cached in memory
 298 before checking to see if the source template has changed.
 299 .PP
 300 .Vb 3
 301 \&    my $provider = Template::Provider\->new({
 302 \&        STAT_TTL => 60,  # one minute
 303 \&    });
 304 .Ve
 305 .Sh "\s-1COMPILE_EXT\s0"
 306 .IX Subsection "COMPILE_EXT"
 307 The \s-1COMPILE_EXT\s0 option can be
 308 provided to specify a filename extension for compiled template files.
 309 It is undefined by default and no attempt will be made to read or write
 310 any compiled template files.
 311 .PP
 312 .Vb 3
 313 \&    my $provider = Template::Provider\->new({
 314 \&        COMPILE_EXT => '.ttc',
 315 \&    });
 316 .Ve
 317 .Sh "\s-1COMPILE_DIR\s0"
 318 .IX Subsection "COMPILE_DIR"
 319 The \s-1COMPILE_DIR\s0 option is used to
 320 specify an alternate directory root under which compiled template files should
 321 be saved.
 322 .PP
 323 .Vb 3
 324 \&    my $provider = Template::Provider\->new({
 325 \&        COMPILE_DIR => '/tmp/ttc',
 326 \&    });
 327 .Ve
 328 .Sh "\s-1TOLERANT\s0"
 329 .IX Subsection "TOLERANT"
 330 The \s-1TOLERANT\s0 flag can be set to indicate
 331 that the \f(CW\*(C`Template::Provider\*(C'\fR module should ignore any errors encountered while
 332 loading a template and instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR.
 333 .Sh "\s-1PARSER\s0"
 334 .IX Subsection "PARSER"
 335 The \s-1PARSER\s0 option can be used to define
 336 a parser module other than the default of Template::Parser.
 337 .PP
 338 .Vb 3
 339 \&    my $provider = Template::Provider\->new({
 340 \&        PARSER => MyOrg::Template::Parser\->new({ ... }),
 341 \&    });
 342 .Ve
 343 .Sh "\s-1DEBUG\s0"
 344 .IX Subsection "DEBUG"
 345 The \s-1DEBUG\s0 option can be used to enable
 346 debugging messages from the Template::Provider module by setting it to include
 347 the \f(CW\*(C`DEBUG_PROVIDER\*(C'\fR value.
 348 .PP
 349 .Vb 1
 350 \&    use Template::Constants qw( :debug );
 351 .Ve
 352 .PP
 353 .Vb 3
 354 \&    my $template = Template\->new({
 355 \&        DEBUG => DEBUG_PROVIDER,
 356 \&    });
 357 .Ve
 358 .SH "SUBCLASSING"
 359 .IX Header "SUBCLASSING"
 360 The \f(CW\*(C`Template::Provider\*(C'\fR module can be subclassed to provide templates from a
 361 different source (e.g. a database).  In most cases you'll just need to provide
 362 custom implementations of the \f(CW\*(C`_template_modified()\*(C'\fR and \f(CW\*(C`_template_content()\*(C'\fR
 363 methods.  If your provider requires and custom initialisation then you'll also
 364 need to implement a new \f(CW\*(C`_init()\*(C'\fR method.
 365 .PP
 366 Caching in memory and on disk will still be applied (if enabled)
 367 when overriding these methods.
 368 .Sh "_template_modified($path)"
 369 .IX Subsection "_template_modified($path)"
 370 Returns a timestamp of the \f(CW$path\fR passed in by calling \f(CW\*(C`stat()\*(C'\fR.
 371 This can be overridden, for example, to return a last modified value from
 372 a database.  The value returned should be a timestamp value (as returned by \f(CW\*(C`time()\*(C'\fR,
 373 although a sequence number should work as well.
 374 .Sh "_template_content($path)"
 375 .IX Subsection "_template_content($path)"
 376 This method returns the content of the template for all \f(CW\*(C`INCLUDE\*(C'\fR, \f(CW\*(C`PROCESS\*(C'\fR,
 377 and \f(CW\*(C`INSERT\*(C'\fR directives.
 378 .PP
 379 When called in scalar context, the method returns the content of the template
 380 located at \f(CW$path\fR, or \f(CW\*(C`undef\*(C'\fR if \f(CW$path\fR is not found.
 381 .PP
 382 When called in list context it returns \f(CW\*(C`($content, $error, $mtime)\*(C'\fR,
 383 where \f(CW$content\fR is the template content, \f(CW$error\fR is an error string
 384 (e.g. "\f(CW\*(C`$path: File not found\*(C'\fR"), and \f(CW$mtime\fR is the template modification
 385 time.
 386 .SH "AUTHOR"
 387 .IX Header "AUTHOR"
 388 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 389 .SH "COPYRIGHT"
 390 .IX Header "COPYRIGHT"
 391 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 392 .PP
 393 This module is free software; you can redistribute it and/or
 394 modify it under the same terms as Perl itself.
 395 .SH "SEE ALSO"
 396 .IX Header "SEE ALSO"
 397 Template, Template::Parser, Template::Context