Bio::Root::Exception - Generic exception objects for Bioperl
use Bio::Root::Exception; use Error qw(:try); $file = shift; try { open (IN, $file) || throw Bio::Root::FileOpenException ( -text => "Can't open file $file for reading", -value => $!, -object => $self ); } catch Bio::Root::FileOpenException with { my $err = shift; print STDERR "Using default input file: $default_file\n"; open (IN, $default_file) || die "Can't open $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!
# Note: You don't have to be within a try{} block open (IN, $file) || $object->throw( -class => 'Bio::Root::FileOpenException', -text => "Can't open file $file for reading", -value => $!);
@Bio::TestException::ISA = qw( Bio::Root::Exception );
These are generic exceptions for typical problem situations that could arise in any module or script.
All of these exceptions 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"; };
The exceptions in Bio::Root::Exception are extensions of Graham Barr's Error.pm 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.
require Error
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 Bio::Root::Root::throw() which can use Error.pm when it's available. See documentation in Bio::Root::Root for details.
See the examples/exceptions directory of the Bioperl distribution for working demo code.
examples/exceptions
Bio::Root::Root::throw() for information about throwing Bio::Root::Exception-based exceptions.
Error.pm (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.pod
Steve Chervitz <sac@bioperl.org>
Copyright (c) 2001 Steve Chervitz. All Rights Reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This software is provided "as is" without warranty of any kind.
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( -text => "A generic exception", -object => $self );
Purpose : Guarantees that -value is set properly before calling Error::new(). Arguments: same as for Error::new() -value 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 specifing -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 ("")".
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;
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()
Purpose : Indicates that a method has not been implemented. Example : throw Bio::Root::NotImplemented( -text => "Method \"foo\" not implemented in module FooBar.", -value => "foo" );
Purpose : Indicates that some input/output-related trouble has occurred. Example : throw Bio::Root::IOException( -text => "Can't save data to file $file.", -value => $! );
Purpose : Indicates that a file could not be opened. Example : throw Bio::Root::FileOpenException( -text => "Can't open file $file for reading.", -value => $! );
Purpose : Indicates that a system call failed. Example : unlink($file) or throw Bio::Root::SystemException( -text => "Can't unlink file $file.", -value => $! );
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" );
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 );
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" );
To install Bio::Seq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Seq
CPAN shell
perl -MCPAN -e shell install Bio::Seq
For more information on module installation, please visit the detailed CPAN module installation guide.