Inline Exceptions

  use Class::Throwable ('My::InlineException', 'My::Other::InlineException');

This is a quick and easy way to define arbitrary exception classes without the need to manually create separate files or packages for them. However, it should be noted that subclasses of Class::Throwable cannot be used to define inline exceptions. If you attempt to do this, an exception will be thrown.

Exception Verbosity

There are a number of ways in which you can set the verbosity of the exceptions produced by Class::Throwable. The simplest way is as the argument to the "toString" method. Using this method will override any other settings you may have, and insure that the output of this method is as you ask it to be.

  $@->toString(2);

However, to use this style properly, this requires that you test the value of $@ to be sure it is a Class::Throwable object. In some cases, this may not be an issue, while in others, it makes more sense to set verbosity on a wider scale.

For instance, if you define inline exceptions, then the simplest way to set a verbostity level for a particular inline exception is through the class method "setVerbosity".

  use Class::Throwable qw(My::InlineException);
  
  My::InlineException->setVerbosity(2);

This means that unless the "toString" verbosity argument overrides it, all My::InlineException exceptions will use a verbosity setting of 2. This method means that you can easily "print" the value of $@ and then any My::InlineException exceptions will be automatically stringified with a verbosity level of 2. This can simplify exception catching by reducing the need to inspect the value of $@.

If you defined your exceptions as subclasses of Class::Throwable and stored them in separate files, then another means of setting the verbosity level is to assign it in the "use" statement.

  use My::SeparateFileSubClass::Exception (VERBOSE => 2);

This has the same effect as the "setVerbosity" class method, in fact, there is nothing to stop you from using the "setVerbosity" class method in this case if you like. This method can also be used on Class::Throwable itself, however, this does not set the verbosity level for all subclasses, only for Class::Throwable exceptions.

There is one last method which can be used. This method has the widest scope of all the methods. The variable $Class::Throwable::DEFAULT_VERBOSITY can be set. Setting this value will take effect if, 1) there is no value passed to the "toString" method and 2) no verbosity level has been set for the particular class, either through "setVerbosity" or the "use" statement.

Module exception retro-fitting

NOTE: It is important to do module retrofitting at the earliest possible moment (preferrably before the module you are retrofitting is compiled), as it will override "die" within a specified package.

Other than all this, retrofitting is quite simple. Here is a basic example:

  use Class::Throwable retrofit => 'My::Class';

Now anytime "die" is called within My::Class the calls will get converted to a Class::Throwable instance. You can also control how exceptions are converted like so:

  use Class::Throwable retrofit => 'My::Class' => sub { My::Exception->throw(@_) };

Now anytime "die" is called within My::Class the calls will get converted to a My::Exception instance instead. Or a slightly more complex examples like this:

  use Class::Throwable retrofit => (
                'My::Class' => sub { 
                    My::IllegalOperation->throw(@_) if $_[0] =~ /^Illegal Operation/;
                    My::Exception->throw(@_);
                });

Now anytime "die" is called within My::Class the calls will get converted to a My::Exception instance unless the exception matches the reg-exp, in which case an My::IllegalOperation exception is thrown.

There are a couple of points to be made regarding this functionality. First, it will add another stack frame to your exceptions (the retrofit routine basically). This is probably avoidable, but as this is still experimental I wanted to keep things somewhat simple. And second, if you supply a custom "die" handler, you should be sure that it will "die" somewhere within that routine. If you do not, you may have many un-intended consequences.

Constructor

throw ($message, $sub_exception)

The most common way to construct an exception object is to "throw" it. This method will construct the exception object, collect all the information from the call stack and then "die".

The optional $message argument can be used to pass custom information along with the exception object. Commonly this will be a string, but this module makes no attempt to enforce that it be anything other than a scalar, so more complex references or objects can be used. If no $message is passed in, a default one will be constructed for you.

The second optional argument, $sub_exception, can be used to retain information about an exception which has been caught but might not be appropriate to be re-thrown and is better wrapped within a new exception object. While this argument will commonly be another Class::Throwable object, that fact is not enforced so you can pass in normal string based perl exceptions as well.

If this method is called as an instance method on an exception object pre-built with "new", only then is the stack trace information populated and the exception is then passed to "die".

new ($message, $sub_exception)

This is an alternate means of creating an exception object, it is much like "throw", except that it does not collect stack trace information or "die". It stores the $message and $sub_exception values, and then returns the exception instance, to be possibly thrown later on.

Class Methods

setVerbosity ($verbosity)

This is a class method, if it is called with an instance, and exception will be thrown. This class method can be used to set the verbosity level for a particular class. See the section "Exception Verbosity" above for more details.

Accessors

getMessage

This allows access to the message in the exception, to allow more granular exception reporting.

getStackTrace

This returns the raw stack trace information as an array of arrays. There are 10 values returned by "caller" ($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext, $is_require, $hints, $bitmask) we do not bother to capture the last two as they are subject to change and meant for internal use, all others are retained in the order returned by "caller".

hasSubException

The returns true (1) if this exception has a sub-exception, and false (0) otherwise.

getSubException

This allows access to the stored sub-exception.

Output Methods

toString ($verbosity)

This will print out the exception object's information at a variable level of verbosity which is specified be the optional argument $verbosity. See the section "Exception Verbosity" above for more details.

stringValue

This will return the normal perl stringified value of the object without going through the "toString" method.

stackTraceToString

This method is used to print the stack trace information, the stack trace is presented in the following format:

    |--[ main::foo called in my_script.pl line 12 ]
    |--[ main::bar called in my_script.pl line 14 ]
    |--[ main::baz called in my_script.pl line 16 ]