Exception::Class - A module that allows you to declare real exception classes in Perl |
Exception::Class - A module that allows you to declare real exception classes in Perl
use Exception::Class ( 'MyException',
'AnotherException' => { isa => 'MyException' },
'YetAnotherException' => { isa => 'AnotherException', description => 'These exceptions are related to IPC' },
'ExceptionWithFields' => { isa => 'YetAnotherException', fields => [ 'grandiosity', 'quixotic' ], alias => 'throw_fields', );
# try eval { MyException->throw( error => 'I feel funny.'; };
# catch if ( UNIVERSAL::isa( $@, 'MyException' ) ) { warn $@->error, "\n, $@->trace->as_string, "\n"; warn join ' ', $@->euid, $@->egid, $@->uid, $@->gid, $@->pid, $@->time;
exit; } elsif ( UNIVERSAL::isa( $@, 'ExceptionWithFields' ) ) { $@->quixotic ? do_something_wacky() : do_something_sane(); } else { ref $@ ? $@->rethrow : die $@; }
# use an alias - without parens subroutine name is checked at # compile time throw_fields error => "No strawberry", grandiosity => "quite a bit";
Exception::Class allows you to declare exception hierarchies in your modules in a ``Java-esque'' manner.
It features a simple interface allowing programmers to 'declare' exception classes at compile time. It also has a base exception class, Exception::Class::Base, that can be easily extended.
It is designed to make structured exception handling simpler and better by encouraging people to use hierarchies of exceptions in their applications, as opposed to a single catch-all exception class.
This module does not implement any try/catch syntax. Please see the ``OTHER EXCEPTION MODULES (try/catch syntax)'' section for more information on how to get this syntax.
Importing Exception::Class
allows you to automagically create
Exception::Class::Base
subclasses. You can also create subclasses
via the traditional means of defining your own subclass with @ISA
.
These two methods may be easily combined, so that you could subclass
an exception class defined via the automagic import, if you desired
this.
The syntax for the magic declarations is as follows:
'MANDATORY CLASS NAME' => \%optional_hashref
The hashref may contain the following options:
$Exception::Class::BASE_EXC_CLASS
is assumed to be
the parent (see below).
This parameter lets you create arbitrarily deep class hierarchies.
This can be any other Exception::Class::Base
subclass in your
declaration or a subclass loaded from a module.
To change the default exception class you will need to change the
value of $Exception::Class::BASE_EXC_CLASS
before calling import
.
To do this simply do something like this:
BEGIN { $Exception::Class::BASE_EXC_CLASS = 'SomeExceptionClass'; }
If anyone can come up with a more elegant way to do this please let me know.
CAVEAT: If you want to automagically subclass an
Exception::Class::Base
subclass loaded from a file, then you
must compile the class (via use or require or some other magic)
before you import Exception::Class
or you'll get a compile time
error.
throw
or new
methods as additional parameters for the constructor. In addition,
your exception object will have an accessor method for the fields you
define.
This parameter can be either a scalar (for a single field) or an array reference if you need to define multiple fields.
Fields will be inherited by subclasses.
<class>->throw(@_)
for the given
exception class.
Besides convenience, using aliases also allows for additional compile
time checking. If the alias is called without parentheses, as in
throw_fields "an error occurred"
, then Perl checks for the
existence of the throw_fields()
subroutine at compile time. If
instead you do ExceptionWithFields->throw(...)
, then Perl
checks the class name at runtime, meaning that typos may sneak
through.
The Exception::Class
magic attempts to detect circular class
hierarchies and will die if it finds one. It also detects missing
links in a chain, for example if you declare Bar to be a subclass of
Foo and never declare Foo.
Trace($boolean)
Exception::Class::Base
subclass can be set individually to
include a a stracktrace when the as_string
method is called. The
default is to not include a stacktrace. Calling this method with a
value changes this behavior. It always returns the current value
(after any change is applied).
This value is inherited by any subclasses. However, if this value is
set for a subclass, it will thereafter be independent of the value in
Exception::Class::Base
.
This is a class method, not an object method.
NoRefs($boolean)
Devel::StackTrace
is created, it walks through the stack and
stores the arguments which were passed to each subroutine on the
stack. If any of these arguments are references, then that means that
the Devel::StackTrace
ends up increasing the refcount of these
references, delaying their destruction.
Since Exception::Class::Base
uses Devel::StackTrace
internally,
this method provides a way to tell Devel::StackTrace
not to store
these references. Instead, Devel::StackTrace
replaces references
with their stringified representation.
This method defaults to true. As with Trace
, it is inherited by
subclasses but setting it in a subclass makes it independent
thereafter.
Exception::Class::Base
object with the
given error message. If no error message is given, $!
is used. It
then die's with this object as its argument.
This method also takes a show_trace
parameter which indicates
whether or not the particular exception object being created should
show a stacktrace when its as_string
method is called. This
overrides the value of Trace
for this class if it is given.
If only a single value is given to the constructor it is assumed to be the message parameter.
Additional keys corresponding to the fields defined for the particular exception subclass will also be accepted.
throw
, but instead of
dying simply returns a new exception object.
Exception::Class::Base
subclass. The Exception::Class::Base
class's description is
``Generic exception'' (this may change in the future). This is also an
object method.
caller
to report the die as coming from
within the Exception::Class::Base
class rather than where rethrow
was called.
Of course, you always have access to the original stacktrace for the exception object.
show_trace($boolean)
Carp::confess
.
as_string
method to get the message. By default,
this is the same as calling the message
method, but may be
overridden by a subclass. See below for details.
The Exception::Class::Base
object is overloaded so that
stringification produces a normal error message. It just calls the
as_string method described above. This means that you can just
print $@
after an eval and not worry about whether or not its an
actual object. It also means an application or module could do this:
$SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
and this would probably not break anything (unless someone was
expecting a different type of exception object from die
).
By default, the as_string
method simply returns the value
message
or error
param plus a stack trace, if the class's
Trace
method returns a true value or show_trace
was set when
creating the exception.
However, once you add new fields to a subclass, you may want to include those fields in the stringified error.
Inside the as_string
method, the message (non-stack trace) portion
of the error is generated by calling the full_message
method. This
can be easily overridden. For example:
sub full_message { my $self = shift;
my $msg = $self->message;
$msg .= " and foo was " . $self->foo;
return $msg; }
If you're creating a complex system that throws lots of different
types of exceptions, consider putting all the exception declarations
in one place. For an app called Foo you might make a
Foo::Exceptions
module and use that in all your code. This module
could just contain the code to make Exception::Class
do its
automagic class creation. Doing this allows you to more easily see
what exceptions you have, and makes it easier to keep track of them.
This might look something like this:
package Foo::Bar::Exceptions;
use Exception::Class ( Foo::Bar::Exception::Senses => { description => 'sense-related exception' },
Foo::Bar::Exception::Smell => { isa => 'Foo::Bar::Exception::Senses', fields => 'odor', description => 'stinky!' },
Foo::Bar::Exception::Taste => { isa => 'Foo::Bar::Exception::Senses', fields => [ 'taste', 'bitterness' ], description => 'like, gag me with a spoon!' },
... );
You may want to create a real module to subclass
Exception::Class::Base
as well, particularly if you want your
exceptions to have more methods.
If you are interested in adding try/catch/finally syntactic sugar to
your code then I recommend you check out U. Arun Kumar's Error.pm
module, which implements this syntax. It also includes its own base
exception class, Error::Simple
.
If you would prefer to use the Exception::Class::Base
class
included with this module, you'll have to add this to your code
somewhere:
push @Exception::Class::Base::ISA, 'Error';
It's a hack but apparently it works.
Dave Rolsky, <autarch@urth.org>
Devel::StackTrace - used by this module to create stack traces
Error.pm - implements try/catch in Perl. Also provides an exception base class.
Test::Exception - a module that helps you test exception based code.
Numerous other modules/frameworks seem to have their own exception classes (SPOPS and Template Toolkit, to name two) but none of these seem to be designed for use outside of these packages.
Exception::Class - A module that allows you to declare real exception classes in Perl |