local-lib5/man/man3/Template::Base.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::Base 3"
 132 .TH Template::Base 3 "2009-05-20" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Base \- Base class module implementing common functionality
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    package My::Module;
 139 \&    use base qw( Template::Base );
 140 .Ve
 141 .PP
 142 .Vb 6
 143 \&    sub _init {
 144 \&        my ($self, $config) = @_;
 145 \&        $self\->{ doodah } = $config\->{ doodah }
 146 \&            || return $self\->error("No 'doodah' specified");
 147 \&        return $self;
 148 \&    }
 149 .Ve
 150 .PP
 151 .Vb 1
 152 \&    package main;
 153 .Ve
 154 .PP
 155 .Vb 2
 156 \&    my $object = My::Module\->new({ doodah => 'foobar' })
 157 \&        || die My::Module\->error();
 158 .Ve
 159 .SH "DESCRIPTION"
 160 .IX Header "DESCRIPTION"
 161 Base class module which implements a constructor and error reporting
 162 functionality for various Template Toolkit modules.
 163 .SH "PUBLIC METHODS"
 164 .IX Header "PUBLIC METHODS"
 165 .Sh "new(\e%config)"
 166 .IX Subsection "new(%config)"
 167 Constructor method which accepts a reference to a hash array or a list
 168 of \f(CW\*(C`name => value\*(C'\fR parameters which are folded into a hash.  The
 169 \&\f(CW\*(C`_init()\*(C'\fR method is then called, passing the configuration hash and should
 170 return true/false to indicate success or failure.  A new object reference
 171 is returned, or undef on error.  Any error message raised can be examined
 172 via the \fIerror()\fR class method or directly via the \f(CW$ERROR\fR package variable
 173 in the derived class.
 174 .PP
 175 .Vb 2
 176 \&    my $module = My::Module\->new({ ... })
 177 \&        || die My::Module\->error(), "\en";
 178 .Ve
 179 .PP
 180 .Vb 2
 181 \&    my $module = My::Module\->new({ ... })
 182 \&        || die "constructor error: $My::Module::ERROR\en";
 183 .Ve
 184 .Sh "error($msg, ...)"
 185 .IX Subsection "error($msg, ...)"
 186 May be called as an object method to get/set the internal \f(CW\*(C`_ERROR\*(C'\fR member
 187 or as a class method to get/set the \f(CW$ERROR\fR variable in the derived class's
 188 package.
 189 .PP
 190 .Vb 2
 191 \&    my $module = My::Module\->new({ ... })
 192 \&        || die My::Module\->error(), "\en";
 193 .Ve
 194 .PP
 195 .Vb 2
 196 \&    $module\->do_something()
 197 \&        || die $module\->error(), "\en";
 198 .Ve
 199 .PP
 200 When called with parameters (multiple params are concatenated), this
 201 method will set the relevant variable and return undef.  This is most
 202 often used within object methods to report errors to the caller.
 203 .PP
 204 .Vb 1
 205 \&    package My::Module;
 206 .Ve
 207 .PP
 208 .Vb 2
 209 \&    sub foobar {
 210 \&        my $self = shift;
 211 .Ve
 212 .PP
 213 .Vb 1
 214 \&        # some other code...
 215 .Ve
 216 .PP
 217 .Vb 3
 218 \&        return $self\->error('some kind of error...')
 219 \&            if $some_condition;
 220 \&    }
 221 .Ve
 222 .Sh "debug($msg, ...)"
 223 .IX Subsection "debug($msg, ...)"
 224 Generates a debugging message by concatenating all arguments
 225 passed into a string and printing it to \f(CW\*(C`STDERR\*(C'\fR.  A prefix is
 226 added to indicate the module of the caller.
 227 .PP
 228 .Vb 1
 229 \&    package My::Module;
 230 .Ve
 231 .PP
 232 .Vb 2
 233 \&    sub foobar {
 234 \&        my $self = shift;
 235 .Ve
 236 .PP
 237 .Vb 1
 238 \&        $self\->debug('called foobar()');
 239 .Ve
 240 .PP
 241 .Vb 2
 242 \&        # some other code...
 243 \&    }
 244 .Ve
 245 .PP
 246 When the \f(CW\*(C`foobar()\*(C'\fR method is called, the following message
 247 is sent to \f(CW\*(C`STDERR\*(C'\fR:
 248 .PP
 249 .Vb 1
 250 \&    [My::Module] called foobar()
 251 .Ve
 252 .PP
 253 Objects can set an internal \f(CW\*(C`DEBUG\*(C'\fR value which the \f(CW\*(C`debug()\*(C'\fR
 254 method will examine.  If this value sets the relevant bits
 255 to indicate \f(CW\*(C`DEBUG_CALLER\*(C'\fR then the file and line number of
 256 the caller will be appened to the message.
 257 .PP
 258 .Vb 1
 259 \&    use Template::Constants qw( :debug );
 260 .Ve
 261 .PP
 262 .Vb 3
 263 \&    my $module = My::Module\->new({
 264 \&        DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER,
 265 \&    });
 266 .Ve
 267 .PP
 268 .Vb 1
 269 \&    $module\->foobar();
 270 .Ve
 271 .PP
 272 This generates an error message such as:
 273 .PP
 274 .Vb 1
 275 \&    [My::Module] called foobar() at My/Module.pm line 6
 276 .Ve
 277 .Sh "\fImodule_version()\fP"
 278 .IX Subsection "module_version()"
 279 Returns the version number for a module, as defined by the \f(CW$VERSION\fR
 280 package variable.
 281 .SH "AUTHOR"
 282 .IX Header "AUTHOR"
 283 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 284 .SH "COPYRIGHT"
 285 .IX Header "COPYRIGHT"
 286 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 287 .PP
 288 This module is free software; you can redistribute it and/or
 289 modify it under the same terms as Perl itself.
 290 .SH "SEE ALSO"
 291 .IX Header "SEE ALSO"
 292 Template