Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::Root::Exception - Generic exception objects for Bioperl

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 (IN, $file) ||
                   throw Bio::Root::FileOpenException ( "Can't open file $file for reading", $!);

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

            open (IN, $file) ||
                       $object->throw(-class => 'Bio::Root::FileOpenException',
                                      -text => "Can't open file $file for reading",
                                      -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;

           $file = shift;
           try {
               open (IN, $file) ||
                   throw Bio::Root::FileOpenException ( "Can't open file $file for reading", $!);
           }
           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!

   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.

       Bio::Root::Exception()
       Bio::Root::NotImplemented()
       Bio::Root::IOException()
       Bio::Root::FileOpenException()
       Bio::Root::SystemException()
       Bio::Root::BadParameter()
       Bio::Root::OutOfRange()
       Bio::Root::NoSuchThing()

       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 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 "throw" in Bio::Root::Root which can use Error.pm when it's
       available. See documentation in Bio::Root::Root for details.

SEE ALSO

       See the "examples/exceptions" directory of the Bioperl distribution for working demo code.

       "throw" in Bio::Root::Root for information 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

AUTHOR

       Steve Chervitz <sac@bioperl.org>

COPYRIGHT

       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.

DISCLAIMER

       This software is provided "as is" without warranty of any kind.

EXCEPTIONS

   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;

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