Bio::Root::Exception

NAME

Bio::Root::Exception - BioPerl exceptions

SYNOPSIS

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 );

DESCRIPTION

Exceptions defined in 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( 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

Error.pm is not part of the Bioperl distribution, 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 Bio::Root::Root which can use Error.pm when it's available. See documentation in Bio::Root::Root for details.

EXCEPTIONS

AUTHOR Steve Chervitz