/ 
Exception-1.00
River stage zero No dependents
/ Exception

NAME

Exception - Exception handling and a base exception class.

SYNOPSIS

use Exception qw(try catch throw);

try { throw(new Exception('Error.')); };
if(catch(qw(Exception e))) { 
  print 'Caught: ',$e->as_string(),"\n";
}
elsif(catch()) {
  print 'Caught Unknown: ',$@,"\n";
}

DESCRIPTION

Exception handling routines. Execute try blocks, throw exceptions and catch them. This module also provides a base exception object.

API REFERENCE

new

throw(new Exception('Error: ',$!));

Construct a new exception object. During construction, the object will capture the caller's state information, including a stacktrace by using the caller() function.

_exception__capture_exception_information

this is an internal function called by new() that actualy does the work of capturing the stacktrace and other state information. The information is then stored into the exception object.

get_stacktrace

my @stack = Exception->get_stacktrace();

This method is called by _exception__capture_exception_information() during construction to capture the stacktrace. It returns an array of array references that represents the captured stacktrace. It can be invoked either as a method on an exception object, or as a package method (as the example above shows).

stacktrace_to_string

print "Stacktrace:\n",Exception->stacktrace_to_string(@stack),"\n";
# or
print "Stacktrace:\n",$e->stacktrace_to_string(@stack),"\n";

This method takes an array of array references and turns them into a stringified summary that's nicer looking than the raw data structure.

line

print 'At line: ',$e->line(),"\n";

Get or set the line number in the exception object.

package

print 'In pacakge: ',$e->pacakge(),"\n";

Get or set the package name in the exception object.

filename

print 'In File: ',$e->filename(),"\n";

Get or set the file name in the exception object.

stacktrace

print 'Stacktrace: ',"\n",$e->stacktrace(),"\n";

This method returns (actualy, it's a get or set method) the stacktrace [string version creatd by stacktrace_to_string()]. By default, the stacktrace is generated and stored during the construction of the exception object.

error

print 'Error: ',$e->error(),"\n";

Get or set the error in the exception object.

when

print 'Hapened at: ',$e->when(),"\n";

Get or set the time in the exception object.

try

try {
  ...
};

Try a bock of code. This function is really just a synonym for eval, it's main reason for being here is to emulate the look of the code from other languages that support exception handling (like C++). Please note that try is actualy a function which expects to be passed a codeblock - this means that you need to follow your closing curly brace with a semicolon.

as_string

print 'Exception: ',"\n",$e->as_string(),"\n";

Returns a nice looking summary of the inforamtion contained in the exception object.

catch

if(catch(qw(My::Exception e))) {
  print 'Caught My::Exception object: ',$e->as_string(),"\n";
}
elsif(catch(qw(Exception e))) {
  print 'Caught Exception object: ',$e->as_string(),"\n";
}
elsif(catch()) {
  print 'Caught old style or unknown type of exception: ',$@,"\n";
}

Try catching an exception. catch() expects its first argument to be a class name. If the exception that was thrown is of that type, or of a type derived from the given type, catch() will return a true value. If the exception is not an object of the given type, catch() will return undef.

If a second argument is passed to catch(), it will be assumed that it is to be a named scalar to store the exception object in. catch() will then create that symbol in the caller's namespace and assign the exception object to it. You don't have to use this, but if you do, $@ will be cleared (set to undef) so it doesn't accidentaly trigger any other code that might check $@. If you don't pass a symbol name here, you get to decide what to do with $@ (it will still contain the exception - weather its an object or not).

When you invoke catch() with no arguments, it will return true or false based on weather or not $@ is defined. This is how you can perform a 'catch all' for any exception type that you're not explicitly looking for.

throw

unless(open(FILE,'</not/a/file')) {
  throw(new Exception('Errror opening file: ',$!,"\n"));
}

Throw a new exception. throw() is technicaly just a synonym for Perl's die().

rethrow

try {
  ...
};
if(catch(qw(Exception e))) {
  # handle the exception...
}
elsif(catch()) {
  # we don't know what this is...
  rethrow();
}

rethrow() is mainly here for readability right now, though plans are to probably have the exceptoin object capture some kinds of information every time it's thrown or rethrown. rethrow() currently is exactly the same as throw() which is bacily just a synonym for die.

Called with no arguments, rethrow() throws $@. Called with an argument, rethrow() throws it's arguments.

DERIVING NEW EXCEPTION TYPES

Usualy the type of the exception is all that's importiant, so actualy deriving a new object from Exception and overriding behavior isn't commonly done. So, for Perl to recognize the new class type, all that really needs to be set up is the ISA array. So, all you will have to do is:

@Test::Exception::ISA = qw(Exception);

Then use the new type:

try {
  ...
};
if(catch(qw(Test::Exception e))) {
  # caught a Test::Exception...
}
elsif(catch(qw(Exception e))) {
  # caught an Exception...
}
elsif(catch()) {
  # caught something else...
}

AUTHOR

Kyle R. Burton <mortis@voicenet.com>

SEE ALSO

perl(1).