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.0401
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   Functional Interface
82       ouch
83
84       Some nice sugar instead of using the object oriented interface.
85
86        ouch 2121, 'Did not do the big thing.';
87
88       code
89           An error code. An integer or string representing error type. Try to
90           stick to codes used in whatever domain you happen to be working in.
91           HTTP Status codes. JSON-RPC error codes, etc.
92
93       message
94           A human readable error message.
95
96       data
97           Optional. Anything you want to attach to the exception to help a
98           developer catching it decide what to do. For example, if you're
99           doing form processing, you might want this to be the name of the
100           field that caused the exception.
101
102           WARNING: Do not include objects or code refs in your data. This
103           should only be stuff that is easily serializable like scalars,
104           array refs, and hash refs.
105
106       kiss
107
108       Some nice sugar to trap an Ouch.
109
110        if (kiss $code) {
111           # make it go
112        }
113
114       code
115           The code you're looking for.
116
117       exception
118           Optional. If you like you can pass the exception into "kiss". If
119           not, it will just use whatever is in $@. You might want to do this
120           if you've saved the exception before running another "eval", for
121           example.
122
123       hug
124
125       Some nice sugar to trap any exception.
126
127        if (hug) {
128          # make it stop
129        }
130
131       exception
132           Optional. If you like you can pass the exception into "hug". If
133           not, it will just use whatever is in $@.
134
135       bleep
136
137       A little sugar to make exceptions human friendly. Returns a clean error
138       message from any exception, including an Ouch.
139
140        File not found.
141
142       Rather than:
143
144        File not found. at /Some/File.pm line 63.
145
146       exception
147           Optional. If you like you can pass the exception into "bleep". If
148           not, it will just use whatever is in $@.
149
150
151
152       Calls "bleep", and then exits with error code
153
154       exception
155           Optional. You can pass an exception into "barf" which then gets
156           passed to "bleep" otherwise it will use whatever's in $@
157
158   Object-Oriented Interface
159       new
160
161       Constructor for the object-oriented interface. Takes the same
162       parameters as "ouch".
163
164        Ouch->new($code, $message, $data);
165
166       scalar
167
168       Returns the scalar form of the error message:
169
170        Crap! at /Some/File.pm line 43.
171
172       Just as if you had done:
173
174        die 'Crap!';
175
176       Rather than:
177
178        ouch $code, 'Crap!';
179
180       trace
181
182       Call this if you want the full stack trace that lead up to the ouch.
183
184       hashref
185
186       Returns a formatted hash reference of the exception, which can be
187       useful for handing off to a serializer like JSON.
188
189        {
190          code     => $code,
191          message  => $message,
192          data     => $data,
193        }
194
195       code
196
197       Returns the "code" passed into the constructor.
198
199       message
200
201       Returns the "messsage" passed into the constructor.
202
203       data
204
205       Returns the "data" passed into the constructor.
206
207   Traditional Interface
208       Some people just can't bring themselves to use the sugary cuteness of
209       Ouch. For them there is the ":traditional" interface. Here's how it
210       works:
211
212        use Ouch qw(:traditional);
213
214        my $e = try {
215          throw 404, 'File not found.';
216        };
217
218        if ( catch 404, $e ) {
219          # do the big thing
220        }
221        elsif ( catch_all $e ) {
222          # make it stop
223        }
224        else {
225          # make it go
226        }
227
228       NOTE: "try" also populates $@, and "catch" and "catch_all" will also
229       use $@ if you don't specify an exception.
230
231       try
232
233       Returns an exception. Is basically just a nice wrapper around "eval".
234
235       block
236           Try accepts a code ref, anonymous subroutine, or a block.
237
238           NOTE: You need a semi-colon at the end of a "try" block.
239
240       throw
241
242       Works exactly like "ouch". See "ouch" for details.
243
244       catch
245
246       Works exactly like "kiss". See "kiss" for details.
247
248       catch_all
249
250       Works exactly like "hug". See "hug" for details.
251
252   Try::Tiny
253       Many Ouch users, like to use Ouch with Try::Tiny, and some of them are
254       sticks in the mud who can't bring themselves to "ouch" and "kiss", and
255       don't like that ":traditional" walks all over "try" and "catch" For
256       them, there is the ":trytiny" interface. Here's how it works:
257
258        use Try::Tiny;
259        use Ouch qw(:trytiny);
260
261        try {
262           throw(404, 'File not found!';
263        }
264        catch {
265           if (caught($_)) {
266               # do something
267           }
268           else {
269               throw($_); # rethrow
270           }
271        };
272

SUPPORT

274       Repository
275           <http://github.com/rizen/Ouch>
276
277       Bug Reports
278           <http://github.com/rizen/Ouch/issues>
279

AUTHOR

286       JT Smith <jt_at_plainblack_dot_com>
287

LEGAL

289       Ouch is Copyright 2011 Plain Black Corporation
290       (<http://www.plainblack.com>) and is licensed under the same terms as
291       Perl itself.
292
293
294
295perl v5.12.3                      2011-04-30                           Ouch(3)