1Ouch(3) User Contributed Perl Documentation Ouch(3)
2
3
4
6 Ouch - Exceptions that don't hurt.
7
9 version 0.0501
10
12 use Ouch;
13
14 eval { ouch(404, 'File not found.'); };
15
16 if (kiss 404) {
17 check_elsewhere();
18 }
19
20 say $@; # These two lines do the
21 say $@->scalar; # same thing.
22
24 Ouch provides a class for exception handling that doesn't require a lot
25 of boilerplate, nor any up front definition. If Exception::Class is
26 working for you, great! But if you want something that is faster,
27 easier to use, requires less typing, and has no prereqs, but still
28 gives you much of that same functionality, then Ouch is for you.
29
30 Why another exception handling module?
31 It really comes down to Carp isn't enough for me, and Exception::Class
32 does what I want but makes me type way too much. Also, I tend to work
33 on a lot of protocol-based systems that use error codes (HTTP, FTP,
34 SMTP, JSON-RPC) rather than error classes, so that feels more natural
35 to me. Consider the difference between these:
36
37 Ouch
38
39 use Ouch;
40 ouch 404, 'File not found.', 'file';
41
42 Exception::Class
43
44 use Exception::Class (
45 'FileNotFound' => {
46 fields => [ 'code', 'field' ],
47 },
48 );
49 FileNotFound->throw( error => 'File not found.', code => 404, field => 'file' );
50
51 And if you want to catch the exception you're looking at:
52
53 Ouch
54
55 if (kiss 404) {
56 # do something
57 }
58
59 Exception::Class
60
61 my $e;
62 if ($e = Exception::Class->caught('FileNotFound')) {
63 # do something
64 }
65
66 Those differences may not seem like a lot, but over any substantial
67 program with lots of exceptions it can become a big deal.
68
69 Usage
70 Most of the time, all you need to do is:
71
72 ouch $code, $message, $data;
73 ouch -32700, 'Parse error.', $request; # JSON-RPC 2.0 error
74 ouch 441, 'You need to specify an email address.', 'email'; # form processing error
75 ouch 'missing_param', 'You need to specify an email address.', 'email';
76
77 You can also go long form if you prefer:
78
79 die Ouch->new($code, $message, $data);
80
81 If you want to rethrow an Ouch, you can simply "die" it.
82
83 eval { ouch(404, 'File not found.'); } ;
84 die $@;
85
86 Functional Interface
87 ouch
88
89 Some nice sugar instead of using the object oriented interface.
90
91 ouch 2121, 'Did not do the big thing.';
92
93 code
94 An error code. An integer or string representing error type. Try to
95 stick to codes used in whatever domain you happen to be working in.
96 HTTP Status codes. JSON-RPC error codes, etc.
97
98 message
99 A human readable error message.
100
101 data
102 Optional. Anything you want to attach to the exception to help a
103 developer catching it decide what to do. For example, if you're
104 doing form processing, you might want this to be the name of the
105 field that caused the exception.
106
107 WARNING: Do not include objects or code refs in your data. This
108 should only be stuff that is easily serializable like scalars,
109 array refs, and hash refs.
110
111 kiss
112
113 Some nice sugar to trap an Ouch.
114
115 if (kiss $code) {
116 # make it go
117 }
118
119 code
120 The code you're looking for.
121
122 exception
123 Optional. If you like you can pass the exception into "kiss". If
124 not, it will just use whatever is in $@. You might want to do this
125 if you've saved the exception before running another "eval", for
126 example.
127
128 hug
129
130 Some nice sugar to trap any exception.
131
132 if (hug) {
133 # make it stop
134 }
135
136 exception
137 Optional. If you like you can pass the exception into "hug". If
138 not, it will just use whatever is in $@.
139
140 bleep
141
142 A little sugar to make exceptions human friendly. Returns a clean error
143 message from any exception, including an Ouch.
144
145 File not found.
146
147 Rather than:
148
149 File not found. at /Some/File.pm line 63.
150
151 exception
152 Optional. If you like you can pass the exception into "bleep". If
153 not, it will just use whatever is in $@.
154
155 barf
156
157 Calls "bleep", and then exits with error code
158
159 exception
160 Optional. You can pass an exception into "barf" which then gets
161 passed to "bleep" otherwise it will use whatever's in $@
162
163 Object-Oriented Interface
164 new
165
166 Constructor for the object-oriented interface. Takes the same
167 parameters as "ouch".
168
169 Ouch->new($code, $message, $data);
170
171 scalar
172
173 Returns the scalar form of the error message:
174
175 Crap! at /Some/File.pm line 43.
176
177 Just as if you had done:
178
179 die 'Crap!';
180
181 Rather than:
182
183 ouch $code, 'Crap!';
184
185 trace
186
187 Call this if you want the full stack trace that lead up to the ouch.
188
189 hashref
190
191 Returns a formatted hash reference of the exception, which can be
192 useful for handing off to a serializer like JSON.
193
194 {
195 code => $code,
196 message => $message,
197 data => $data,
198 }
199
200 code
201
202 Returns the "code" passed into the constructor.
203
204 message
205
206 Returns the "messsage" passed into the constructor.
207
208 data
209
210 Returns the "data" passed into the constructor.
211
212 Try::Tiny
213 Many Ouch users like to use Ouch with Try::Tiny.
214
215 use Try::Tiny;
216 use Ouch;
217
218 try {
219 ouch 404, 'File not found!';
220 }
221 catch {
222 if (kiss(401, $_)) {
223 # do something
224 }
225 else {
226 die $_; # rethrow
227 }
228 };
229
230 Some users are sticks in the mud who can't bring themselves to "ouch"
231 and "kiss". For them, there is the ":trytiny" interface. Here's how it
232 works:
233
234 use Try::Tiny;
235 use Ouch qw(:trytiny);
236
237 try {
238 throw 404, 'File not found!';
239 }
240 catch {
241 if (caught(401, $_)) {
242 # do something
243 }
244 else {
245 die $_; # rethrow
246 }
247 };
248
249 Using Try::Tiny has some impedence mismatch in that the exception is
250 propagated through $_ instead of $@ (the default used by Ouch). This
251 forces to always include $_ when calling functions in Ouch, which is
252 suboptimal. It's possible to do this:
253
254 use Try::Tiny;
255 use Ouch qw(:trytiny_var); # use Try::Tiny's variable $_
256
257 try {
258 throw 404, 'File not found!';
259 }
260 catch {
261 if (kiss 401) {
262 # do something
263 }
264 else {
265 die $_; # rethrow
266 }
267 };
268
269 i.e. you can use the regular Ouch syntax.
270
271 This behaviour is localized to the import, i.e. if Ouch is then
272 imported in another place it is possible to decide again which is the
273 default exception variable in that specific import:
274
275 package I::Want::Try::Tiny;
276 use Try::Tiny;
277 use Ouch qw(:trytiny_var);
278 # ... $_ is the default exception for kiss, hug, barf, and bleep
279
280 package Gimme::Regular::Ouch;
281 use Ouch;
282 # ... $@ is the default exception object here
283
284 It's also possible to mix the two approaches, i.e. use both ":trytiny"
285 and ":trytiny_var".
286
287 throw
288
289 See "ouch" for details.
290
291 caught
292
293 See "kiss" for details.
294
295 caught_all
296
297 See "hug" for details.
298
300 This functionality is deprecated and will be removed in a future
301 release. Use Try::Tiny instead.
302
303 Traditional Interface
304 Some people just can't bring themselves to use the sugary cuteness of
305 Ouch. For them there is the ":traditional" interface. Here's how it
306 works:
307
308 use Ouch qw(:traditional);
309
310 my $e = try {
311 throw 404, 'File not found.';
312 };
313
314 if ( catch 404, $e ) {
315 # do the big thing
316 }
317 elsif ( catch_all $e ) {
318 # make it stop
319 }
320 else {
321 # make it go
322 }
323
324 NOTE: "try" also populates $@, and "catch" and "catch_all" will also
325 use $@ if you don't specify an exception.
326
327 try
328
329 Returns an exception. Is basically just a nice wrapper around "eval".
330
331 block
332 Try accepts a code ref, anonymous subroutine, or a block.
333
334 NOTE: You need a semi-colon at the end of a "try" block.
335
336 throw
337
338 Works exactly like "ouch". See "ouch" for details.
339
340 catch
341
342 Works exactly like "kiss". See "kiss" for details.
343
344 catch_all
345
346 Works exactly like "hug". See "hug" for details.
347
349 Requires Perl 5.12 or higher.
350
352 Repository
353 <http://github.com/rizen/Ouch>
354
355 Bug Reports
356 <http://github.com/rizen/Ouch/issues>
357
359 If you're looking for something lighter, check out Carp that ships with
360 Perl. Or if you're looking for something heavier check out
361 Exception::Class.
362
364 JT Smith <jt_at_plainblack_dot_com>
365
367 Ouch is Copyright 2011 Plain Black Corporation
368 (<http://www.plainblack.com>) and is licensed under the same terms as
369 Perl itself.
370
371
372
373perl v5.30.1 2020-01-30 Ouch(3)