Debian Codegraph @

README

raw
1 NAME
2 failures - Minimalist exception hierarchy generator
3
4 VERSION
5 version 0.004
6
7 SYNOPSIS
8 use failures qw/io::file io::network/;
9 use Try::Tiny;
10 use Safe::Isa; # for $_isa
11
12 try {
13 process_file or
14 failure::io::file->throw("oops, something bad happened: $!");
15 }
16 catch {
17 if ( $_->$_isa("failure::io::file") ) {
18 ...
19 }
20 elsif( $_->$_isa("failure::io") ) {
21 ...
22 }
23 elsif( $_->$_isa("failure") ) {
24 ...
25 }
26 else {
27 ...
28 }
29 }
30
31 DESCRIPTION
32 This module lets you define an exception hierarchy quickly and simply.
33
34 Here were my design goals:
35
36 * minimalist interface
37
38 * 80% of features in 20% of lines of code
39
40 * depend only on core modules (nearly achieved)
41
42 * support hierarchical error types
43
44 * identify errors types by name (class) not by parsing strings
45
46 * leave (possibly expensive) trace decisions to the thrower
47
48 Currently, "failures" is implemented in under 70 lines of code.
49
50 Failure objects are implemented with Class::Tiny to allow easy
51 subclassing (see custom::failures), but "Class::Tiny" only requires core
52 modules, so other than that exception, the 'core only' goal is achieved.
53
54 USAGE
55 Defining failure categories
56 use failures qw/foo::bar foo::baz/;
57
58 This will define the following classes in the "failure" namespace:
59
60 * "failure"
61
62 * "failure::foo"
63
64 * "failure::foo::bar"
65
66 * "failure::foo::baz"
67
68 Subclasses inherit, so "failure::foo::bar" is-a "failure::foo" and
69 "failure::foo" is-a "failure".
70
71 Attributes
72 A failure class has three attributes: "msg", "payload", and "trace".
73 Their usage is described below. Accessors exist for all three.
74
75 Throwing failures
76 The "throw" method of a failure class takes a single, optional argument
77 that modifies how failure objects are stringified.
78
79 If no argument is given, a default message is generated if the object is
80 stringified:
81
82 say failure::foo::bar->throw;
83 # Caught failure::foo::bar
84
85 With a single, non-hash-reference argument, the argument is used for the
86 "msg" attribute and is appended if the object is stringified.
87
88 say failure::foo::bar->throw("Ouch!");
89 # Caught failure::foo::bar: Ouch!
90
91 With a hash reference argument, the "msg" key provides the string to
92 append to the default error. If you have extra data to attach to the
93 exception, use the "payload" key:
94
95 failure::foo::bar->throw({
96 msg => "Ouch!",
97 payload => $extra_data,
98 });
99
100 If an optional "trace" key is provided, it is appended if the object is
101 stringified. To loosely emulate "die" and provide a simple filename and
102 line number, use the "failure->line_trace" class method:
103
104 failure::foo::bar->throw({
105 msg => "Ouch!",
106 trace => failure->line_trace,
107 });
108
109 # Caught failure::foo::bar: Ouch!
110 #
111 # Failure caught at <FILENAME> line <NUMBER>
112
113 To provide a trace just like the Carp module (including respecting
114 @CARP_NOT) use the "croak_trace" or "confess_trace" class methods:
115
116 failure::foo::bar->throw({
117 msg => "Ouch!",
118 trace => failure->croak_trace,
119 });
120
121 # Caught failure::foo::bar: Ouch!
122 #
123 # Failure caught at <CALLING-FILENAME> line <NUMBER>
124
125 failure::foo::bar->throw({
126 msg => "Ouch!",
127 trace => failure->confess_trace,
128 });
129
130 # Caught failure::foo::bar: Ouch!
131 #
132 # Failure caught at <FILENAME> line <NUMBER>
133 # [confess stack trace continues]
134
135 You can provide a "trace" key with any object that overrides
136 stringification, like Devel::StackTrace:
137
138 failure::foo::bar->throw({
139 msg => "Ouch!",
140 trace => Devel::StackTrace->new,
141 });
142
143 # Caught failure::foo::bar: Ouch!
144 #
145 # [stringified Devel::StackTrace object]
146
147 Catching failures
148 Use Try::Tiny, of course. Within a catch block, you know that $_ is
149 defined, but it still might be an unblessed reference or something that
150 is risky to call "isa" on. If you load Safe::Isa, you get a code
151 reference in $_isa that calls "isa" only on objects.
152
153 So catching looks like this:
154
155 use Try::Tiny;
156 use Safe::Isa;
157
158 try { ... }
159 catch {
160 if ( $_->$_isa("failure::foo") ) {
161 # handle it
162 }
163 };
164
165 If you need to rethrow the exception, just use "die":
166
167 elsif ( $_->$_isa("failure") ) {
168 die $_;
169 }
170
171 Overriding failure class behavior
172 See custom::failures.
173
174 SEE ALSO
175 There are many error/exception systems on CPAN. This one is designed to
176 be minimalist.
177
178 If you have more complex or substantial needs, people I know and trust
179 seem to be recommending:
180
181 * Throwable — exceptions as a Moo/Moose role
182
183 * Throwable::X — Throwable extended with extra goodies
184
185 Here are other modules I found that weren't appropriate for my needs or
186 didn't suit my taste:
187
188 * Class::Throwable — no hierarchy and always builds a full stack trace
189
190 * Error::Tiny — blends Try::Tiny and a trivial exception base class
191
192 * Exception::Base — complexity on par with Exception::Class, but
193 highly optimized for speed
194
195 * Exception::Class — once highly recommended, but even the author now
196 suggests Throwable
197
198 * Exception::Simple — very simple, but always uses "caller" and has no
199 hierarchy
200
201 * Exception::Tiny — not bad, but always uses "caller" and setting up a
202 hierarchy requires extra work
203
204 * Ouch — simple, well-thought out, but no hierarchy; also cutesy
205 function names
206
207 Here are some that I'm very dubious about:
208
209 * Err — alpha since 2012
210
211 * Error — no longer recommended by maintainer
212
213 * errors — "still under design" since 2009
214
215 * Exception — dates back to 1996 and undocumented
216
217 SUPPORT
218 Bugs / Feature Requests
219 Please report any bugs or feature requests through the issue tracker at
220 <https://github.com/dagolden/failures/issues>. You will be notified
221 automatically of any progress on your issue.
222
223 Source Code
224 This is open source software. The code repository is available for
225 public review and contribution under the terms of the license.
226
227 <https://github.com/dagolden/failures>
228
229 git clone https://github.com/dagolden/failures.git
230
231 AUTHOR
232 David Golden <[email protected]>
233
234 CONTRIBUTOR
235 Michael Jemmeson <[email protected]>
236
237 COPYRIGHT AND LICENSE
238 This software is Copyright (c) 2013 by David Golden.
239
240 This is free software, licensed under:
241
242 The Apache License, Version 2.0, January 2004
243