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',
},
);
use Scalar::Util qw( blessed );
use Try::Tiny;
try {
MyException->throw( error => 'I feel funny.' );
}
catch {
die $_ unless blessed $_ && $_->can('rethrow');
if ( $_->isa('Exception::Class') ) {
warn $_->error, "\n", $_->trace->as_string, "\n";
warn join ' ', $_->euid, $_->egid, $_->uid, $_->gid, $_->pid, $_->time;
exit;
}
elsif ( $_->isa('ExceptionWithFields') ) {
if ( $_->quixotic ) {
handle_quixotic_exception();
}
else {
handle_non_quixotic_exception();
}
}
else {
$_->rethrow;
}
};
# without Try::Tiny
eval { ... };
if ( my $e = Exception::Class->caught ) { ... }
# use an alias - without parens subroutine name is checked at
# compile time
throw_fields error => "No strawberry", grandiosity => "quite a bit";
RECOMMENDATION 2: Whether or not you use Throwable, you should use Try::Tiny.
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.
You will also want to look at the documentation for Exception::Class::Base, which is the default base class for all exception objects created by this module.
The syntax for the magic declarations is as follows:
'MANDATORY CLASS NAME' => \%optional_hashref
The hashref may contain the following options:
This is the class's parent class. If this isn't provided then the class name in $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.
This allows you to define additional attributes for your exception class. Any field you define can be passed to the "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.
Specifying an alias causes this class to create a subroutine of the specified name in the caller's namespace. Calling this subroutine is equivalent to calling "<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.
Each exception class has a description method that returns a fixed string. This should describe the exception class (as opposed to any particular exception object). This may be useful for debugging if you start catching exceptions you weren't expecting (particularly if someone forgot to document them) and you don't understand the error messages.
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.
use Exception::Class ( 'My::Exception' );
use Scalar::Util qw( blessed );
use Try::Tiny;
try {
might_throw();
}
catch {
if ( blessed $_ && $_->isa('My::Exception') ) {
handle_it();
}
else {
die $_;
}
};
Note that you cannot use "Exception::Class->caught" with Try::Tiny.
eval {...};
if ( my $e = Exception::Class->caught('My::Error') ) {
cleanup();
do_something_with_exception($e);
}
The "caught" method takes a class name and returns an exception object if the last thrown exception is of the given class, or a subclass of that class. If it is not given any arguments, it simply returns $@.
You should always make a copy of the exception object, rather than using $@ directly. This is necessary because if your "cleanup" function uses "eval", or calls something which uses it, then $@ is overwritten. Copying the exception preserves it for the call to "do_something_with_exception".
Exception objects also provide a caught method so you can write:
if ( my $e = My::Error->caught ) {
cleanup();
do_something_with_exception($e);
}
package Exception::Uncatchable;
sub isa { shift->rethrow }
Of course, this only works if you always call "Exception::Class->caught" after an "eval".
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.
I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
Please note that I am not suggesting that you must do this in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me.
Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time (let's all have a chuckle at that together).
To donate, log into PayPal and send money to autarch@urth.org, or use the button at <http://www.urth.org/~autarch/fs-donation.html>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
The full text of the license can be found in the LICENSE file included with this distribution.