Name

Class::Usul::Exception - Exception handling

Version

This documents version v0.17.$Rev: 7 $ 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;
}

# THEN
try   { $self->some_method() }
catch { warn $_."\n\n".$_->stacktrace."\n" };

Description

An exception class that supports error messages with placeholders, a "throw" method with automatic re-throw upon detection of self, conditional throw if an exception was caught and a simplified stacktrace

Error objects are overloaded to stringify to the full error message plus a leader

Configuration and Environment

The File::DataClass::Exception->Ignore class attribute is an array ref of methods whose presence should be ignored by the error message leader

Defines the following list of read only attributes;

args

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

class

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

error

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

leader

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

level

A positive integer which defaults to one. How many additional stack frames to pop before calculating the leader attribute

out

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

rv

Return value which defaults to one

time

A positive integer which defaults to the CORE::time the exception was thrown

trace

An instance of the trace_class

trace_args

A hash ref of arguments passed the trace_class constructor when the trace attribute is instantiated

trace_class

A loadable class which defaults to Devel::StackTrace

Subroutines/Methods

as_string

$error_text = $self->as_string;

This is what the object stringifies to, including the leader attribute

caught

$self = $class->caught( [ @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

stacktrace

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

Return the stack trace. Defaults to skipping zero lines of output

throw

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

Create (or re-throw) an exception. 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, 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( [ @args ] );

Calls "caught" passing in the options @args and if there was an exception "throw"s it

trace_from_filter

Lifted from StackTrace::Auto this methods filters out frames from the raw stacktrace that are not of interest. If is very clever

Diagnostics

None

Dependencies

namespace::clean

overload

Moose

MooseX::Types::Common::String

MooseX::Types::Common::Numeric

MooseX::Types::Moose

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

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