Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Template::Base.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Template::Base 3"
.TH Template::Base 3 "2009-05-20" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Template::Base \- Base class module implementing common functionality
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package My::Module;
\&    use base qw( Template::Base );
.Ve
.PP
.Vb 6
\&    sub _init {
\&        my ($self, $config) = @_;
\&        $self\->{ doodah } = $config\->{ doodah }
\&            || return $self\->error("No 'doodah' specified");
\&        return $self;
\&    }
.Ve
.PP
.Vb 1
\&    package main;
.Ve
.PP
.Vb 2
\&    my $object = My::Module\->new({ doodah => 'foobar' })
\&        || die My::Module\->error();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Base class module which implements a constructor and error reporting 
functionality for various Template Toolkit modules.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.Sh "new(\e%config)"
.IX Subsection "new(%config)"
Constructor method which accepts a reference to a hash array or a list 
of \f(CW\*(C`name => value\*(C'\fR parameters which are folded into a hash.  The 
\&\f(CW\*(C`_init()\*(C'\fR method is then called, passing the configuration hash and should
return true/false to indicate success or failure.  A new object reference
is returned, or undef on error.  Any error message raised can be examined
via the \fIerror()\fR class method or directly via the \f(CW$ERROR\fR package variable 
in the derived class.
.PP
.Vb 2
\&    my $module = My::Module\->new({ ... })
\&        || die My::Module\->error(), "\en";
.Ve
.PP
.Vb 2
\&    my $module = My::Module\->new({ ... })
\&        || die "constructor error: $My::Module::ERROR\en";
.Ve
.Sh "error($msg, ...)"
.IX Subsection "error($msg, ...)"
May be called as an object method to get/set the internal \f(CW\*(C`_ERROR\*(C'\fR member
or as a class method to get/set the \f(CW$ERROR\fR variable in the derived class's
package.
.PP
.Vb 2
\&    my $module = My::Module\->new({ ... })
\&        || die My::Module\->error(), "\en";
.Ve
.PP
.Vb 2
\&    $module\->do_something() 
\&        || die $module\->error(), "\en";
.Ve
.PP
When called with parameters (multiple params are concatenated), this
method will set the relevant variable and return undef.  This is most
often used within object methods to report errors to the caller.
.PP
.Vb 1
\&    package My::Module;
.Ve
.PP
.Vb 2
\&    sub foobar {
\&        my $self = shift;
.Ve
.PP
.Vb 1
\&        # some other code...
.Ve
.PP
.Vb 3
\&        return $self\->error('some kind of error...')
\&            if $some_condition;
\&    }
.Ve
.Sh "debug($msg, ...)"
.IX Subsection "debug($msg, ...)"
Generates a debugging message by concatenating all arguments
passed into a string and printing it to \f(CW\*(C`STDERR\*(C'\fR.  A prefix is
added to indicate the module of the caller.
.PP
.Vb 1
\&    package My::Module;
.Ve
.PP
.Vb 2
\&    sub foobar {
\&        my $self = shift;
.Ve
.PP
.Vb 1
\&        $self\->debug('called foobar()');
.Ve
.PP
.Vb 2
\&        # some other code...
\&    }
.Ve
.PP
When the \f(CW\*(C`foobar()\*(C'\fR method is called, the following message
is sent to \f(CW\*(C`STDERR\*(C'\fR:
.PP
.Vb 1
\&    [My::Module] called foobar()
.Ve
.PP
Objects can set an internal \f(CW\*(C`DEBUG\*(C'\fR value which the \f(CW\*(C`debug()\*(C'\fR
method will examine.  If this value sets the relevant bits
to indicate \f(CW\*(C`DEBUG_CALLER\*(C'\fR then the file and line number of
the caller will be appened to the message.
.PP
.Vb 1
\&    use Template::Constants qw( :debug );
.Ve
.PP
.Vb 3
\&    my $module = My::Module\->new({
\&        DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER,
\&    });
.Ve
.PP
.Vb 1
\&    $module\->foobar();
.Ve
.PP
This generates an error message such as:
.PP
.Vb 1
\&    [My::Module] called foobar() at My/Module.pm line 6
.Ve
.Sh "\fImodule_version()\fP"
.IX Subsection "module_version()"
Returns the version number for a module, as defined by the \f(CW$VERSION\fR
package variable.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template