: | $ERROR, $ETYPE, $SNIPPET | ||
: | new(), init(), mandatory(), optional(), error(), throw(), DEBUG(), ID(), INSPECT(), _inspect_ref(), _inspect_hash(), _inspect_list(), _inspect_text() |
package Template::MyModule; use Template::Base; use base qw( Template::Base ); use vars qw( $VERSION $DEBUG $ERROR $ETYPE ); $VERSION = sprintf("%d.%02d", q$Revision$ =~ /(\d+)\.(\d+)/); $DEBUG = 0 unless defined $DEBUG; $ERROR = ''; $ETYPE = 'mymodule'; # exception type sub init { my ($self, $config) = @_; # expects mandatory 'foo' config option $self->mandatory($config, 'foo') || return; # optional 'bar' and 'baz' config options $self->optional($config, 'bar', 'baz') || return; # DIY mandatory argument checking $self->{ THINGY } = $config->{ THINGY } || return $self->error('no THINGY specified!'); return $self; } sub something { my $self = shift; . . . $self->throw('an exception has been thrown') if $something_unexpected_occurred; . . . return $self->error('an error has occured: ', $blah, $blah) if $something_went_wrong; . . . return 1; } package main; my $object = MyModule->new( foo => 'Foo', bar => 'Bar', THINGY => 'xyz' ) || die MyModule->error(); $object->do_something() || die $object->error();
The base class implements a constructor method
new()
which delegates to an initialiser
method, init()
. This is the method that most
subclass will redefine. The mandatory()
and
optional()
methods are available for checking
constructor arguments from the init()
method.
The error()
can be used for general purpose
error reporting and retrieval. The throw()
method throws exceptions, default to the type defined by the
$ETYPE variable in the subclass package.
Various other debug and general utility methods are defined.
DEBUG()
generates debugging messages,
ID()
returns a sensible identifier for an
object and INSPECT()
returns a string
containing a summary of the current object status. The
_inspect_hash()
, _inspect_list()
and _inspect_text()
methods provide an easy
way of inspecting the contents of a hash, list or text block,
respectively.
new()
constructor method, for example.
You can inspect or manipulate this variable directly, or
indirectly by calling the error()
method
as a class method.
# same Template::MyModule->error('set an error'); $Template::MyModule::ERROR = 'set an error'; # same print Template::MyModule->error(); print $Template::MyModule::ERROR;
throw()
.
_inspect_text()
method.
The default value is 32 (characters).
new( \%config )
new( key => value, key => value, ... )
General purpose constructor method which expects a hash
reference of configuration parameters, or a list of
key => value
pairs which are
automatically folded into a hash. Blesses a hash into an
object and calls its init()
method, passing
the reference to the hash array of configuration parameters.
Returns a new object derived from Template::Base or undef on
error.
Example:
use Template::MyModule; my $obj = Template::MyModule->new({ FOO => 'bar' });
my $obj = Template::MyModule->new( FOO => 'bar' );
init( \%config )
Initialisation method called by the new()
constructor, passing a reference to a hash array containing
any configuration items specified as constructor arguments.
Should return $self on success or undef on error, usually
via a call to the error() method which sets an error message
and returns undef.
mandatory( \%config, \@keys )
mandatory( \%config, $key1, $key2, ... )
Copies mandatory fields from the configuration hash passed by
reference as the first argument into $self
.
A list of keys to denote the mandatory fields can be passed as
further arguments or as a reference to a list of arguments.
Raises an error if any of the arguments specified are not
defined in the $config
hash.
optional( \%config, \@keys )
optional( \%config, \%keys )
optional( \%config, $key1, $key2, ... )
Copies optional fields from the configuration hash passed by
reference as the first argument into
$self
. A list of keys to denote the
optional fields can be passed as further arguments or as a
reference to a list or hash array. If a reference to a hash
array is passed then the values contained therein are used as
defaults if the relevant item doesn't exist in the
$config
hash.
error( )
error( $msg, $msg, ... )
This can be called as either a class or object method to get
or set the value of the package variable
$ERROR
(class method) or internal
$self->{ _ERROR }
item (object method).
Returns the current value when called without any arguments.
Updates the value and returns undef when called with one or
more arguments.
package Template::MyModule; use base qw( Template::Base ); sub do_something { my $self = shift; . . . return $self->error('An error has occured: ', $blah, $blah) if $something_went_wrong; . . . return 1; } package main; my $mod = Template::MyModule->new(); $mod->do_something() || die $mod->error(), "\n";
throw( $message )
throw( $msg, $msg, ... )
Throws an exception by calling die() with an exception object
of the
$mod->throw($exception); $mod->throw("I'm sorry Dave, I can't do that"); $mod->throw('denied', "I'm sorry Dave, I can't do that");
An optional third parameter can be supplied which is a reference to the current output buffer. This is used by the template processing mechanism to buffer the results of processing a template up to the point at which the exception was thrown. The RETURN and STOP directives, for example, use this to propagate output back to the user. In most cases, you can safely ignore it
This method rides on a one-way ticket to die() oblivion. It does not return.
DEBUG()
Debugging method prints all arguments to STDERR.
$self->DEBUG("testing 1..2..3..\n") if $DEBUG;
ID()
Returns a string identifying an object.
$self->DEBUG($self->ID, "->testing('1..2..3..')\n") if $DEBUG;
INSPECT()
Returns a string detailing the state and contents of the object.
$self->DEBUG( $self->INSPECT() ) if $DEBUG;
_inspect_ref( $ref )
Returns a string detailing the content of a reference passed as
an argument. The reference may be to a hash array, list or object.
$self->DEBUG( $self->_inspect_ref($myref) ) if $DEBUG;
_inspect_hash( \%hash )
Returns a string detailing the contents of a hash array passed
by reference.
$self->DEBUG( $self->_inspect_hash(\%myhash) ) if $DEBUG;
_inspect_list( \@list )
Returns a string detailing the contents of a list passed
by reference.
$self->DEBUG( $self->_inspect_list(\@mylist) ) if $DEBUG;
_inspect_text( $text )
_inspect_text( $text, $length )
Returns a string containing the text string passed, truncated
to $length
characters or
$SNIPPET
characters if
$length
is not specified. If the text
is truncated then '...' is appended to it.
$self->DEBUG( $self->_inspect_text($text) ) if $DEBUG; $self->DEBUG( $self->_inspect_text($text, 64) ) if $DEBUG;