This file is indexed.

/usr/share/perl5/custom/failures.pm is in libfailures-perl 0.003-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
use 5.008001;
use strict;
use warnings;

package custom::failures;
# ABSTRACT: Minimalist, customized exception hierarchy generator
our $VERSION = '0.003'; # VERSION

use parent 'failures';

1;


# vim: ts=4 sts=4 sw=4 et:

__END__

=pod

=encoding UTF-8

=head1 NAME

custom::failures - Minimalist, customized exception hierarchy generator

=head1 VERSION

version 0.003

=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' => [ 'io::file' ];

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:

    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