NAME

Bio::Root::Err.pm - Exception class for Perl 5 objects

SYNOPSIS

Object Creation

Bio::Root::Object.pm is a wrapper for Bio::Root::Err.pm objects so clients do not have to create these objects directly. Please see Bio::Root::Object::throw() as well as _initialize() for a more complete treatment of how to create Bio::Root::Err.pm objects.

  use Bio::Root::Err;

  $err = Bio::Root::Err->new(-MSG     =>"Bad data: $data",
			     -STACK   =>[\caller(0), \caller(1), ...],
			     );

To use the throw() method directly:

use Bio::Root::Err (:std);

throw( $object_ref, 'Error message', 'additional note', 'technical note');

The $object_ref argument should be a reference to a Bio::Root::Object.pm.

INSTALLATION

This module is included with the central Bioperl distribution:

http://bio.perl.org/Core/Latest
ftp://bio.perl.org/pub/DIST

Follow the installation instructions included in the README file.

DESCRIPTION

A Bio::Root::Err.pm object encapsulates data and methods that facilitate working with errors and exceptional conditions that arise in Perl objects. There are no biological semantics in this module, as one may suspect from its location in the Bio:: hierarchy. The location of this module serves to separate it from the namespaces of other Perl Error modules. It also makes it convenient for use by Bio:: objects.

The motivation for having an error object is to allow Perl 5 objects to deal with errors or exceptional conditions that can arise during their construction or manipulation. For example:

(1) A complex object can break in many ways.
(2) Tracking errors within a set of nested objects can be difficult.
(3) The way an error is reported should be context-sensitive:
    a web-user needs different information than does the
    software engineer.

Bio::Root::Err.pm, along with Bio::Root::Object.pm, attempt to make such problems tractable. Please see the Bio::Root::Object.pm documentation for more about my error handling philosophy.

A Bio::Root::Err.pm object is an example of a Vector-Object: This module inherits both from Bio::Root::Object.pm and Bio::Root::Vector.pm. This permits a single Err object to exist within a linked list of Err objects OR alone. See the Bio::Root::Vector.pm documentation for more about Vector-Objects.

The API for this module is not complete since the module is under development.

Other Exception Strategies

Exception handling with Perl 5 objects is currently not as evolved as one would like. The error handling used by Bio::Root::Object.pm and Bio::Root::Err.pm relies on Perl's built-in error/exception handling with eval/die, which is not very object-aware. What I've attempted to do with these modules is to make eval/die more object-savvy, as well as make Perl 5 objects more eval/die-savvy (but the current strategy is basically a hack).

It would be great if Perl could throw an object reference with die(). This would permit more intelligent and easy to write exception handlers. For now the Err.pm object is reconstructed from the output of string().

There are some other third-party Exception classes such as Torsten Ekedahl's Experimental::Exception.pm or Ken Steven's Throwable.pm or Graham Barr's Error.pm (see "Other Exception Modules"). These modules attempt to introduce a traditional "try-catch-throw" exception handling mechanism into Perl. Future version of my modules (and perhaps erl itself) may utilize one of these.

USAGE

A demo script that illustrates working with Bio::Root::Err objects is available at:

http://bio.perl.org/Core/Examples/Root_object/error.pl

DEPENDENCIES

Bio::Root::Err.pm inherits from Bio::Root::Object.pm and Bio::Root::Vector.pm.

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

bioperl-l@bioperl.org             - General discussion
http://bioperl.org/MailList.shtml - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:

bioperl-bugs@bio.perl.org
http://bio.perl.org/bioperl-bugs/

AUTHOR Steve Chervitz

Email sac@bioperl.org

See the FEEDBACK section section for where to send bug reports and comments.

VERSION

Bio::Root::Err.pm, 0.041

ACKNOWLEDGEMENTS

This module was developed under the auspices of the Saccharomyces Genome Database: http://genome-www.stanford.edu/Saccharomyces

Other Bioperl developers contributed ideas including Ewan Birney, Ian Korf, Chris Dagdigian, Georg Fuellen, and Steven Brenner.

COPYRIGHT

TODO

Improve documentation.
Experiment with other Exception modules.

APPENDIX

Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.

_initialize

