Dancer...ception(3pm)

💖 Dancer...ception(3pm) 💖

okay bestie, gather round, because today we're talking about Dancer::Exception — the Perl module that lets you throw and catch your lil exceptions like the absolute icon you are. it's from the User Contributed Perl Documentation, and yes, the manual page header literally trims the name down to Dancer...ception(3pm) because apparently even the manpage wanted a cute nickname. 💅

---

✨ NAME ✨

Dancer::Exception — the class for throwing and catching exceptions, periodt. 🎀

---

🌸 VERSION 🌸

version 1.3522 — that's the one, no cap. 🦋

---

⭐ SYNOPSIS ⭐

here's the vibe, in code:

use Dancer::Exception qw(:all);

register_exception('DataProblem',
                    message_pattern => "test message : %s"
                  );

sub do_stuff {
  raise DataProblem => "we've lost data!";
}

try {
  do_stuff()
} catch {
  # an exception was thrown
  my ($exception) = @_;
  if ($exception->does('DataProblem')) {
    # handle the data problem
    my $message = $exception->message();
  } else {
    $exception->rethrow
  }
};

like… slay. 🫶

---

👑 DESCRIPTION 👑

so Dancer::Exception is built on top of Try::Tiny. you can try and catch exceptions exactly like you do in Try::Tiny. same energy, same moves.

exceptions are objects, bestie. they come from subclasses of Dancer::Exception::Base. 🔥

but hold up — for internal Dancer usage there's a special class of exceptions called Dancer::Continuation. the way these work: exceptions from this class are not caught with a catch block, only with a continuation. it's a cheap way to implement a workflow interruption. Dancer users should ignore this feature. fr fr, just ignore it. 🙈

💜 What it means for Dancer users 💜

you can throw and catch exceptions using try and catch. you can reuse some Dancer core exceptions (that's the Dancer::Exception::Base::* fam), or you can create brand-new exception classes and use them however you want. that way it's super easy to use custom exceptions in a Dancer application. go have a look at register_exception, raise, and all those methods in Dancer::Exception::Base. they ate. 💅

---

🧚 METHODS 🧚

🌈 try 🌈

Same as in Try::Tiny. literally the same. 😌

🌈 catch 🌈

Same as in Try::Tiny. the exception can be snagged as the first parameter, like:

try { ... } catch { my ($exception) = @_; };

🌈 continuation 🌈

To be used by Dancer developers only, in Dancer core code. just… developers only, bestie. don't touch. 🙈

🌈 raise 🌈

# raise Dancer::Exception::Base::Custom
raise Custom => "user $username is unknown";

# raise Dancer::Exception::Base::Custom::Frontend
raise 'Custom::Frontend' => "user $username is unknown";

# same, raise Dancer::Exception::Base::Custom::Frontend
raise custom_frontend => "user $username is unknown";

# raise My::Own::ExceptionSystem::Invalid::Login
raise '+My::Own::ExceptionSystem::Invalid::Login' => "user $username is unknown";

raise is the easy way to throw an exception. the first parameter is the name of the exception class, without the Dancer::Exception:: prefix. the other parameters get stored as raising arguments inside the exception. usually that parameter is an exception message, but honestly it's left up to the exception class implementation. you do you. 💖

if the exception class name starts with a +, then the Dancer::Exception:: part won't be added. that's how you can build your own exception class hierarchy — but lowkey you should check out register_exception first before you go implementing your own hierarchy. and if you really wanna build your own exception class hierarchy, the recommendation is that all exceptions inherit from Dancer::Exception::, or at the very least that it implements its methods. 👑

also: the exception class can be written as words separated by underscores, and it'll get camelized automatically. so 'Exception::Foo' and 'exception_foo' are equivalent. but be careful — 'MyException' can't be written as 'myexception', because it would just get camelized into 'Myexception'. yeah. awkward. 💀

🌈 register_exception 🌈

this method lets you register custom exceptions, usable by Dancer users in their route code (actually, pretty much everywhere). iconic behaviour. ✨

# simple exception
register_exception ('InvalidCredentials',
                    message_pattern => "invalid credentials : %s",
                   );

this registers a new custom exception. to use it, you do:

raise InvalidCredentials => "user Herbert not found";

the exception message can be retrieved with the $exception->message method, and we'll be "invalid credentials : user Herbert not found" (see the methods in Dancer::Exception::Base).

# complex exception
register_exception ('InvalidLogin',
                    composed_from => [qw(Fatal InvalidCredentials)],
                    message_pattern => "wrong login or password",
                 );

in this example, the InvalidLogin is built as a composition of the Fatal and InvalidCredentials exceptions. see the does method in Dancer::Exception::Base for that one. 🦋

🌈 registered_exceptions 🌈

my @exception_classes = registered_exceptions;

returns the list of exception class names. it'll list core exceptions and custom exceptions (except the one you registered with a leading +, see register_exception). the list is sorted. tidy. 🎀

---

🌟 GLOBAL VARIABLE 🌟

💫 $Dancer::Exception::Verbose 💫

when you set it to 1, exceptions will stringify with a long stack trace. this variable is similar to $Carp::Verbose. the recommended way to use it is like this:

local $Dancer::Exception::Verbose;
$Dancer::Exception::Verbose = 1;

and psst — all the Carp global variables can also be used to alter the stacktrace generation. 🙌

---

💖 AUTHOR 💖

Dancer Core Developers. the icons behind the icon. 👑

---

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2010 by Alexis Sukrieh.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so yes, go forth and share. 🫶

---

and that's the whole page, bestie! this manual was brought to you by perl v5.40.1, dated 2026-05-05, and honestly? a whole serve. go catch some exceptions, my main character. 💅✨🌈