.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Ouch 3pm"
.TH Ouch 3pm "2022-12-01" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Ouch \- Exceptions that don't hurt.
.SH "VERSION"
.IX Header "VERSION"
version 0.0501
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Ouch;
\&
\& eval { ouch(404, \*(AqFile not found.\*(Aq); };
\&
\& if (kiss 404) {
\&   check_elsewhere();
\& }
\&
\& say $@;           # These two lines do the
\& say $@\->scalar;   # same thing.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Ouch 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.
.SS "Why another exception handling module?"
.IX Subsection "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 (\s-1HTTP, FTP, SMTP,\s0 JSON-RPC) rather than error classes, so that feels more natural to me. Consider the difference between these:
.PP
\&\fBOuch\fR
.PP
.Vb 2
\& use Ouch;
\& ouch 404, \*(AqFile not found.\*(Aq, \*(Aqfile\*(Aq;
.Ve
.PP
\&\fBException::Class\fR
.PP
.Vb 6
\& use Exception::Class (
\&    \*(AqFileNotFound\*(Aq => {
\&        fields  => [ \*(Aqcode\*(Aq, \*(Aqfield\*(Aq ],
\&    },
\& );
\& FileNotFound\->throw( error => \*(AqFile not found.\*(Aq, code => 404, field => \*(Aqfile\*(Aq );
.Ve
.PP
And if you want to catch the exception you're looking at:
.PP
\&\fBOuch\fR
.PP
.Vb 3
\& if (kiss 404) {
\&   # do something
\& }
.Ve
.PP
\&\fBException::Class\fR
.PP
.Vb 4
\& my $e;
\& if ($e = Exception::Class\->caught(\*(AqFileNotFound\*(Aq)) {
\&   # do something
\& }
.Ve
.PP
Those differences may not seem like a lot, but over any substantial program with lots of exceptions it can become a big deal.
.SS "Usage"
.IX Subsection "Usage"
Most of the time, all you need to do is:
.PP
.Vb 4
\& ouch $code, $message, $data;
\& ouch \-32700, \*(AqParse error.\*(Aq, $request; # JSON\-RPC 2.0 error
\& ouch 441, \*(AqYou need to specify an email address.\*(Aq, \*(Aqemail\*(Aq; # form processing error
\& ouch \*(Aqmissing_param\*(Aq, \*(AqYou need to specify an email address.\*(Aq, \*(Aqemail\*(Aq;
.Ve
.PP
You can also go long form if you prefer:
.PP
.Vb 1
\& die Ouch\->new($code, $message, $data);
.Ve
.PP
If you want to rethrow an Ouch, you can simply \f(CW\*(C`die\*(C'\fR it.
.PP
.Vb 2
\& eval { ouch(404, \*(AqFile not found.\*(Aq); } ;
\& die $@;
.Ve
.SS "Functional Interface"
.IX Subsection "Functional Interface"
\fIouch\fR
.IX Subsection "ouch"
.PP
Some nice sugar instead of using the object oriented interface.
.PP
.Vb 1
\& ouch 2121, \*(AqDid not do the big thing.\*(Aq;
.Ve
.IP "code" 4
.IX Item "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. \s-1HTTP\s0 Status codes. JSON-RPC error codes, etc.
.IP "message" 4
.IX Item "message"
A human readable error message.
.IP "data" 4
.IX Item "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.
.Sp
\&\fB\s-1WARNING:\s0\fR 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.
.PP
\fIkiss\fR
.IX Subsection "kiss"
.PP
Some nice sugar to trap an Ouch.
.PP
.Vb 3
\& if (kiss $code) {
\&    # make it go
\& }
.Ve
.IP "code" 4
.IX Item "code"
The code you're looking for.
.IP "exception" 4
.IX Item "exception"
Optional. If you like you can pass the exception into \f(CW\*(C`kiss\*(C'\fR. If not, it will just use whatever is in \f(CW$@\fR. You might want to do this if you've saved the exception before running another \f(CW\*(C`eval\*(C'\fR, for example.
.PP
\fIhug\fR
.IX Subsection "hug"
.PP
Some nice sugar to trap any exception.
.PP
.Vb 3
\& if (hug) {
\&   # make it stop
\& }
.Ve
.IP "exception" 4
.IX Item "exception"
Optional. If you like you can pass the exception into \f(CW\*(C`hug\*(C'\fR. If not, it will just use whatever is in \f(CW$@\fR.
.PP
\fIbleep\fR
.IX Subsection "bleep"
.PP
A little sugar to make exceptions human friendly. Returns a clean error message from any exception, including an Ouch.
.PP
.Vb 1
\& File not found.
.Ve
.PP
Rather than:
.PP
.Vb 1
\& File not found. at /Some/File.pm line 63.
.Ve
.IP "exception" 4
.IX Item "exception"
Optional. If you like you can pass the exception into \f(CW\*(C`bleep\*(C'\fR. If not, it will just use whatever is in \f(CW$@\fR.
.PP
\fIbarf\fR
.IX Subsection "barf"
.PP
Calls \f(CW\*(C`bleep\*(C'\fR, and then exits with error code
.IP "exception" 4
.IX Item "exception"
Optional. You can pass an exception into \f(CW\*(C`barf\*(C'\fR which then gets passed to \f(CW\*(C`bleep\*(C'\fR otherwise it will use whatever's in \f(CW$@\fR
.SS "Object-Oriented Interface"
.IX Subsection "Object-Oriented Interface"
\fInew\fR
.IX Subsection "new"
.PP
Constructor for the object-oriented interface. Takes the same parameters as \f(CW\*(C`ouch\*(C'\fR.
.PP
.Vb 1
\& Ouch\->new($code, $message, $data);
.Ve
.PP
\fIscalar\fR
.IX Subsection "scalar"
.PP
Returns the scalar form of the error message:
.PP
.Vb 1
\& Crap! at /Some/File.pm line 43.
.Ve
.PP
Just as if you had done:
.PP
.Vb 1
\& die \*(AqCrap!\*(Aq;
.Ve
.PP
Rather than:
.PP
.Vb 1
\& ouch $code, \*(AqCrap!\*(Aq;
.Ve
.PP
\fItrace\fR
.IX Subsection "trace"
.PP
Call this if you want the full stack trace that lead up to the ouch.
.PP
\fIhashref\fR
.IX Subsection "hashref"
.PP
Returns a formatted hash reference of the exception, which can be useful for handing off to a serializer like \s-1JSON\s0.
.PP
.Vb 5
\& {
\&   code     => $code,
\&   message  => $message,
\&   data     => $data,
\& }
.Ve
.PP
\fIcode\fR
.IX Subsection "code"
.PP
Returns the \f(CW\*(C`code\*(C'\fR passed into the constructor.
.PP
\fImessage\fR
.IX Subsection "message"
.PP
Returns the \f(CW\*(C`messsage\*(C'\fR passed into the constructor.
.PP
\fIdata\fR
.IX Subsection "data"
.PP
Returns the \f(CW\*(C`data\*(C'\fR passed into the constructor.
.SS "Try::Tiny"
.IX Subsection "Try::Tiny"
Many Ouch users like to use Ouch with Try::Tiny.
.PP
.Vb 2
\& use Try::Tiny;
\& use Ouch;
\&
\& try {
\&    ouch 404, \*(AqFile not found!\*(Aq;
\& }
\& catch {
\&    if (kiss(401, $_)) {
\&        # do something
\&    }
\&    else {
\&        die $_; # rethrow
\&    }
\& };
.Ve
.PP
Some users are sticks in the mud who can't bring themselves to \f(CW\*(C`ouch\*(C'\fR and
\&\f(CW\*(C`kiss\*(C'\fR. For them, there is the \f(CW\*(C`:trytiny\*(C'\fR interface. Here's how it works:
.PP
.Vb 2
\& use Try::Tiny;
\& use Ouch qw(:trytiny);
\&
\& try {
\&    throw 404, \*(AqFile not found!\*(Aq;
\& }
\& catch {
\&    if (caught(401, $_)) {
\&        # do something
\&    }
\&    else {
\&        die $_; # rethrow
\&    }
\& };
.Ve
.PP
Using Try::Tiny has some impedence mismatch in that the exception is
propagated through \f(CW$_\fR instead of \f(CW$@\fR (the default used by Ouch). This
forces to always include \f(CW$_\fR when calling functions in Ouch, which is
suboptimal. It's possible to do this:
.PP
.Vb 2
\&   use Try::Tiny;
\&   use Ouch qw(:trytiny_var); # use Try::Tiny\*(Aqs variable $_
\&
\&   try {
\&      throw 404, \*(AqFile not found!\*(Aq;
\&   }
\&   catch {
\&      if (kiss 401) {
\&         # do something
\&      }
\&      else {
\&         die $_; # rethrow
\&      }
\&   };
.Ve
.PP
i.e. you can use the regular Ouch syntax.
.PP
This behaviour is localized to the import, i.e. if Ouch is then imported
in another place it is possible to decide again which is the default
exception variable in that specific import:
.PP
.Vb 4
\&   package I::Want::Try::Tiny;
\&   use Try::Tiny;
\&   use Ouch qw(:trytiny_var);
\&   # ... $_ is the default exception for kiss, hug, barf, and bleep
\&
\&   package Gimme::Regular::Ouch;
\&   use Ouch;
\&   # ... $@ is the default exception object here
.Ve
.PP
It's also possible to mix the two approaches, i.e. use both \f(CW\*(C`:trytiny\*(C'\fR
and \f(CW\*(C`:trytiny_var\*(C'\fR.
.PP
\fIthrow\fR
.IX Subsection "throw"
.PP
See \f(CW\*(C`ouch\*(C'\fR for details.
.PP
\fIcaught\fR
.IX Subsection "caught"
.PP
See \f(CW\*(C`kiss\*(C'\fR for details.
.PP
\fIcaught_all\fR
.IX Subsection "caught_all"
.PP
See \f(CW\*(C`hug\*(C'\fR for details.
.SH "DEPRECATED"
.IX Header "DEPRECATED"
This functionality is deprecated and will be removed in a future release. Use Try::Tiny instead.
.SS "Traditional Interface"
.IX Subsection "Traditional Interface"
Some people just can't bring themselves to use the sugary cuteness of Ouch. For them there is the \f(CW\*(C`:traditional\*(C'\fR interface. Here's how it works:
.PP
.Vb 1
\& use Ouch qw(:traditional);
\&
\& my $e = try {
\&   throw 404, \*(AqFile not found.\*(Aq;
\& };
\&
\& if ( catch 404, $e ) {
\&   # do the big thing
\& }
\& elsif ( catch_all $e ) {
\&   # make it stop
\& }
\& else {
\&   # make it go
\& }
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR \f(CW\*(C`try\*(C'\fR also populates \f(CW$@\fR, and \f(CW\*(C`catch\*(C'\fR and \f(CW\*(C`catch_all\*(C'\fR will also use \f(CW$@\fR if you don't specify an exception.
.PP
\fItry\fR
.IX Subsection "try"
.PP
Returns an exception. Is basically just a nice wrapper around \f(CW\*(C`eval\*(C'\fR.
.IP "block" 4
.IX Item "block"
Try accepts a code ref, anonymous subroutine, or a block.
.Sp
\&\fB\s-1NOTE:\s0\fR You need a semi-colon at the end of a \f(CW\*(C`try\*(C'\fR block.
.PP
\fIthrow\fR
.IX Subsection "throw"
.PP
Works exactly like \f(CW\*(C`ouch\*(C'\fR. See \f(CW\*(C`ouch\*(C'\fR for details.
.PP
\fIcatch\fR
.IX Subsection "catch"
.PP
Works exactly like \f(CW\*(C`kiss\*(C'\fR. See \f(CW\*(C`kiss\*(C'\fR for details.
.PP
\fIcatch_all\fR
.IX Subsection "catch_all"
.PP
Works exactly like \f(CW\*(C`hug\*(C'\fR. See \f(CW\*(C`hug\*(C'\fR for details.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
Requires Perl 5.12 or higher.
.SH "SUPPORT"
.IX Header "SUPPORT"
.IP "Repository" 4
.IX Item "Repository"
<http://github.com/rizen/Ouch>
.IP "Bug Reports" 4
.IX Item "Bug Reports"
<http://github.com/rizen/Ouch/issues>
.SH "SEE ALSO"
.IX Header "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.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1JT\s0 Smith <jt_at_plainblack_dot_com>
.SH "LEGAL"
.IX Header "LEGAL"
Ouch is Copyright 2011 Plain Black Corporation (<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.