—

              
use 5.008001;
use strict;
use warnings;
package custom::failures;
# ABSTRACT: Minimalist, customized exception hierarchy generator
our $VERSION = '0.004'; # VERSION
use parent 'failures';
1;
# vim: ts=4 sts=4 sw=4 et:
__END__
HideShow 210 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
custom::failures - Minimalist, customized exception hierarchy generator
=head1 VERSION
version 0.004
=head1 SYNOPSIS
    package MyApp::failure;
    use custom::failures qw/io::file io::network/;
    # customize failure methods…
=head1 DESCRIPTION
This module works like L<failures> but lets you define a customized exception
hierarchy if you need a custom namespace, additional attributes, or customized
object behaviors.
Because failure classes have an C<@ISA> chain and Perl by default uses
depth-first-search to resolve method calls, you can override behavior anywhere
in the custom hierarchy and it will take precedence over default C<failure>
behaviors.
There are two methods that might be useful to override:
=over 4
=item *
message
=item *
throw
=back
Both are described further, below.
=head1 USAGE
=head2 Defining a custom failure hierarchy
    package MyApp::failure;
    use custom::failures qw/foo::bar/;
This will define a failure class hierarchy under the calling package's
namespace.  The following diagram show the classes that will be created (arrows
denote 'is-a' relationships):
    MyApp::failure::foo::bar --> failure::foo::bar
           |                        |
           V                        V
    MyApp::failure::foo      --> failure::foo
           |                        |
           V                        V
    MyApp::failure           --> failure
Alternatively, if you want a different namespace for the hierarchy, do it this way:
    use custom::failures 'MyApp::Error' => [ 'foo::bar' ];
That will create the following classes and relationships:
    MyApp::Error::foo::bar --> failure::foo::bar
           |                        |
           V                        V
    MyApp::Error::foo      --> failure::foo
           |                        |
           V                        V
    MyApp::Error           --> failure
By having custom classes also inherit from a standard namespace, you can throw
a custom error class that will still be caught in the standard namespace:
    use Safe::Isa; # for $_isa
    try {
        MyApp::failure::foo::bar->throw;
    }
    catch {
        if ( $_->$_isa( "failure::foo" ) ) {
            # handle it here
        }
    };
=head2 Adding custom attributes
Failure classes are implemented with L<Class::Tiny>, so adding
attributes is trivially easy:
    package MyApp::failure;
    use custom::failures qw/foo::bar/;
    use Class::Tiny qw/user/;
This adds a C<user> attribute to C<MyApp::failure> and
all its subclasses so it can be set in the argument to C<throw>:
    MyApp::failure::foo->throw( { msg => "Ouch!", user => "me" } );
Be sure to load C<Class::Tiny> B<after> you load C<custom::failures>
so that your C<@ISA> is already set up.
=head2 Overriding the C<message> method
Overriding C<message> lets you modify how the error string is produced.
The C<message> method takes a string (typically just the C<msg> field) and
returns a string.  It should not produce or append stack trace information.
That is done during object stringification.
Call C<SUPER::message> if you want the standard error text prepended (C<"Caught
$class: ...">).
For example, if you want to use L<String::Flogger> to render messages:
    package MyApp::failure;
    use custom::failures qw/foo::bar/;
    use String::Flogger qw/flog/;
    sub message {
        my ( $self, $msg ) = @_;
        return $self->SUPER::message( flog($msg) );
    }
Then you can pass strings or array references or code references as the C<msg>
for C<throw>:
    MyApp::failure->throw( "just a string"               );
    MyApp::failure->throw( [ "show some data %s", $ref ] );
    MyApp::failure->throw( sub { call_expensive_sub() }  );
Because the C<message> method is only called during stringification (unless you
call it yourself), the failure class type can be checked before any expensive
rendering is done.
=head2 Overriding the C<throw> method
Overriding C<throw> lets you modify the arguments you can provide or ensure
that a trace is included.  It can take whatever arguments you want and should
call C<SUPER::throw> with a hash reference to actually throw the error.
For example, to capture the filename associated with file errors:
    package MyApp::failure;
    use custom::failures qw/file/;
    use Class::Tiny qw/filename/;
    sub throw {
        my ( $class, $msg, $file ) = @_;
        my $args = {
            msg => $msg,
            filename => $file,
            trace => failures->croak_trace,
        };
        $self->SUPER::throw( $args );
    }
    sub message {
        # do something with 'msg' and 'filename'
    }
Later you could use it like this:
    MyApp::failure::file->throw( opening => $some_file );
=head2 Using BUILD
C<Class::Tiny> supports C<BUILD>, so you can also use that to
do things with failure objects when thrown.  This example
logs exceptions as they are built:
    use Log::Any qw/$log/;
    sub BUILD {
        my ($self) = @_;
        $log->error( $self->message );
    }
By using C<message> instead of stringifying C<$self>, we
log the message but not the trace (if any).
=for Pod::Coverage throw message as_string
=head1 AUTHOR
David Golden <dagolden@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
  The Apache License, Version 2.0, January 2004
=cut