Usage     : n/a; automatically called by Bio::Root::Object::new()
Purpose   : Initializes key Bio::Root::Err.pm data.
Returns   : String (the -MAKE constructor option.)
Argument  : Named parameters passed from new()
          : (PARAMETER TAGS CAN BE UPPER OR LOWER CASE).
          :   -MSG     => basic description of the exception.
          :   -NOTE    => additional note to indicate cause of exception
          :               or provide information about how to fix/report it
          :   -TECH    => addition note with technical information
          :               of interest to developer.
          :   -STACK   => array reference containing caller() data
          :   -TYPE    => string, one of @Bio::Root::Err::ERR_TYPES
          :               (default = exception).
          :   -CONTEXT => array reference
          :   -OBJ     => Err object to be cloned.

See Also : Bio::Root::Object::_set_err()

_set_clone

Usage     : n/a; internal method used by _initialize()
Purpose   : Copy all Bio::Root::Err.pm data members into a new object reference.
Argument  : object ref for object to be cloned.
Comments  : Does not cloning the vector since this method is
          : typically used to extract a single Err object from its vector.

_build_from_string

Usage     : n/a; called by _initialize()
Purpose   : Re-create an Err.pm object from a string containing Err data.
Returns   : boolean, (was the Err.pm object rebuilt?)
Argument  : message, note, tech passed from _initialize()
          : The message is examined to see if it contains a stringified error.

See Also : _initialize(), string(), _has_err()

_has_err

Usage     : n/a; internal method called by _build_from_string()
Purpose   : Deterimine if an Err has already been set to prevent duplicate Errs.
Returns   : boolean

_set_type

Usage     : n/a; internal method
Purpose   : Sets the type of Err (warning, exception, fatal)
          : Called by _initialize()
Argument  : string

_set_list_data

Usage     : n/a; internal method used by set().
          : $err->_set_list_data( $member, $data);
Purpose   : For data members which are anonymous arrays: note, tech, stack,
          : adds the given data to the list.
Arguments : $member = any of qw(note tech stack)
          : $data   = string
Comments  : Splits $data on tab. Each item
          : of the split is a new entry.
          : To clobber the current data (unusual situation), you must first
          : call set() with no data then call again with desired data.

_set_context

Usage     : n/a; internal method used by set().
Purpose   : Sets the object containment context for the exception.
          : (this is the hierarchy of objects in which the
          :  exception occurred.)

set

Usage     : $err->set( $member, $data );
Purpose   : General accessor for setting any Err.pm data member.
Example   : $err->set('note', 'this is an additional note.');
Returns   : n/a
Argument  : $member = string, any of qw(msg type note tech stack)
          : $data   = string
Throws    : n/a
Comments  : Note, tech, and stack items are appended to any existing
          : notes, tech notes, and stack.
          : There should be no need to mess with the stack.

msg

Usage     : $message = $err->msg;
Purpose   : Get the main message associated with the exception.
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

type

Usage     : $type = $err->type;
Purpose   : Get the type of Err (warning, exception, fatal)
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

note

Usage     : $note = $err->note;
          : $note = $err->note('<P>');
Purpose   : Get any general note associated with the exception.
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

tech

Usage     : $tech = $err->tech;
          : $tech = $err->tech('<P>');
Purpose   : Get any technical note associate with the exception.
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

stack

Usage     : $stack = $err->stack;
          : $stack = $err->stack('<P>');
Purpose   : Get the call stack for the exception.
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

context

Usage     : $context = $err->context;
          : $context = $err->context('<P>');
Purpose   : Get the containment context of the object which generated the exception.
Returns   : String
Argument  : optional string to be used as a delimiter.

See Also : get(), string()

get

Usage     : $err->get($member, $delimiter);
Purpose   : Get specific data from the Err.pm object.
Returns   : String in scalar context.
          : Array in list context.
Argument  : $member = any of qw(msg type note tech stack context) or combination.
          : $delimiter = optional string to be used as a delimiter
          : between member data.

See Also : string(), msg(), note(), tech(), type(), context(), stack()

_get_list_data

Usage     : n/a; internal method used by get()
Purpose   : Gets data for members which are list refs (note, tech, stack, context)
Returns   : Array
Argument  : ($member, $delimiter)

get_all

Usage     : (same as get())
Purpose   : Get specific data from all errors in an Err.pm object.
Returns   : Array in list context.
          : String in scalar context.
Argument  : (same as get())

_add_note

Usage     : n/a; internal method called by _add_list_data()
Purpose   : adds a new note.

_add_tech()

