• NAME
• SYNOPSIS
• Throwing exceptions using Error::throw():
• Throwing exceptions using Bionanny::Base::throw():
• Catching and handling exceptions using Error::try():
• Defining a new Exception type as a subclass of Bionanny::Exception:
• DESCRIPTION
• SEE ALSO
• AUTHOR
• COPYRIGHT
• DISCLAIMER
• METHODS
• new
• pretty_format
• stringify

NAME

Bionanny::Exception - Generic exception object for Bionanny

SYNOPSIS

Throwing exceptions using Error::throw():

    use Bionanny::Exception;
    use Error;

    # Set Error::Debug to include stack trace data in the error messages
    $Error::Debug = 1;

    $file = shift;
    open (IN, $file) ||
            throw Bionanny::Exception ( "Can't open file $file for reading", $!);

Throwing exceptions using Bionanny::Base::throw():

     # Here we have an object that ISA Bionanny::Base, so it inherits throw().

     open (IN, $file) || 
                $object->throw(-class => 'Bionanny::Exception',
                               -text => "Can't open file $file for reading",
                               -value => $!);

Catching and handling exceptions using Error::try():

    use Bionanny::Exception;

    # Note that we need to import the 'try' tag from Error.pm
    use Error qw(:try);

    # Set Error::Debug to include stack trace data in the error messages
    $Error::Debug = 1;

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

    @Bionanny::TestException::ISA = qw( Bionanny::Exception );

DESCRIPTION

The Bionanny::Exception is an extension of Graham Barr's Error.pm module available from CPAN.

SEE ALSO

http://www.bionanny.org

AUTHOR

Martin Senger (support@bionanny.org)

COPYRIGHT

This file is a component of the Bionanny project. Copyright Michael Niemi & Martin Senger. For details contact support@bionanny.org, or see http://www.bionanny.org/.

Parts were re-factored from modules available in Bioperl project. See copyright notices there.

This module 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.

METHODS

new

The arguments, in the key-value style, are the 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 Bionanny::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 (''``)''.

pretty_format

  print $error->pretty_format;

Get a nicely formatted string containing information about the exception. Format is similar to that produced by Bionanny::Base::throw(), with the addition of the name of the exception class in the EXCEPTION line and some other data available via the Error object.

stringify

  catch Bionanny::Exception with {
     my $error = shift;
     print "$error";
  }

Overrides Error::stringify() to call pretty_format(). This is called automatically when an exception object is placed between double quotes.