oracular (3) Badger::Exception.3pm.gz
NAME
Badger::Exception - structured exception for error handling
SYNOPSIS
use Badger::Exception;
# create exception object
my $exception = Badger::Exception->new({
type => $type,
info => $info,
});
# query exception type and info fields
$type = $exception->type();
$info = $exception->info();
($type, $info) = $exception->type_info();
# print string summarising exception
print $exception->text();
# use automagic stringification
print $exception;
# throw exception
$exception->throw;
DESCRIPTION
This module defines an object class for representing exceptions. These are simple objects that store
various bits of information about an error condition.
The "type" denotes what kind of error occurred (e.g. '"file"', '"parser"', '"database"', etc.). The
"info" field provides further information about the error (e.g. '"foo/bar.html not found"', '"parser
error at line 42"', '"server is on fire"', etc). Other optional fields include "file" and "line" for
specifying the location of the error.
In most cases you wouldn't generate and/or throw an exception object directly from your code. A better
approach is to define a "throw()" method in a base class which does this for you.
The Badger::Base module is an example of just such a module. You can use this as a base class for your
modules to inherit the throw() method.
Here's an example of a module that implements a method which expects an argument. If if doesn't get the
argument it's looking for then it throws an exception via the inherited throw() method. The exception
type is "example" and the additional information is "No argument specified".
package Your::Module;
use base 'Badger::Base';
sub example_method {
my $self = shift;
my $arg = shift
|| self->throw( example => 'No argument specified' );
# ...do something with ...
}
The error() provides a higher level of abstraction. You provide the error message (which becomes the
exception "info") and it will generate an exception type based on the package name of your module.
package Your::Module;
use base 'Badger::Base';
sub example_method {
my $self = shift;
my $arg = shift
|| self->error('No argument specified' );
# ...do something with ...
}
In the example above, an exception will be thrown with a "type" defined as "your.module". The module
name is converted to lower case and the package delimiters are replaced with dots. There are
configuration options that allow you to define other exceptions types. Consult the Badger::Base
documentation for further information.
You can choose any values you like for "type" and "info". The "type" is used to identify what kind of
error occurred and should be a short word like ""example"", or a dot-separated sequence of words like
""example.file.missing"". In the latter case, dotted exception types are assumed to represent a hierarchy
where "example.file.missing" error is a more specialised kind of "example.file" error, which in turn is a
more specialised kind of "example" error. The match_type() method takes this into account when matching
exception types.
eval {
# some code that throws an exception
};
if ($@) {
if ($@->match_type('example')) {
# caught 'example' or 'example.*' error
# ...now do something
}
else {
# re-throw any other exception types
$@->throw;
}
}
The "info" field should provide a more detailed error message in a format suitable for human consumption.
STACK TRACING
The "Badger::Exception" module also has a tracing mode which will automatically save the caller stack at
the point at which the error is thrown. This allows you to inspect the full code path which led to the
error from the comfort of you exception catching code, rather than having to deal with it at the point
where the error is throw.
# deep in your code somewhere.... in a class derived from Badger::Base
$self->throw(
database => 'The database is made of cheese',
trace => 1,
);
The "text()" method (which is called whenever the object is stringified) will then append a stack track
to the end of the generated message.
# high up in your calling code:
eval { $object->do_something_gnarly };
if ($err = $@) {
print $err;
exit;
}
You can also call the stack() method to return the stored call stack information, or the stack_trace()
method to see a textual summary.
You can enable the tracing behaviour for all exception objects by setting the $TRACE package variable.
use Badger::Exception;
$Badger::Exception::TRACE = 1;
The trace import hook is provided as a short-cut for this.
use Badger::Exception trace => 1;
IMPORT HOOKS
trace
This import hook can be used to set the $TRACE package variable to enable stack tracing for the
Badger::Exception module.
use Badger::Exception trace => 1
When stack tracing is enabled, the exception will store information about the calling stack at the point
at which it is thrown. This information will be displayed by the text() method. It is also available in
raw form via the stack() method.
METHODS
new()
Constructor method for creating a new exception.
my $exception = Badger::Exception->new(
type => 'database',
info => 'could not connect',
file => '/path/to/file.pm',
line => 420,
);
type()
When called without arguments, this method returns the exception type, as defined by the first argument
passed to the "new()" constructor method.
my $type = $exception->type();
It can also be called with an argument to set a new type for the exception.
$exception->type('database');
info()
When called without arguments, this method returns the information field for the exception.
my $info = $exception->info();
It can also be called with an argument to define new information for the exception.
$exception->info('could not connect');
file()
Method to get or set the name of the file in which the exception was raised.
$exception->file('path/to/file.pm');
print $exception->file; # /path/to/file.pm
line()
Method to get or set the line number at which the exception was raised.
$exception->line(420);
print $exception->line; # 420
text()
This method returns a text representation of the exception object. The string returned is formatted as
"$type error - $info".
print $exception->text(); # database error - could not connect
This method is also bound to the stringification operator, allowing you to simple "print" the exception
object to get the same result as calling "text()" explicitly.
print $exception; # database error - could not connect
trace()
Method to get or set the flag which determines if the exception captures a stack backtrace at the point
at which it is thrown. It can be called as an object method to affect an individual exception object, or
as a class method to get or set the $TRACE package variable which provides the default value for any
exceptions created from then on.
$exception->trace(1); # object method
print $exception->trace; # 1
Badger::Exception->trace(1); # class method - sets $TRACE
print Badger::Exception->trace; # 1
match_type()
This method selects and returns a type string from the arguments passed that is the nearest correct match
for the current exception type. This is used to select the most appropriate handler for the exception.
my $match = $exception->match_type('file', 'parser', 'database')
|| die "no match for exception\n";
In this example, the exception will return one of the values "file", "parser" or "database", if and only
if its type is one of those values. Otherwise it will return undef;
Exception types can be organised into a hierarchical structure by delimiting each part of the type with a
period. For example, the "database" exception type might be further divided into the more specific
"database.connection", "database.query" and "database.server_on_fire" exception types.
An exception of type "database.connection" will match a handler type of "database.connection" or more
generally, "database". The longer (more specific) handler name will always match in preference to a
shorter (more general) handler as shown in the next example:
$exception->type('database.connection');
my $match = $exception->match_type('database', 'database.connection')
|| die "no match for exception\n";
print $match; # database.connection
When there is no exact match, the "match_type()" method will return something more general that matches.
In the following example, there is no specific handler type for "database.exploded", but the more general
"database" type still matches.
$exception->type('database.exploded');
my $match = $exception->match_type('database', 'database.connection')
|| die "no match for exception\n";
print $match; # database
You can also specify multiple exception types using a reference to a list.
if ($exception->match_type(['warp.drive', 'shields'])) {
...
}
Or using a single string of whitespace delimited exception types.
if ($exception->match_type('warp.drive shields')) {
...
}
You can also pass a reference to a hash array in which the keys are exception types. The corresponding
value for a matching type will be returned.
my $type_map = {
'warp.drive' => 'propulsion',
'impulse.drive' => 'propulsion',
'shields' => 'defence',
'phasers' => 'defence'
};
if ($exception->match_type($type_map)) {
...
}
throw()
This method throws the exception by calling "die()" with the exception object as an argument. If the
$TRACE flag is set to a true value then the method will first save the pertinent details from a stack
backtrace into the exception object before throwing it.
stack()
If stack tracing is enabled then this method will return a reference to a list of information from the
caller stack at the point at which the exception was thrown. Each item in the list is a reference to a
list containing the information returned by the inbuilt "caller()" method. See "perldoc -f caller" for
further information.
use Badger::Exception trace => 1;
eval {
# some code that throws an exception object
$exception->throw();
};
my $catch = $@; # exception object
my $stack = $catch->stack;
foreach my $caller (@$stack) {
my ($pkg, $file, $line, @other_stuff) = @$caller;
# do something
}
The first set of information relates to the immediate caller of the throw() method. The next item is the
caller of that method, and so on.
stack_trace()
If stack tracing is enabled then this method returns a text string summarising the caller stack at the
point at which the exception was thrown.
use Badger::Exception trace => 1;
eval {
# some code that throws an exception object
$exception->throw();
};
if ($@) {
print $@->stack_trace;
}
AUTHOR
Andy Wardley <http://wardley.org/>
COPYRIGHT
Copyright (C) 1996-2009 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
SEE ALSO
Badger::Base