local-lib5/man/man3/Template::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::Config 3"
 132 .TH Template::Config 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Config \- Factory module for instantiating other TT2 modules
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Config;
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 This module implements various methods for loading and instantiating
 143 other modules that comprise the Template Toolkit.  It provides a consistent
 144 way to create toolkit components and allows custom modules to be used in
 145 place of the regular ones.
 146 .PP
 147 Package variables such as \f(CW$STASH\fR, \f(CW$SERVICE\fR, \f(CW$CONTEXT\fR, etc., contain
 148 the default module/package name for each component (Template::Stash,
 149 Template::Service and Template::Context, respectively) and are used by
 150 the various factory methods (\fIstash()\fR, \fIservice()\fR and \fIcontext()\fR) to
 151 load the appropriate module. Changing these package variables will cause
 152 subsequent calls to the relevant factory method to load and instantiate an
 153 object from the new class.
 154 .SH "PUBLIC METHODS"
 155 .IX Header "PUBLIC METHODS"
 156 .Sh "load($module)"
 157 .IX Subsection "load($module)"
 158 Load a module using Perl's \fIrequire()\fR. Any occurences of '\f(CW\*(C`::\*(C'\fR' in the module
 159 name are be converted to '\f(CW\*(C`/\*(C'\fR', and '\f(CW\*(C`.pm\*(C'\fR' is appended. Returns 1 on success or
 160 undef on error.  Use \f(CW\*(C`$class\->error()\*(C'\fR to examine the error string.
 161 .Sh "\fIpreload()\fP"
 162 .IX Subsection "preload()"
 163 This method preloads all the other \f(CW\*(C`Template::*\*(C'\fR modules that are likely to
 164 be used. It is called automatically by the Template module when running
 165 under mod_perl (\f(CW$ENV{MOD_PERL}\fR is set).
 166 .Sh "parser(\e%config)"
 167 .IX Subsection "parser(%config)"
 168 Instantiate a new parser object of the class whose name is denoted by
 169 the package variable \f(CW$PARSER\fR (default: Template::Parser).  Returns
 170 a reference to a newly instantiated parser object or undef on error.
 171 .Sh "provider(\e%config)"
 172 .IX Subsection "provider(%config)"
 173 Instantiate a new template provider object (default: Template::Provider).
 174 Returns an object reference or undef on error, as above.
 175 .Sh "plugins(\e%config)"
 176 .IX Subsection "plugins(%config)"
 177 Instantiate a new plugins provider object (default: Template::Plugins).
 178 Returns an object reference or undef on error, as above.
 179 .Sh "filters(\e%config)"
 180 .IX Subsection "filters(%config)"
 181 Instantiate a new filter provider object (default: Template::Filters).
 182 Returns an object reference or undef on error, as above.
 183 .Sh "stash(\e%vars)"
 184 .IX Subsection "stash(%vars)"
 185 Instantiate a new stash object (Template::Stash or Template::Stash::XS
 186 depending on the default set at installation time) using the contents of the
 187 optional hash array passed by parameter as initial variable definitions.
 188 Returns an object reference or undef on error, as above.
 189 .Sh "context(\e%config)"
 190 .IX Subsection "context(%config)"
 191 Instantiate a new template context object (default: Template::Context).
 192 Returns an object reference or undef on error, as above.
 193 .Sh "service(\e%config)"
 194 .IX Subsection "service(%config)"
 195 Instantiate a new template service object (default: Template::Service).
 196 Returns an object reference or undef on error, as above.
 197 .Sh "iterator(\e%config)"
 198 .IX Subsection "iterator(%config)"
 199 Instantiate a new template iterator object (default: Template::Iterator).
 200 Returns an object reference or undef on error, as above.
 201 .Sh "constants(\e%config)"
 202 .IX Subsection "constants(%config)"
 203 Instantiate a new namespace handler for compile time constant folding
 204 (default: Template::Namespace::Constants). Returns an object reference or
 205 undef on error, as above.
 206 .Sh "instdir($dir)"
 207 .IX Subsection "instdir($dir)"
 208 Returns the root directory of the Template Toolkit installation under
 209 which optional components are installed.  Any relative directory specified
 210 as an argument will be appended to the returned directory.
 211 .PP
 212 .Vb 3
 213 \&    # e.g. returns '/usr/local/tt2'
 214 \&    my $ttroot = Template::Config\->instdir()
 215 \&        || die "$Template::Config::ERROR\en";
 216 .Ve
 217 .PP
 218 .Vb 3
 219 \&    # e.g. returns '/usr/local/tt2/templates'
 220 \&    my $template = Template::Config\->instdir('templates')
 221 \&        || die "$Template::Config::ERROR\en";
 222 .Ve
 223 .PP
 224 Returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$Template::Config::ERROR\fR appropriately if the
 225 optional components of the Template Toolkit have not been installed.
 226 .SH "AUTHOR"
 227 .IX Header "AUTHOR"
 228 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 229 .SH "COPYRIGHT"
 230 .IX Header "COPYRIGHT"
 231 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 232 .PP
 233 This module is free software; you can redistribute it and/or
 234 modify it under the same terms as Perl itself.
 235 .SH "SEE ALSO"
 236 .IX Header "SEE ALSO"
 237 Template