Ouch(3pm)

📦
version 0.0501 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Ouch — Exceptions that don't hurt 💖

okay bestie, so this is the manual page for Ouch, a Perl module living in the User Contributed Perl Documentation section of your man pages. Sit down, hydrate, and let's get into it. 🫶

✨ VERSION ✨

version 0.0501 — that's the one, that's the version, periodt.

🌈 SYNOPSIS 🌈

use Ouch;

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

if (kiss 404) {
  check_elsewhere();
}

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

See how chill that is? No boilerplate ceremony, no 47 lines of class definition before you can throw one (1) error. Iconic behaviour honestly. 👑

🦋 DESCRIPTION 🦋

So here's the whole vibe: Ouch gives you a class for exception handling that needs basically no boilerplate and no up-front definition. If Exception::Class is already serving you, amazing, love that for you, genuinely. 💅 But if you want something that's faster, easier to use, needs less typing, and has no prereqs, while still handing you a lot of that same functionality — then Ouch is literally for you, bestie.

💭 Why another exception handling module?

ngl, it comes down to this: Carp just isn't enough for the author, and Exception::Class does what he wants but makes him type way too much. Also, he tends to work on a lot of protocol-based systems that use error codes (HTTP, FTP, SMTP, JSON-RPC) rather than error classes, so error codes just feel more natural to him. Look at the difference between these two:

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 might not look like a lot, but over any substantial program with lots of exceptions it can become a big deal. fr fr.

🌸 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 that's more your thing:

die Ouch->new($code, $message, $data);

And if you want to rethrow an Ouch, you can simply die it. So easy:

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. Like, please, bestie, respect the boundary. 😭

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. (yes it really is spelled with three s's up in here, and honestly? we respect it. 💀)

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. slay.

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". Versatile king behaviour. 👑

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.

okay so, heads up bestie: this whole next bit is on the way out. It still works, but it's giving legacy. Don't start new stuff with it. 🚩

🌈 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. do not forget it. the semicolon is the moment. ✨

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. that's the floor, bestie.

💜 SUPPORT 💜

🔥 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>

Ouch is Copyright 2011 Plain Black Corporation (<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.

and that's the whole page, bestie!! 🎀 this one's from perl v5.36.0, dated 2022-12-01, and it lives in the Ouch(3pm) man page. go forth and throw exceptions that don't hurt. mwah. 💖🦋✨

📦 where this page comes from