Throwing exceptions using Error.pm throw:

    use 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 Bio::Root::FileOpenException->throw("Could not read file '$file': $!");

Throwing exceptions using Bioperl throw:

    # Here we have an object that ISA Bio::Root::Root, so it inherits throw().

    open my $IN, '<', $file
        or $object->throw(-class => 'Bio::Root::FileOpenException',
                          -text  => "Could not read file '$file'",
                          -value => $!);

Catching and handling exceptions using Error.pm try:

    use 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 Bio::Root::FileOpenException->throw("Could not read file '$file': $!");
    }
    catch 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 Bio::Root::Exception:

    @Bio::TestException::ISA = qw( Bio::Root::Exception );

Exceptions defined in Bio::Root::Exception

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( Bio::Root::Exception );

All of the exceptions defined in this module inherit from a common base class exception, Bio::Root::Exception. This allows a user to write a handler for all Bioperl-derived exceptions as follows:

           use Bio::Whatever;
           use Error qw(:try);

           try {
                # some code that depends on Bioperl
           }
           catch 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 Bio::Root::Exception directly, or indirectly by inheriting from a Bio::Root::Exception subclass.

The exceptions in Bio::Root::Exception are extensions of Graham Barr's Error module available from CPAN. Despite this dependency, the Bio::Root::Exception module does not explicitly "require Error". This permits Bio::Root::Exception to be loaded even when Error.pm is not available.

Throwing exceptions within Bioperl modules

Bio::Root::Exception

 Purpose : A generic base class for all BioPerl exceptions.
           By including a "catch Bio::Root::Exception" block, you
           should be able to trap all BioPerl exceptions.
 Example : throw Bio::Root::Exception("A generic 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 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
           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

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 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 Bio::Root::Exception with {
              my $error = shift;
              print "$error";
           }

See Also: pretty_format()

Bio::Root::NotImplemented

 Purpose : Indicates that a method has not been implemented.
 Example : throw Bio::Root::NotImplemented(
               -text   => "Method \"foo\" not implemented in module FooBar.",
               -value  => "foo" );

Bio::Root::IOException

 Purpose : Indicates that some input/output-related trouble has occurred.
 Example : throw Bio::Root::IOException(
               -text   => "Can't save data to file $file.",
               -value  => $! );

Bio::Root::FileOpenException

 Purpose : Indicates that a file could not be opened.
 Example : throw Bio::Root::FileOpenException(
               -text   => "Can't open file $file for reading.",
               -value  => $! );

Bio::Root::SystemException

 Purpose : Indicates that a system call failed.
 Example : unlink($file) or throw Bio::Root::SystemException(
               -text   => "Can't unlink file $file.",
               -value  => $! );

Bio::Root::BadParameter

 Purpose : Indicates that one or more parameters supplied to a method
           are invalid, unspecified, or conflicting.
 Example : throw Bio::Root::BadParameter(
               -text   => "Required parameter \"-foo\" was not specified",
               -value  => "-foo" );

Bio::Root::OutOfRange

 Purpose : Indicates that a specified (start,end) range or
           an index to an array is outside the permitted range.
 Example : throw Bio::Root::OutOfRange(
               -text   => "Start coordinate ($start) cannot be less than zero.",
               -value  => $start  );

Bio::Root::NoSuchThing

 Purpose : Indicates that a requested thing cannot be located
           and therefore could possibly be bogus.
 Example : throw Bio::Root::NoSuchThing(
               -text   => "Accession M000001 could not be found.",
               -value  => "M000001"  );