view release on metacpan or  search on metacpan

lib/Class/Usul/Exception.pm  view on Meta::CPAN

package Class::Usul::Exception;

use namespace::autoclean;

use Unexpected::Functions qw( has_exception );
use Unexpected::Types     qw( Int Str );
use Moo;

extends q(Unexpected);
with    q(Unexpected::TraitFor::ErrorLeader);
with    q(Unexpected::TraitFor::ExceptionClasses);

my $class = __PACKAGE__;

$class->ignore_class( 'Class::Usul::IPC', 'Sub::Quote' );

has_exception $class;

has_exception 'DateTimeCoercion' => parents => [ $class ],
   error   => 'String [_1] will not coerce to a Unix time value';

has_exception 'Tainted' => parents => [ $class ],
   error   => 'String [_1] contains possible taint';

has_exception 'TimeOut' => parents => [ $class ],
   error   => 'Command [_1] timed out after [_2] seconds';

has '+class' => default => $class;

has 'out'    => is => 'ro', isa => Str, default => q();

has 'rv'     => is => 'ro', isa => Int, default => 1;

has 'time'   => is => 'ro', isa => Int, default => CORE::time(),
   init_arg  => undef;

1;

__END__

=pod

=encoding utf8

=head1 Name

Class::Usul::Exception - Exception handling

=head1 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" };

=head1 Description

An exception class that supports error messages with placeholders, a
L</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

=head1 Configuration and Environment

The C<< __PACKAGE__->ignore_class >> class method contains a classes
whose presence should be ignored by the error message leader

Defines the following list of read only attributes;

=over 3

=item C<args>

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

=item C<class>

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

=item C<error>

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

=item C<leader>

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