On Apache
Under GNU General Public License
2012-05-23 17:02 @38.107.179.236 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
Exception::Class(3pm) User Contributed Perl Documentation Exception::Class(3pm)
NAME
Exception::Class - A module that allows you to declare real exception classes in Perl
SYNOPSIS
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.' ) };
my $e;
# catch
if ( $e = Exception::Class->caught('MyException') )
{
warn $e->error, "\n", $e->trace->as_string, "\n";
warn join ' ', $e->euid, $e->egid, $e->uid, $e->gid, $e->pid, $e->time;
exit;
}
elsif ( $e = Exception::Class->caught('ExceptionWithFields') )
{
$e->quixotic ? do_something_wacky() : do_something_sane();
}
else
{
$e = Exception::Class->caught();
ref $e ? $e->rethrow : die $e;
}
# use an alias - without parens subroutine name is checked at
# compile time
throw_fields error => "No strawberry", grandiosity => "quite a bit";
DESCRIPTION
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 com-
pile 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 MOD-
ULES (try/catch syntax)" section for more information on how to get this syntax.
DECLARING EXCEPTION CLASSES
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:
* isa
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 $Excep-
tion::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.
* fields
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.
* alias
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.
* description
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 expect-
ing (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.
Catching Exceptions
"Exception::Class" provides some syntactic sugar for catching exceptions in a safe manner:
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);
}
Uncatchable Exceptions
Internally, the "caught()" method will call "isa()" on the exception object. You could
make an exception "uncatchable" by overriding "isa()" in that class like this:
package Exception::Uncatchable;
sub isa { shift->rethrow }
Of course, this only works if you always call "Exception::Class->caught()" after an
"eval".
Exception::Class::Base CLASS METHODS
* Trace($boolean)
Each "Exception::Class::Base" subclass can be set individually to include a a strack-
trace when the "as_string" method is called. The default is to not include a stack-
trace. 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 sub-
class, it will thereafter be independent of the value in "Exception::Class::Base".
This is a class method, not an object method.
* NoRefs($boolean)
When a "Devel::StackTrace" object 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 pro-
vides 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.
* RespectOverload($boolean)
When a "Devel::StackTrace" object stringifies, by default it ignores stringification
overloading on any objects being dealt with.
Since "Exception::Class::Base" uses "Devel::StackTrace" internally, this method pro-
vides a way to tell "Devel::StackTrace" to respect overloading.
This method defaults to false. As with "Trace()", it is inherited by subclasses but
setting it in a subclass makes it independent thereafter.
* MaxArgLength($boolean)
When a "Devel::StackTrace" object stringifies, by default it displays the full argu-
ment for each function. This parameter can be used to limit the maximum length of each
argument.
Since "Exception::Class::Base" uses "Devel::StackTrace" internally, this method pro-
vides a way to tell "Devel::StackTrace" to limit the length of arguments.
This method defaults to 0. As with "Trace()", it is inherited by subclasses but set-
ting it in a subclass makes it independent thereafter.
* Fields
This method returns the extra fields defined for the given class, as an array.
* throw( $message )
* throw( message => $message )
* throw( error => $error )
This method creates a new 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.
The frames included in the trace can be controlled by the "ignore_class" and
"ignore_package" parameters. These are passed directly to Devel::Stacktrace's con-
structor. See "Devel::Stacktrace" for more details.
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 sub-
class will also be accepted.
* new
This method takes the same parameters as "throw()", but instead of dying simply
returns a new exception object.
This method is always called when constructing a new exception object via the
"throw()" method.
* description
Returns the description for the given "Exception::Class::Base" subclass. The "Excep-
tion::Class::Base" class's description is "Generic exception" (this may change in the
future). This is also an object method.
Exception::Class::Base OBJECT METHODS
* rethrow
Simply dies with the object as its sole argument. It's just syntactic sugar. This
does not change any of the object's attribute values. However, it will cause
"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.
* message
* error
Returns the error/message associated with the exception.
* pid
Returns the pid at the time the exception was thrown.
* uid
Returns the real user id at the time the exception was thrown.
* gid
Returns the real group id at the time the exception was thrown.
* euid
Returns the effective user id at the time the exception was thrown.
* egid
Returns the effective group id at the time the exception was thrown.
* time
Returns the time in seconds since the epoch at the time the exception was thrown.
* package
Returns the package from which the exception was thrown.
* file
Returns the file within which the exception was thrown.
* line
Returns the line where the exception was thrown.
* trace
Returns the trace object associated with the object.
* show_trace($boolean)
This method can be used to set whether or not a strack trace is included when the
as_string method is called or the object is stringified.
* as_string
Returns a string form of the error message (something like what you'd expect from
die). If the class or object is set to show traces then then the full trace is also
included. The result looks like "Carp::confess()".
* full_message
Called by the "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.
OVERLOADING
The "Exception::Class::Base" object is overloaded so that stringification produces a nor-
mal 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()").
OVERRIDING THE as_string METHOD
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;
}
USAGE RECOMMENDATION
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, partic-
ularly if you want your exceptions to have more methods.
Subclassing Exception::Class::Base
As part of your usage of "Exception::Class", you may want to create your own base excep-
tion class which subclasses "Exception::Class::Base". You should feel free to subclass
any of the methods documented above. For example, you may want to subclass "new()" to add
additional information to your exception objects.
Exception::Class FUNCTIONS
The "Exception::Class" method offers one function, "Classes()", which is not exported.
This method returns a list of the classes that have been created by calling the "Excep-
tion::Class" import() method. Note that this is all the subclasses that have been cre-
ated, so it may include subclasses created by things like CPAN modules, etc. Also note
that if you simply define a subclass via the normal Perl method of setting @ISA or "use
base", then your subclass will not be included.
OTHER EXCEPTION MODULES (try/catch syntax)
If you are interested in adding try/catch/finally syntactic sugar to your code then I rec-
ommend 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'
unless Exception::Class::Base->isa('Error');
It's a hack but apparently it works.
SUPPORT
Please submit bugs to the CPAN RT system at http://rt.cpan.org/NoAuth/Report-
Bug.html?Queue=Exception%3A%3AClass or via email at bug-exception-class AT rt.org.
AUTHOR
Dave Rolsky, <autarch AT urth.org>
COPYRIGHT
Copyright (c) 2000-2006 David Rolsky. All rights reserved. This program is free soft-
ware; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
perl v5.8.8 2008-04-01 Exception::Class(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-23 17:02 @38.107.179.236 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)