Provided by: libouch-perl_0.0501-2_all bug

NAME

       Ouch - Exceptions that don't hurt.

VERSION

       version 0.0501

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:

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

       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.

           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 $@.

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

       Using Try::Tiny has some impedence mismatch in that the exception is propagated through $_
       instead of $@ (the default used by Ouch). This forces to always include $_ when calling
       functions in Ouch, which is suboptimal. It's possible to do this:

          use Try::Tiny;
          use Ouch qw(:trytiny_var); # use Try::Tiny's variable $_

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

       i.e. you can use the regular Ouch syntax.

       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:

          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

       It's also possible to mix the two approaches, i.e. use both ":trytiny" and ":trytiny_var".

       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
        }

       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.

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.