Usage     : n/a; internal method called by _add_list_data()
Purpose   : adds a new technical note.

_add_list_data

Usage     : n/a; called by _set_list_data()
Purpose   : adds a new note or tech note.

print

Usage     : $err->print;
Purpose   : Prints Err data to STDOUT or a FileHandle.
Returns   : Call to print
Argument  : Named parameters for string()
Comments  : Uses string() to get data.

string

Usage     : $err->string( %named_parameters);
Purpose   : Stringify the data contained in the Err.pm object.
Example   : print STDERR $err->string;
Returns   : String
Argument  : Named parameters (optional) passed to
          : Bio::Root::IOManager::set_display().

See Also : print(), _build_from_string(), Bio::Root::IOManager::set_display()

is_fatal

Usage     : $err->is_fatal;
Purpose   : Determine if the error is of type 'FATAL'
Returns   : Boolean
Status    : Experimental, Deprecated

throw

Usage     : throw($object, [message], [note], [technical note]);
          : This method is exported.
Purpose   : Class method version of Bio::Root::Object::throw().
Returns   : die()s with the contents of the Err object in a string.
          : If the global strictness is less than -1, die is not called and
          : the error is printed to STDERR.
Argument  : [0] = object throwing the error.
          : [1] = optional message about the error.
          : [2] = optional note about the error.
          : [3] = optional technical note about the error.
Comments  : The glogal verbosity level is not used. For verbosity-sensitive
          : behavior, use Bio::Root::Object::throw().
Status    : Experimental
          : This method is an alternative to Bio::Root::Object::throw()
          : and is not as well developed or documented as that method.

See Also : warning(), Bio::Root::Object::throw() Bio::Root::Global::strictness()

warning

Usage     : warning($object, [message], [note], [technical note]);
          : This method is exported.
Purpose   : Class method version of Bio::Root::Object::warn().
Returns   : Prints the contents of the error to STDERR and returns false (0).
          : If the global strictness() is > 1, warn() calls are converted
          : into throw() calls.
Argument  : [0] = object producing the warning.
          : [1] = optional message about the error.
          : [2] = optional note about the error.
          : [3] = optional technical note about the error.
          :
Comments  : The glogal verbosity level is not used. For verbosity-sensitive
          : behavior, use Bio::Root::Object::warn().
Status    : Experimental
          : This method is an alternative to Bio::Root::Object::warn()
          : and is not as well developed or documented as that method.

See Also : throw, Bio::Root::Object::warn(), Bio::Root::Global::strictness()

format_stack_entry

Usage     : &format_stack_entry(<class>,<file>,<line>,<class_method>,<has_args>,<wantarray>)
          : This function is exported.
Purpose   : Creates a single stack entry given a caller() list.
Argument  : List of scalars (output of the caller() method).
Returns   : String = class_method($line)
          : e.g., Bio::Root::Object::name(1234)

FOR DEVELOPERS ONLY

Data Members

Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:

1 Do NOT rely on these in any code outside of this module.: All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).
2 This documentation may be incomplete and out of date.: It is easy for this documentation to become obsolete as this module is still evolving. Always double check this info and search for members not described here.

An instance of Bio::Root::Err.pm is a blessed reference to a hash containing all or some of the following fields:

FIELD     VALUE
------------------------------------------------------------------------
_type     fatal | warning | exception (one of @Bio::Root::Err::ERR_TYPES).

_msg      Terse description: Main cause of error.

_note     List reference. Verbose description: probable cause & troubleshooting for user.

_tech     List reference. Technical notes of interest to programmer.

_stack    List reference. Stack trace: list of "class::method(line number)" strings.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

Object Creation

INSTALLATION

DESCRIPTION

Other Exception Strategies

USAGE

DEPENDENCIES

FEEDBACK

Mailing Lists

Reporting Bugs

AUTHOR Steve Chervitz

VERSION

SEE ALSO

Other Exception Modules

ACKNOWLEDGEMENTS

COPYRIGHT

TODO

APPENDIX

_initialize

_set_clone

_build_from_string

_has_err

_set_type

_set_list_data

_set_context

set

msg

type

note

tech

stack

context

get

_get_list_data

get_all

_add_note

_add_tech()

_add_list_data

print

string

is_fatal

throw

warning

format_stack_entry

FOR DEVELOPERS ONLY

Data Members

Module Install Instructions