.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Root::Exception 3pm"
.TH Bio::Root::Exception 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Root::Exception \- BioPerl exceptions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Throwing exceptions using Error.pm throw:"
.IX Subsection "Throwing exceptions using Error.pm throw:"
.Vb 2
\&    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, \*(Aq<\*(Aq, $file
\&        or Bio::Root::FileOpenException\->throw("Could not read file \*(Aq$file\*(Aq: $!");
.Ve
.SS "Throwing exceptions using Bioperl throw:"
.IX Subsection "Throwing exceptions using Bioperl throw:"
.Vb 1
\&    # Here we have an object that ISA Bio::Root::Root, so it inherits throw().
\&
\&    open my $IN, \*(Aq<\*(Aq, $file
\&        or $object\->throw(\-class => \*(AqBio::Root::FileOpenException\*(Aq,
\&                          \-text  => "Could not read file \*(Aq$file\*(Aq",
\&                          \-value => $!);
.Ve
.SS "Catching and handling exceptions using Error.pm try:"
.IX Subsection "Catching and handling exceptions using Error.pm try:"
.Vb 2
\&    use Bio::Root::Exception;
\&    use Error qw(:try);
\&
\&    # Note that we need to import the \*(Aqtry\*(Aq 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, \*(Aq<\*(Aq, $file
\&            or Bio::Root::FileOpenException\->throw("Could not read file \*(Aq$file\*(Aq: $!");
\&    }
\&    catch Bio::Root::FileOpenException with {
\&        my $err = shift;
\&        print STDERR "Using default input file: $default_file\en";
\&        open $IN, \*(Aq<\*(Aq, $default_file or die "Could not read file \*(Aq$default_file\*(Aq: $!";
\&    }
\&    otherwise {
\&        my $err = shift;
\&        print STDERR "An unexpected exception occurred: \en$err";
\&
\&        # By placing an the error object reference within double quotes,
\&        # you\*(Aqre 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!
.Ve
.SS "Defining a new Exception type as a subclass of Bio::Root::Exception:"
.IX Subsection "Defining a new Exception type as a subclass of Bio::Root::Exception:"
.Vb 1
\&    @Bio::TestException::ISA = qw( Bio::Root::Exception );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Exceptions defined in Bio::Root::Exception"
.IX Subsection "Exceptions defined in Bio::Root::Exception"
These are generic exceptions for typical problem situations that could arise
in any module or script.
.PP
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.
.PP
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):
.PP
.Vb 1
\&    @NoCanDoException::ISA = qw( Bio::Root::Exception );
.Ve
.PP
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:
.PP
.Vb 2
\&           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:\en$err\en";
\&           };
.Ve
.PP
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.
.PP
The exceptions in Bio::Root::Exception are extensions of Graham Barr's
Error module available from \s-1CPAN.\s0  Despite this dependency, the
Bio::Root::Exception module does not explicitly \f(CW\*(C`require Error\*(C'\fR.
This permits Bio::Root::Exception to be loaded even when
Error.pm is not available.
.SS "Throwing exceptions within Bioperl modules"
.IX Subsection "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 \*(L"throw\*(R" in Bio::Root::Root which can use Error.pm
when it's available. See documentation in Bio::Root::Root for details.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See the \f(CW\*(C`examples/exceptions\*(C'\fR directory of the Bioperl distribution for
working demo code.
.PP
\&\*(L"throw\*(R" in Bio::Root::Root for information about throwing
Bio::Root::Exception\-based exceptions.
.PP
Error (available from \s-1CPAN,\s0 author: \s-1GBARR\s0)
.PP
Error.pm is helping to guide the design of exception handling in Perl 6.
See these \s-1RFC\s0's:
.PP
.Vb 1
\&     http://dev.perl.org/rfc/63.pod
\&
\&     http://dev.perl.org/rfc/88.pod
.Ve
.SH "EXCEPTIONS"
.IX Header "EXCEPTIONS"
.SH "AUTHOR Steve Chervitz"
.IX Header "AUTHOR Steve Chervitz"
.SS "Bio::Root::Exception"
.IX Subsection "Bio::Root::Exception"
.Vb 4
\& 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", $!);
.Ve
.SH "Methods defined by Bio::Root::Exception"
.IX Header "Methods defined by Bio::Root::Exception"
.SS "new"
.IX Subsection "new"
.Vb 2
\& 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 ("")".
.Ve
.SS "\fBpretty_format()\fP"
.IX Subsection "pretty_format()"
.Vb 6
\& 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;
.Ve
.SS "_reformat_stacktrace"
.IX Subsection "_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 \*(L"try{} block\*(R"
3. skip the \*(L"require\*(R" and \*(L"Error::subs::try\*(R" stack entries (boring)
.PP
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.
.SS "\fBstringify()\fP"
.IX Subsection "stringify()"
.Vb 7
\& 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";
\&           }
.Ve
.PP
See Also: \fBpretty_format()\fR
.SH "Subclasses of Bio::Root::Exception"
.IX Header "Subclasses of Bio::Root::Exception"
.SS "Bio::Root::NotImplemented"
.IX Subsection "Bio::Root::NotImplemented"
.Vb 4
\& Purpose : Indicates that a method has not been implemented.
\& Example : throw Bio::Root::NotImplemented(
\&               \-text   => "Method \e"foo\e" not implemented in module FooBar.",
\&               \-value  => "foo" );
.Ve
.SS "Bio::Root::IOException"
.IX Subsection "Bio::Root::IOException"
.Vb 4
\& Purpose : Indicates that some input/output\-related trouble has occurred.
\& Example : throw Bio::Root::IOException(
\&               \-text   => "Can\*(Aqt save data to file $file.",
\&               \-value  => $! );
.Ve
.SS "Bio::Root::FileOpenException"
.IX Subsection "Bio::Root::FileOpenException"
.Vb 4
\& Purpose : Indicates that a file could not be opened.
\& Example : throw Bio::Root::FileOpenException(
\&               \-text   => "Can\*(Aqt open file $file for reading.",
\&               \-value  => $! );
.Ve
.SS "Bio::Root::SystemException"
.IX Subsection "Bio::Root::SystemException"
.Vb 4
\& Purpose : Indicates that a system call failed.
\& Example : unlink($file) or throw Bio::Root::SystemException(
\&               \-text   => "Can\*(Aqt unlink file $file.",
\&               \-value  => $! );
.Ve
.SS "Bio::Root::BadParameter"
.IX Subsection "Bio::Root::BadParameter"
.Vb 5
\& Purpose : Indicates that one or more parameters supplied to a method
\&           are invalid, unspecified, or conflicting.
\& Example : throw Bio::Root::BadParameter(
\&               \-text   => "Required parameter \e"\-foo\e" was not specified",
\&               \-value  => "\-foo" );
.Ve
.SS "Bio::Root::OutOfRange"
.IX Subsection "Bio::Root::OutOfRange"
.Vb 5
\& 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  );
.Ve
.SS "Bio::Root::NoSuchThing"
.IX Subsection "Bio::Root::NoSuchThing"
.Vb 5
\& 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"  );
.Ve