.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Base 3"
.TH Template::Base 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.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 );
\&
\&    sub _init {
\&        my ($self, $config) = @_;
\&        $self\->{ doodah } = $config\->{ doodah }
\&            || return $self\->error("No \*(Aqdoodah\*(Aq specified");
\&        return $self;
\&    }
\&
\&    package main;
\&
\&    my $object = My::Module\->new({ doodah => \*(Aqfoobar\*(Aq })
\&        || 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"
.SS 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_init()\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 \fBerror()\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";
\&
\&    my $module = My::Module\->new({ ... })
\&        || die "constructor error: $My::Module::ERROR\en";
.Ve
.SS "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";
\&
\&    $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;
\&
\&    sub foobar {
\&        my $self = shift;
\&
\&        # some other code...
\&
\&        return $self\->error(\*(Aqsome kind of error...\*(Aq)
\&            if $some_condition;
\&    }
.Ve
.SS "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;
\&
\&    sub foobar {
\&        my $self = shift;
\&
\&        $self\->debug(\*(Aqcalled foobar()\*(Aq);
\&
\&        # some other code...
\&    }
.Ve
.PP
When the \f(CWfoobar()\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(CWdebug()\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 append to the message.
.PP
.Vb 1
\&    use Template::Constants qw( :debug );
\&
\&    my $module = My::Module\->new({
\&        DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER,
\&    });
\&
\&    $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
.SS \fBmodule_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\-2022 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