Bio::Phylo::Util::Exceptions(3)

NAME
Bio::Phylo::Util::Exceptions - Errors ($@) that are objects

SYNOPSIS
 use Bio::Phylo::Forest::Node;
 my $node = Bio::Phylo::Forest::Node->new;

 # now let's try something illegal
 eval {
    $node->set_branch_length( 'non-numerical value' );
 };

 # have an error
 if ( my $e = Bio::Phylo::Util::Exceptions::BadNumber->caught ) {

    # print out where the error came from
    print $@->trace->as_string;

    # caught() returns $@, so $e and $@ are the
    # same object in this example.
    # Therefore, the same thing would be:
    print $e->trace->as_string;
 }

DESCRIPTION
Sometimes, Bio::Phylo dies. If this happens because you did something that brought Bio::Phylo into an undefined and dangerous state (such as might happen if you provide a non-numerical value for a setter that needs numbers), Bio::Phylo will throw an "exception", a special form of the $@ variable that is a blessed object with useful methods to help you diagnose the problem.

This package defines the exceptions that can be thrown by Bio::Phylo. There are no serviceable parts inside. Refer to the Exception::Class perldoc for more examples on how to catch exceptions and show traces.

EXCEPTION CLASSES

Bio::Phylo::Util::Exceptions::BadNumber
    Thrown when anything other than a number that passes Scalar::Util's looks_like_number test is given as an argument to a method that expects a number.

Bio::Phylo::Util::Exceptions::BadString
    Thrown when an incorrectly formatted string argument is provided, for example a string that would be split into substrings under NEXUS tokenization rules, a string that isn't an xs:NCName or a string that isn't a binomial CURIE

Bio::Phylo::Util::Exceptions::BadFormat
    Thrown when a non-existing parser or unparser format is requested, in calls such as "parse( -format => 'newik', -string => $string )", where 'newik' doesn't exist.

Bio::Phylo::Util::Exceptions::OddHash
    Thrown when an odd number of arguments has been specified. This might happen if you call a method that requires named arguments and the key/value pairs don't seem to match up.

Bio::Phylo::Util::Exceptions::ObjectMismatch
    Thrown when a method is called that requires an object as an argument, and the wrong type of object is specified.

Bio::Phylo::Util::Exceptions::UnknownMethod
    Trown when an indirect method call is attempted through the "$obj->get('unknown_method')" interface, and the object doesn't seem to implement the requested method.

Bio::Phylo::Util::Exceptions::BadArgs
    Thrown when something undefined is wrong with the supplied arguments.

Bio::Phylo::Util::Exceptions::FileError
    Thrown when a file specified as an argument does not exist or is not readable.

Bio::Phylo::Util::Exceptions::ExtensionError
    Thrown when there is an error loading a requested extension.

Bio::Phylo::Util::Exceptions::OutOfBounds
    Thrown when an entity is requested that falls outside of the range of objects contained by a Bio::Phylo::Listable subclass, probably through the "$obj->get_by_index($i)" method call.

Bio::Phylo::Util::Exceptions::NotImplemented
    Thrown when an interface method is called instead of the implementation by the child class.

Bio::Phylo::Util::Exceptions::Deprecated
    Thrown when a deprecated method is called.

METHODS

new()
    Constructor

     Type    : Constructor
     Title   : new
     Usage   : $class->new( error => 'An exception was thrown!' );
     Function: Constructs exception
     Returns : A Bio::Phylo::Util::Exceptions object
     Args    : error => 'Error message'

throw()
    Throws exception.

     Type    : Exception
     Title   : throw
     Usage   : $class->throw( error => 'An exception was thrown!' );
     Function: Throws exception
     Returns : A Bio::Phylo::Util::Exceptions object
     Args    : error => 'Error message'

caught()
    Catches an exception by class.

     Type    : Handler
     Title   : caught
     Usage   : my $e = Bio::Phylo::Util::Exceptions->caught;
     Function: Catches an exception
     Returns : A Bio::Phylo::Util::Exceptions object
     Args    : None

rethrow()
    Rethrows a caught exception.

     Type    : Exception
     Title   : rethrow
     Usage   : $@->rethrow;
     Function: Rethrows exception
     Returns : A Bio::Phylo::Util::Exceptions object
     Args    : None

as_string()
    Serializes exception.

     Type    : Serializer
     Title   : as_string
     Usage   : print $@->as_string;
     Function: Serializes exception with description and stack trace.
     Returns : String
     Args    : None

SEE ALSO
There is a mailing list at <https://groups.google.com/forum/#!forum/bio-phylo> for any user or developer questions and discussions.

Bio::Phylo::Manual
    Also see the manual: Bio::Phylo::Manual and <http://rutgervos.blogspot.com>

CITATION
If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. <http://dx.doi.org/10.1186/1471-2105-12-63>