Name

Class::Usul::Exception - Exception base class

Version

This documents version v0.15.$Rev: 280 $ of Class::Usul::Exception

Synopsis

   use Class::Usul::Functions qw(throw);
   use Try::Tiny;

   sub some_method {
      my $self = shift;

      try   { this_will_fail }
      catch { throw $_ }
   }

   # OR

   use Class::Usul::Exception;

   sub some_method {
      my $self = shift;

      eval { this_will_fail };
      Class::Usul::Exception->throw_on_error;
   }

Description

Implements try (by way of an eval), throw, and catch error semantics. Inherits from Exception::Class

Configuration and Environment

The $Class::Usul::Exception::Ignore package variable is an array ref of methods whose presence should be suppressed in the stack trace output

The $Class::Usul::Exception::Min_Level package variable defaults to 3. It is the number of stack frames to skip before setting the error message leader and line number

Defines the following list of attributes;

args

An array ref of parameters substituted in for the placeholders in the error message when the error is localised

class

Default to __PACKAGE__. Can be used to differentiate different classes of error

error

The actually error message which defaults to Error unknown. Can contain placeholders of the form [_<n>] where <n> is an integer starting at one

ignore_package

Set to the value of the $Class::Usul::Exception::Ignore package variable

leader

Set to the package and line number where the error should be reported

out

Defaults to null. May contain the output from whatever just threw the exception

rv

Return value which defaults to 1

Subroutines/Methods

new

   $self = $class->new( @args );

Create an exception object. You probably do not want to call this directly, but indirectly through "catch", "throw", or "throw_on_error"

Calls the "full_message" method if asked to serialize

catch

   $self = $class->catch( @args );

Catches and returns a thrown exception or generates a new exception if $EVAL_ERROR has been set. Returns either an exception object or undef

full_message

   $error_text = $self->full_message;

This is what the object stringifies to

stacktrace

   $lines = $self->stacktrace( $num_lines_to_skip );

Return the stack trace. Defaults to skipping one (the first) line of output

throw

   $class->throw error => 'Path [_1] not found', args => [ 'pathname' ];

Create (or re-throw) an exception to be caught by the catch above. If the passed parameter is a blessed reference it is re-thrown. If a single scalar is passed it is taken to be an error message code, a new exception is created with all other parameters taking their default values. If more than one parameter is passed the it is treated as a list and used to instantiate the new exception. The 'error' parameter must be provided in this case

throw_on_error

   $class->throw_on_error;

Calls "catch" and if the was an exception "throw"s it

Diagnostics

None

Dependencies

Exception::Class

MRO::Compat

Scalar::Util

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

The default ignore package list should be configurable

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author

Peter Flanigan <pjfl@cpan.org>

License and Copyright

Copyright (c) 2013 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

cpanm Class::Usul

perl -MCPAN -e shell
install Class::Usul