Ouch(3pm)

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

NAME

6       Ouch - Exceptions that don't hurt.
7

VERSION

9       version 0.0501
10

SYNOPSIS

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

DESCRIPTION

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

DEPRECATED

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

REQUIREMENTS

349       Requires Perl 5.12 or higher.
350

SUPPORT

352       Repository
353           <http://github.com/rizen/Ouch>
354
355       Bug Reports
356           <http://github.com/rizen/Ouch/issues>
357

AUTHOR

364       JT Smith <jt_at_plainblack_dot_com>
365

LEGAL

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.32.0                      2020-07-28                           Ouch(3)