GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  OUCH (3)

.ds Aq ’

NAME

Ouch - Exceptions that don’t hurt.

CONTENTS

VERSION

version 0.0409

SYNOPSIS



 use Ouch;

 eval { ouch(404, File not found.); };

 if (kiss 404) {
   check_elsewhere();
 }

 say $@;           # These two lines do the
 say $@->scalar;   # same thing.



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.

    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:

<B>OuchB>



 use Ouch;
 ouch 404, File not found., file;



<B>Exception::ClassB>



 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:

<B>OuchB>



 if (kiss 404) {
   # do something
 }



<B>Exception::ClassB>



 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);



If you want to rethrow an Ouch, you can simply die it.



 eval { ouch(404, File not found.); } ;
 die $@;



    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.

<B>WARNING:B> 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 $@.
barf

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.

    Try::Tiny

Many Ouch users like to use Ouch with Try::Tiny.



 use Try::Tiny;
 use Ouch;

 try {
    ouch 404, File not found!;
 }
 catch {
    if (kiss(401, $_)) {
        # do something
    }
    else {
        die $_; # rethrow
    }
 };



Some users are sticks in the mud who can’t bring themselves to ouch and kiss. 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(401, $_)) {
        # do something
    }
    else {
        die $_; # rethrow
    }
 };



throw

See ouch for details.

caught

See kiss for details.

caught_all

See hug for details.

DEPRECATED

This functionality is deprecated and will be removed in a future release. Use Try::Tiny instead.

    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
 }



<B>NOTE:B> 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.

<B>NOTE:B> 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.

REQUIREMENTS

Requires Perl 5.12 or higher.

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>

LEGAL

Ouch is Copyright 2011 Plain Black Corporation (<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 OUCH (3) 2015-01-27

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.