SYNOPSIS
Throwing exceptions using Error.pm throw:
use FAST::Bio::Root::Exception;
use Error;
# Set Error::Debug to include stack trace data in the error messages
$Error::Debug = 1;
$file = shift;
open my $IN, '<', $file
or FAST::Bio::Root::FileOpenException->throw("Could not read file '$file': $!");Throwing exceptions using Bioperl throw:
# Here we have an object that ISA FAST::Bio::Root::Root, so it inherits throw().
open my $IN, '<', $file
or $object->throw(-class => 'FAST::Bio::Root::FileOpenException',
-text => "Could not read file '$file'",
-value => $!);Catching and handling exceptions using Error.pm try:
use FAST::Bio::Root::Exception;
use Error qw(:try);
# Note that we need to import the 'try' tag from Error.pm
# Set Error::Debug to include stack trace data in the error messages
$Error::Debug = 1;
my $file = shift;
my $IN;
try {
open $IN, '<', $file
or FAST::Bio::Root::FileOpenException->throw("Could not read file '$file': $!");
}
catch FAST::Bio::Root::FileOpenException with {
my $err = shift;
print STDERR "Using default input file: $default_file\n";
open $IN, '<', $default_file or die "Could not read file '$default_file': $!";
}
otherwise {
my $err = shift;
print STDERR "An unexpected exception occurred: \n$err";
# By placing an the error object reference within double quotes,
# you're invoking its stringify() method.
}
finally {
# Any code that you want to execute regardless of whether or not
# an exception occurred.
};
# the ending semicolon is essential!Defining a new Exception type as a subclass of FAST::Bio::Root::Exception:
@FAST::Bio::TestException::ISA = qw( FAST::Bio::Root::Exception );DESCRIPTION
Exceptions defined in FAST::Bio::Root::Exception
These are generic exceptions for typical problem situations that could arise in any module or script.
Using defined exception classes like these is a good idea because it indicates the basic nature of what went wrong in a convenient, computable way.
If there is a type of exception that you want to throw that is not covered by the classes listed above, it is easy to define a new one that fits your needs. Just write a line like the following in your module or script where you want to use it (or put it somewhere that is accessible to your code):
@NoCanDoException::ISA = qw( FAST::Bio::Root::Exception );All of the exceptions defined in this module inherit from a common base class exception, FAST::Bio::Root::Exception. This allows a user to write a handler for all Bioperl-derived exceptions as follows:
use FAST::Bio::Whatever;
use Error qw(:try);
try {
# some code that depends on Bioperl
}
catch FAST::Bio::Root::Exception with {
my $err = shift;
print "A Bioperl exception occurred:\n$err\n";
};So if you do create your own exceptions, just be sure they inherit from FAST::Bio::Root::Exception directly, or indirectly by inheriting from a FAST::Bio::Root::Exception subclass.
The exceptions in FAST::Bio::Root::Exception are extensions of Graham Barr's Error module available from CPAN. Despite this dependency, the FAST::Bio::Root::Exception module does not explicitly require Error. This permits FAST::Bio::Root::Exception to be loaded even when Error.pm is not available.
Throwing exceptions within Bioperl modules
Error.pm is not part of the Bioperl distibution, and may not be present within any given perl installation. So, when you want to throw an exception in a Bioperl module, the safe way to throw it is to use "throw" in FAST::Bio::Root::Root which can use Error.pm when it's available. See documentation in FAST::Bio::Root::Root for details.
SEE ALSO
See the examples/exceptions directory of the Bioperl distribution for working demo code.
"throw" in FAST::Bio::Root::Root for information about throwing FAST::Bio::Root::Exception-based exceptions.
Error (available from CPAN, author: GBARR)
Error.pm is helping to guide the design of exception handling in Perl 6. See these RFC's:
http://dev.perl.org/rfc/63.pod
http://dev.perl.org/rfc/88.podEXCEPTIONS
FAST::Bio::Root::Exception
Purpose : A generic base class for all BioPerl exceptions.
By including a "catch FAST::Bio::Root::Exception" block, you
should be able to trap all BioPerl exceptions.
Example : throw FAST::Bio::Root::Exception("A generic exception", $!);Methods defined by FAST::Bio::Root::Exception
new
Purpose : Guarantees that -value is set properly before
calling Error::new().
Arguments: key-value style arguments same as for Error::new()
You can also specify plain arguments as ($message, $value)
where $value is optional.
-value, if defined, must be non-zero and not an empty string
in order for eval{}-based exception handlers to work.
These require that if($@) evaluates to true, which will not
be the case if the Error has no value (Error overloads
numeric operations to the Error::value() method).
It is OK to create FAST::Bio::Root::Exception objects without
specifying -value. In this case, an invisible dummy value is used.
If you happen to specify a -value of zero (0), it will
be replaced by the string "The number zero (0)".
If you happen to specify a -value of empty string (""), it will
be replaced by the string "An empty string ("")".pretty_format()
Purpose : Get a nicely formatted string containing information about the
exception. Format is similar to that produced by
FAST::Bio::Root::Root::throw(), with the addition of the name of
the exception class in the EXCEPTION line and some other
data available via the Error object.
Example : print $error->pretty_format;_reformat_stacktrace
Reformatting of the stack performed by _reformat_stacktrace: for :list 1. Shift the file:line data in line i to line i+1. 2. change xxx::__ANON__() to "try{} block" 3. skip the "require" and "Error::subs::try" stack entries (boring)
This means that the first line in the stack won't have any file:line data But this isn't a big issue since it's for a FAST::Bio::Root::-based method that doesn't vary from exception to exception.
stringify()
Purpose : Overrides Error::stringify() to call pretty_format().
This is called automatically when an exception object
is placed between double quotes.
Example : catch FAST::Bio::Root::Exception with {
my $error = shift;
print "$error";
}See Also: pretty_format()
Subclasses of FAST::Bio::Root::Exception
FAST::Bio::Root::NotImplemented
Purpose : Indicates that a method has not been implemented.
Example : throw FAST::Bio::Root::NotImplemented(
-text => "Method \"foo\" not implemented in module FooBar.",
-value => "foo" );FAST::Bio::Root::IOException
Purpose : Indicates that some input/output-related trouble has occurred.
Example : throw FAST::Bio::Root::IOException(
-text => "Can't save data to file $file.",
-value => $! );FAST::Bio::Root::FileOpenException
Purpose : Indicates that a file could not be opened.
Example : throw FAST::Bio::Root::FileOpenException(
-text => "Can't open file $file for reading.",
-value => $! );FAST::Bio::Root::SystemException
Purpose : Indicates that a system call failed.
Example : unlink($file) or throw FAST::Bio::Root::SystemException(
-text => "Can't unlink file $file.",
-value => $! );FAST::Bio::Root::BadParameter
Purpose : Indicates that one or more parameters supplied to a method
are invalid, unspecified, or conflicting.
Example : throw FAST::Bio::Root::BadParameter(
-text => "Required parameter \"-foo\" was not specified",
-value => "-foo" );FAST::Bio::Root::OutOfRange
Purpose : Indicates that a specified (start,end) range or
an index to an array is outside the permitted range.
Example : throw FAST::Bio::Root::OutOfRange(
-text => "Start coordinate ($start) cannot be less than zero.",
-value => $start );FAST::Bio::Root::NoSuchThing
Purpose : Indicates that a requested thing cannot be located
and therefore could possibly be bogus.
Example : throw FAST::Bio::Root::NoSuchThing(
-text => "Accession M000001 could not be found.",
-value => "M000001" );