1failures(3)           User Contributed Perl Documentation          failures(3)
2
3
4

NAME

6       failures - Minimalist exception hierarchy generator
7

VERSION

9       version 0.004
10

SYNOPSIS

12           use failures qw/io::file io::network/;
13           use Try::Tiny;
14           use Safe::Isa; # for $_isa
15
16           try {
17               process_file or
18                   failure::io::file->throw("oops, something bad happened: $!");
19           }
20           catch {
21               if   ( $_->$_isa("failure::io::file") ) {
22                   ...
23               }
24               elsif( $_->$_isa("failure::io") ) {
25                   ...
26               }
27               elsif( $_->$_isa("failure") ) {
28                   ...
29               }
30               else {
31                   ...
32               }
33           }
34

DESCRIPTION

36       This module lets you define an exception hierarchy quickly and simply.
37
38       Here were my design goals:
39
40       •   minimalist interface
41
42       •   80% of features in 20% of lines of code
43
44       •   depend only on core modules (nearly achieved)
45
46       •   support hierarchical error types
47
48       •   identify errors types by name (class) not by parsing strings
49
50       •   leave (possibly expensive) trace decisions to the thrower
51
52       Currently, "failures" is implemented in under 70 lines of code.
53
54       Failure objects are implemented with Class::Tiny to allow easy
55       subclassing (see custom::failures), but "Class::Tiny" only requires
56       core modules, so other than that exception, the 'core only' goal is
57       achieved.
58

USAGE

60   Defining failure categories
61           use failures qw/foo::bar foo::baz/;
62
63       This will define the following classes in the "failure" namespace:
64
65       •   "failure"
66
67       •   "failure::foo"
68
69       •   "failure::foo::bar"
70
71       •   "failure::foo::baz"
72
73       Subclasses inherit, so "failure::foo::bar" is-a "failure::foo" and
74       "failure::foo" is-a "failure".
75
76   Attributes
77       A failure class has three attributes: "msg", "payload", and "trace".
78       Their usage is described below.  Accessors exist for all three.
79
80   Throwing failures
81       The "throw" method of a failure class takes a single, optional argument
82       that modifies how failure objects are stringified.
83
84       If no argument is given, a default message is generated if the object
85       is stringified:
86
87           say failure::foo::bar->throw;
88           # Caught failure::foo::bar
89
90       With a single, non-hash-reference argument, the argument is used for
91       the "msg" attribute and is appended if the object is stringified.
92
93           say failure::foo::bar->throw("Ouch!");
94           # Caught failure::foo::bar: Ouch!
95
96       With a hash reference argument, the "msg" key provides the string to
97       append to the default error.  If you have extra data to attach to the
98       exception, use the "payload" key:
99
100           failure::foo::bar->throw({
101               msg     => "Ouch!",
102               payload => $extra_data,
103           });
104
105       If an optional "trace" key is provided, it is appended if the object is
106       stringified.  To loosely emulate "die" and provide a simple filename
107       and line number, use the "failure->line_trace" class method:
108
109           failure::foo::bar->throw({
110               msg => "Ouch!",
111               trace => failure->line_trace,
112           });
113
114           # Caught failure::foo::bar: Ouch!
115           #
116           # Failure caught at <FILENAME> line <NUMBER>
117
118       To provide a trace just like the Carp module (including respecting
119       @CARP_NOT) use the "croak_trace" or "confess_trace" class methods:
120
121           failure::foo::bar->throw({
122               msg => "Ouch!",
123               trace => failure->croak_trace,
124           });
125
126           # Caught failure::foo::bar: Ouch!
127           #
128           # Failure caught at <CALLING-FILENAME> line <NUMBER>
129
130           failure::foo::bar->throw({
131               msg => "Ouch!",
132               trace => failure->confess_trace,
133           });
134
135           # Caught failure::foo::bar: Ouch!
136           #
137           # Failure caught at <FILENAME> line <NUMBER>
138           #   [confess stack trace continues]
139
140       You can provide a "trace" key with any object that overrides
141       stringification, like Devel::StackTrace:
142
143           failure::foo::bar->throw({
144               msg => "Ouch!",
145               trace => Devel::StackTrace->new,
146           });
147
148           # Caught failure::foo::bar: Ouch!
149           #
150           # [stringified Devel::StackTrace object]
151
152   Catching failures
153       Use Try::Tiny, of course.  Within a catch block, you know that $_ is
154       defined, but it still might be an unblessed reference or something that
155       is risky to call "isa" on.  If you load Safe::Isa, you get a code
156       reference in $_isa that calls "isa" only on objects.
157
158       So catching looks like this:
159
160           use Try::Tiny;
161           use Safe::Isa;
162
163           try { ... }
164           catch {
165               if ( $_->$_isa("failure::foo") ) {
166                   # handle it
167               }
168           };
169
170       If you need to rethrow the exception, just use "die":
171
172           elsif ( $_->$_isa("failure") ) {
173               die $_;
174           }
175
176   Overriding failure class behavior
177       See custom::failures.
178

SEE ALSO

180       There are many error/exception systems on CPAN.  This one is designed
181       to be minimalist.
182
183       If you have more complex or substantial needs, people I know and trust
184       seem to be recommending:
185
186       •   Throwable — exceptions as a Moo/Moose role
187
188       •   Throwable::X — Throwable extended with extra goodies
189
190       Here are other modules I found that weren't appropriate for my needs or
191       didn't suit my taste:
192
193       •   Class::Throwable — no hierarchy and always builds a full stack
194           trace
195
196       •   Error::Tiny — blends Try::Tiny and a trivial exception base class
197
198       •   Exception::Base — complexity on par with Exception::Class, but
199           highly optimized for speed
200
201       •   Exception::Class — once highly recommended, but even the author now
202           suggests Throwable
203
204       •   Exception::Simple — very simple, but always uses "caller" and has
205           no hierarchy
206
207       •   Exception::Tiny — not bad, but always uses "caller" and setting up
208           a hierarchy requires extra work
209
210       •   Ouch — simple, well-thought out, but no hierarchy; also cutesy
211           function names
212
213       Here are some that I'm very dubious about:
214
215       •   Err — alpha since 2012
216
217       •   Error — no longer recommended by maintainer
218
219       •   errors — "still under design" since 2009
220
221       •   Exception — dates back to 1996 and undocumented
222

SUPPORT

224   Bugs / Feature Requests
225       Please report any bugs or feature requests through the issue tracker at
226       <https://github.com/dagolden/failures/issues>.  You will be notified
227       automatically of any progress on your issue.
228
229   Source Code
230       This is open source software.  The code repository is available for
231       public review and contribution under the terms of the license.
232
233       <https://github.com/dagolden/failures>
234
235         git clone https://github.com/dagolden/failures.git
236

AUTHOR

238       David Golden <dagolden@cpan.org>
239

CONTRIBUTOR

241       Michael Jemmeson <mjemmeson@cpan.org>
242

244       This software is Copyright (c) 2013 by David Golden.
245
246       This is free software, licensed under:
247
248         The Apache License, Version 2.0, January 2004
249
250
251
252perl v5.36.0                      2022-07-22                       failures(3)
Impressum