Class(3)

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' }                                  );
  eval { MyException->throw( error => 'I feel funny.'; };
  print $@->error, "\n";
  MyException->trace(1);
  eval { MyException->throw( error => 'I feel funnier.'; };
  print $@->error, "\n", $@->trace->as_string, "\n";
  print join ' ',  $@->euid, $@->egid, $@->uid, $@->gid, $@->pid, $@->time;
  # catch
  if ($@->isa('MyException'))
  {
     do_something();
  }
  elsif ($@->isa('FooException'))
  {
     go_foo_yourself();
  }
  else
  {
     $@->rethrow;
  }

DESCRIPTION
Exception::Class allows you to declare exceptions in your modules in a manner similar to how exceptions are declared in Java.

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 used for classes stored in files (aka modules ;) ) that are subclasses.

It is designed to make structured exception handling simpler and better by encouraging people to use hierarchies of exceptions in their applications.

NOTE: This module does not implement any try/catch syntax. Please see the the catch syntax) entry in the OTHER EXCEPTION MODULES (try manpage for more information on how to get this syntax.

DECLARING EXCEPTION CLASSES
The 'use Exception::Class' syntax lets you automagically create the relevant Exception::Class::Base subclasses. You can also create subclasses via the traditional means of external modules loaded via 'use'. These two methods may be combined.

The syntax for the magic declarations is as follows:

'MANDATORY CLASS NAME' => \%optional_hashref

The hashref may contain two options: This is the class's parent class. If this isn't provided then the class name is $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 a Exception::Class::Base class loaded from a file, then you _must_ compile the class (via use or require or some other magic) _before_ you do 'use Exception::Class' or you'll get a compile time error. This may change with the advent of Perl 5.6's CHECK blocks, which could allow even more crazy automagicalness (which may or may not be a good thing). Each exception class has a description method that returns a fixed string. This should describe the exception _class_ (as opposed to the particular exception being thrown). This is 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 so if you declare Bar to be a subclass of Foo and never declare Foo then it will also die. My tests indicate that this is functioning properly but this functionality is still somewhat experimental.

Exception::Class::Base CLASS METHODS
Each Exception::Class::Base subclass can be set individually to make a Devel::StackTrace object when an exception is thrown. The default is to not make a trace. Calling this method with a value changes this behavior. It always returns the current value (after any change is applied). This method creates a new 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. Returns a new Exception::Class::Base object with the given error message. If no error message is given, $! is used. Returns the description for the given 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.

Exception::Class::Base OBJECT METHODS
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. Returns the error message associated with the exception. Returns the pid at the time the exception was thrown. Returns the real user id at the time the exception was thrown. Returns the real group id at the time the exception was thrown. Returns the effective user id at the time the exception was thrown. Returns the effective group id at the time the exception was thrown. Returns the time in seconds since the epoch at the time the exception was thrown. Returns the package from which the exception was thrown. Returns the file within which the exception was thrown. Returns the line where the exception was thrown. Returns the trace object associated with the Exception::Class::Base if do_trace was true at the time it was created or undef. Returns a string form of the error message (something like what you'd expect from die). If there is a trace available then it also returns this in string form (like Carp::confess).

OVERLOADING
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').

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. This allows you to more easily see what exceptions you have and makes it easier to keep track of them all (as opposed to looking at the top of 10-20 different files). It's also ever so slightly faster as the Class::Exception->import method doesn't get called over and over again (though a given class is only ever made once).

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. Read the the DECLARING EXCEPTION CLASSES entry elsewhere in this document for more details.

OTHER EXCEPTION MODULES (try/catch syntax)
If you are interested in adding try/catch/finally syntactic sugar to your code then I recommend you check out Graham Barr's Error module, which implements this syntax. It also includes its own base exception class, Error::Simple, but you should be able to use Exception::Class::Base along with his try/catch routines transparently. If you encounter any issues in getting these two to work together, please let me know (and maybe Graham as well) and I will fix this.

AUTHOR
Dave Rolsky, <autarch@urth.org>

SEE ALSO
Devel::StackTrace