Bio::R...eption(3pm)

📦

version 1.7.8 · 3 versions

1.7.8 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
1.7.8 · ubuntu stonking
1.7.8 · ubuntu resolute

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

🌸 NAME 🌸

Bio::Root::Exception — BioPerl exceptions, and honestly? iconic 🫶

this is the Bio::R...eption(3pm) page from User Contributed Perl Documentation (the title's doing a little disappearing act up there, that's just the renderer being cute, don't worry about it 💅)

✨ 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!

bestie the trailing semicolon is not optional. do not come crying to me. 😭

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 the generic exceptions, the ones that cover typical problem situations that could pop up in literally any module or script. no cap.

using defined exception classes like these is a good idea, because it tells you the basic nature of what went wrong in a convenient, computable way. it's giving self-documenting error handling. we love that.

and if there's a type of exception you wanna throw that isn't covered by the classes listed above? it is so 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's 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. which means a user can write a handler for all Bioperl-derived exceptions like this:

           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. that's the whole vibe check. ✅

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. lowkey genius tbh.

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.

👑 SEE ALSO 👑

peep the examples/exceptions directory of the Bioperl distribution for working demo code 🍓
throw in Bio::Root::Root for info about throwing 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.pod

💀 EXCEPTIONS 💀

AUTHOR: Steve Chervitz ✨

`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", $!);

Methods defined by `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 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`

reformatting of the stack performed by _reformat_stacktrace: for :list

shift the file:line data in line i to line i+1.
change xxx::__ANON__() to "try{} block"
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 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()

Subclasses of `Bio::Root::Exception` 🌈

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

okay that's the whole page bestie, you're officially a BioPerl exception girlie now 🫶 this was rendered by perl v5.32.1 on 2021-08-15 as Bio::R...eption(3pm) — go forth and throw responsibly 💖✨

📦 where this page comes from

debian bookworm: libbio-perl-perl 1.7.8-1 · Perl
debian trixie: libbio-perl-perl 1.7.8-1 · Perl
ubuntu jammy: libbio-perl-perl 1.7.8-1 · Perl
ubuntu noble: libbio-perl-perl 1.7.8-1 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Bio::R...eption(3pm)

🌸 NAME 🌸

✨ SYNOPSIS ✨

Throwing exceptions using Error.pm throw 💖

Throwing exceptions using Bioperl throw 🦋

Catching and handling exceptions using Error.pm try 🎀

Defining a new Exception type as a subclass of Bio::Root::Exception 🌈

💜 DESCRIPTION 💜

Exceptions defined in Bio::Root::Exception 🌸

Throwing exceptions within Bioperl modules 🧚

👑 SEE ALSO 👑

💀 EXCEPTIONS 💀

AUTHOR: Steve Chervitz ✨

Bio::Root::Exception 💖

Methods defined by Bio::Root::Exception 🎀

new

pretty_format()

_reformat_stacktrace

stringify()

Subclasses of Bio::Root::Exception 🌈

Bio::Root::NotImplemented

Bio::Root::IOException

Bio::Root::FileOpenException

Bio::Root::SystemException

Bio::Root::BadParameter

Bio::Root::OutOfRange

Bio::Root::NoSuchThing