local-lib5/man/man3/Template::Filters.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::Filters 3"
 132 .TH Template::Filters 3 "2009-07-04" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Filters \- Post\-processing filters for template blocks
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Filters;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    $filters = Template::Filters\->new(\e%config);
 143 .Ve
 144 .PP
 145 .Vb 1
 146 \&    ($filter, $error) = $filters\->fetch($name, \e@args, $context);
 147 .Ve
 148 .PP
 149 .Vb 6
 150 \&    if ($filter) {
 151 \&        print &$filter("some text");
 152 \&    }
 153 \&    else {
 154 \&        print "Could not fetch $name filter: $error\en";
 155 \&    }
 156 .Ve
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 The \f(CW\*(C`Template::Filters\*(C'\fR module implements a provider for creating subroutines
 160 that implement the standard filters. Additional custom filters may be provided
 161 via the \s-1FILTERS\s0 configuration option.
 162 .SH "METHODS"
 163 .IX Header "METHODS"
 164 .Sh "new(\e%params)"
 165 .IX Subsection "new(%params)"
 166 Constructor method which instantiates and returns a reference to a
 167 \&\f(CW\*(C`Template::Filters\*(C'\fR object.  A reference to a hash array of configuration
 168 items may be passed as a parameter.  These are described below.
 169 .PP
 170 .Vb 3
 171 \&    my $filters = Template::Filters\->new({
 172 \&        FILTERS => { ... },
 173 \&    });
 174 .Ve
 175 .PP
 176 .Vb 3
 177 \&    my $template = Template\->new({
 178 \&        LOAD_FILTERS => [ $filters ],
 179 \&    });
 180 .Ve
 181 .PP
 182 A default \f(CW\*(C`Template::Filters\*(C'\fR module is created by the Template module
 183 if the \s-1LOAD_FILTERS\s0 option isn't specified.  All configuration parameters
 184 are forwarded to the constructor.
 185 .PP
 186 .Vb 3
 187 \&    $template = Template\->new({
 188 \&        FILTERS => { ... },
 189 \&    });
 190 .Ve
 191 .ie n .Sh "fetch($name, \e@args, $context)"
 192 .el .Sh "fetch($name, \e@args, \f(CW$context\fP)"
 193 .IX Subsection "fetch($name, @args, $context)"
 194 Called to request that a filter of a given name be provided.  The name
 195 of the filter should be specified as the first parameter.  This should
 196 be one of the standard filters or one specified in the \s-1FILTERS\s0
 197 configuration hash.  The second argument should be a reference to an
 198 array containing configuration parameters for the filter.  This may be
 199 specified as 0, or undef where no parameters are provided.  The third
 200 argument should be a reference to the current Template::Context
 201 object.
 202 .PP
 203 The method returns a reference to a filter sub-routine on success.  It
 204 may also return \f(CW\*(C`(undef, STATUS_DECLINE)\*(C'\fR to decline the request, to allow
 205 delegation onto other filter providers in the \s-1LOAD_FILTERS\s0 chain of
 206 responsibility.  On error, \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR is returned where \f(CW$error\fR
 207 is an error message or Template::Exception object indicating the error
 208 that occurred.
 209 .PP
 210 When the \f(CW\*(C`TOLERANT\*(C'\fR option is set, errors are automatically downgraded to
 211 a \f(CW\*(C`STATUS_DECLINE\*(C'\fR response.
 212 .Sh "\fIuse_html_entities()\fP"
 213 .IX Subsection "use_html_entities()"
 214 This class method can be called to configure the \f(CW\*(C`html_entity\*(C'\fR filter to use
 215 the HTML::Entities module. An error will be raised if it is not installed
 216 on your system.
 217 .PP
 218 .Vb 2
 219 \&    use Template::Filters;
 220 \&    Template::Filters\->use_html_entities();
 221 .Ve
 222 .Sh "\fIuse_apache_util()\fP"
 223 .IX Subsection "use_apache_util()"
 224 This class method can be called to configure the \f(CW\*(C`html_entity\*(C'\fR filter to use
 225 the Apache::Util module. An error will be raised if it is not installed on
 226 your system.
 227 .PP
 228 .Vb 2
 229 \&    use Template::Filters;
 230 \&    Template::Filters\->use_apache_util();
 231 .Ve
 232 .SH "CONFIGURATION OPTIONS"
 233 .IX Header "CONFIGURATION OPTIONS"
 234 The following list summarises the configuration options that can be provided
 235 to the \f(CW\*(C`Template::Filters\*(C'\fR \fInew()\fR constructor. Please see
 236 Template::Manual::Config for further information about each option.
 237 .Sh "\s-1FILTERS\s0"
 238 .IX Subsection "FILTERS"
 239 The \s-1FILTERS\s0 option can be used to specify
 240 custom filters which can then be used with the
 241 \&\s-1FILTER\s0 directive like any other. These
 242 are added to the standard filters which are available by default.
 243 .PP
 244 .Vb 6
 245 \&    $filters = Template::Filters\->new({
 246 \&        FILTERS => {
 247 \&            'sfilt1' =>   \e&static_filter,
 248 \&            'dfilt1' => [ \e&dyanamic_filter_factory, 1 ],
 249 \&        },
 250 \&    });
 251 .Ve
 252 .Sh "\s-1TOLERANT\s0"
 253 .IX Subsection "TOLERANT"
 254 The \s-1TOLERANT\s0 flag can be set to indicate
 255 that the \f(CW\*(C`Template::Filters\*(C'\fR module should ignore any errors and instead
 256 return \f(CW\*(C`STATUS_DECLINED\*(C'\fR.
 257 .Sh "\s-1DEBUG\s0"
 258 .IX Subsection "DEBUG"
 259 The \s-1DEBUG\s0 option can be used to enable
 260 debugging messages for the Template::Filters module by setting it to include
 261 the \f(CW\*(C`DEBUG_FILTERS\*(C'\fR value.
 262 .PP
 263 .Vb 1
 264 \&    use Template::Constants qw( :debug );
 265 .Ve
 266 .PP
 267 .Vb 3
 268 \&    my $template = Template\->new({
 269 \&        DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
 270 \&    });
 271 .Ve
 272 .SH "STANDARD FILTERS"
 273 .IX Header "STANDARD FILTERS"
 274 Please see Template::Manual::Filters for a list of the filters provided
 275 with the Template Toolkit, complete with examples of use.
 276 .SH "AUTHOR"
 277 .IX Header "AUTHOR"
 278 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 279 .SH "COPYRIGHT"
 280 .IX Header "COPYRIGHT"
 281 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 282 .PP
 283 This module is free software; you can redistribute it and/or
 284 modify it under the same terms as Perl itself.
 285 .SH "SEE ALSO"
 286 .IX Header "SEE ALSO"
 287 Template::Manual::Filters, Template, Template::Context