Ouch(3) User Contributed Perl Documentation Ouch(3)NAMEOuch - Exceptions that don't hurt.
VERSION
version 0.0401
SYNOPSIS
use Ouch;
eval { ouch(404, 'File not found.'); };
if (kiss 404) {
check_elsewhere();
}
say $@; # These two lines do the
say $@->scalar; # same thing.
DESCRIPTIONOuch provides a class for exception handling that doesn't require a lot
of boilerplate, nor any up front definition. If Exception::Class is
working for you, great! But if you want something that is faster,
easier to use, requires less typing, and has no prereqs, but still
gives you much of that same functionality, then Ouch is for you.
Why another exception handling module?
It really comes down to Carp isn't enough for me, and Exception::Class
does what I want but makes me type way too much. Also, I tend to work
on a lot of protocol-based systems that use error codes (HTTP, FTP,
SMTP, JSON-RPC) rather than error classes, so that feels more natural
to me. Consider the difference between these:
Ouch
use Ouch;
ouch 404, 'File not found.', 'file';
Exception::Class
use Exception::Class (
'FileNotFound' => {
fields => [ 'code', 'field' ],
},
);
FileNotFound->throw( error => 'File not found.', code => 404, field => 'file' );
And if you want to catch the exception you're looking at:
Ouch
if (kiss 404) {
# do something
}
Exception::Class
my $e;
if ($e = Exception::Class->caught('FileNotFound')) {
# do something
}
Those differences may not seem like a lot, but over any substantial
program with lots of exceptions it can become a big deal.
Usage
Most of the time, all you need to do is:
ouch $code, $message, $data;
ouch -32700, 'Parse error.', $request; # JSON-RPC 2.0 error
ouch 441, 'You need to specify an email address.', 'email'; # form processing error
ouch 'missing_param', 'You need to specify an email address.', 'email';
You can also go long form if you prefer:
die Ouch->new($code, $message, $data);
Functional Interface
ouch
Some nice sugar instead of using the object oriented interface.
ouch 2121, 'Did not do the big thing.';
code
An error code. An integer or string representing error type. Try to
stick to codes used in whatever domain you happen to be working in.
HTTP Status codes. JSON-RPC error codes, etc.
message
A human readable error message.
data
Optional. Anything you want to attach to the exception to help a
developer catching it decide what to do. For example, if you're
doing form processing, you might want this to be the name of the
field that caused the exception.
WARNING: Do not include objects or code refs in your data. This
should only be stuff that is easily serializable like scalars,
array refs, and hash refs.
kiss
Some nice sugar to trap an Ouch.
if (kiss $code) {
# make it go
}
code
The code you're looking for.
exception
Optional. If you like you can pass the exception into "kiss". If
not, it will just use whatever is in $@. You might want to do this
if you've saved the exception before running another "eval", for
example.
hug
Some nice sugar to trap any exception.
if (hug) {
# make it stop
}
exception
Optional. If you like you can pass the exception into "hug". If
not, it will just use whatever is in $@.
bleep
A little sugar to make exceptions human friendly. Returns a clean error
message from any exception, including an Ouch.
File not found.
Rather than:
File not found. at /Some/File.pm line 63.
exception
Optional. If you like you can pass the exception into "bleep". If
not, it will just use whatever is in $@.
Calls "bleep", and then exits with error code
exception
Optional. You can pass an exception into "barf" which then gets
passed to "bleep" otherwise it will use whatever's in $@
Object-Oriented Interface
new
Constructor for the object-oriented interface. Takes the same
parameters as "ouch".
Ouch->new($code, $message, $data);
scalar
Returns the scalar form of the error message:
Crap! at /Some/File.pm line 43.
Just as if you had done:
die 'Crap!';
Rather than:
ouch $code, 'Crap!';
trace
Call this if you want the full stack trace that lead up to the ouch.
hashref
Returns a formatted hash reference of the exception, which can be
useful for handing off to a serializer like JSON.
{
code => $code,
message => $message,
data => $data,
}
code
Returns the "code" passed into the constructor.
message
Returns the "messsage" passed into the constructor.
data
Returns the "data" passed into the constructor.
Traditional Interface
Some people just can't bring themselves to use the sugary cuteness of
Ouch. For them there is the ":traditional" interface. Here's how it
works:
use Ouch qw(:traditional);
my $e = try {
throw 404, 'File not found.';
};
if ( catch 404, $e ) {
# do the big thing
}
elsif ( catch_all $e ) {
# make it stop
}
else {
# make it go
}
NOTE: "try" also populates $@, and "catch" and "catch_all" will also
use $@ if you don't specify an exception.
try
Returns an exception. Is basically just a nice wrapper around "eval".
block
Try accepts a code ref, anonymous subroutine, or a block.
NOTE: You need a semi-colon at the end of a "try" block.
throw
Works exactly like "ouch". See "ouch" for details.
catch
Works exactly like "kiss". See "kiss" for details.
catch_all
Works exactly like "hug". See "hug" for details.
Try::Tiny
Many Ouch users, like to use Ouch with Try::Tiny, and some of them are
sticks in the mud who can't bring themselves to "ouch" and "kiss", and
don't like that ":traditional" walks all over "try" and "catch" For
them, there is the ":trytiny" interface. Here's how it works:
use Try::Tiny;
use Ouch qw(:trytiny);
try {
throw(404, 'File not found!';
}
catch {
if (caught($_)) {
# do something
}
else {
throw($_); # rethrow
}
};
SUPPORT
Repository
<http://github.com/rizen/Ouch>
Bug Reports
<http://github.com/rizen/Ouch/issues>
SEE ALSO
If you're looking for something lighter, check out Carp that ships with
Perl. Or if you're looking for something heavier check out
Exception::Class.
AUTHOR
JT Smith <jt_at_plainblack_dot_com>
LEGALOuch is Copyright 2011 Plain Black Corporation
(<http://www.plainblack.com>) and is licensed under the same terms as
Perl itself.
perl v5.14.1 2011-04-30 Ouch(3)
