.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "Dancer::Exception 3pm"
.TH Dancer::Exception 3pm "2020-01-30" "perl v5.30.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"
Dancer::Exception \- class for throwing and catching exceptions
.SH "VERSION"
.IX Header "VERSION"
version 1.3513
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Dancer::Exception qw(:all);
\&
\&    register_exception(\*(AqDataProblem\*(Aq,
\&                        message_pattern => "test message : %s"
\&                      );
\&
\&    sub do_stuff {
\&      raise DataProblem => "we\*(Aqve lost data!";
\&    }
\&
\&    try {
\&      do_stuff()
\&    } catch {
\&      # an exception was thrown
\&      my ($exception) = @_;
\&      if ($exception\->does(\*(AqDataProblem\*(Aq)) {
\&        # handle the data problem
\&        my $message = $exception\->message();
\&      } else {
\&        $exception\->rethrow
\&      }
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Dancer::Exception is based on Try::Tiny. You can try and catch exceptions,
like in Try::Tiny.
.PP
Exceptions are objects, from subclasses of Dancer::Exception::Base.
.PP
However, for internal Dancer usage, we introduce a special class of exceptions,
called Dancer::Continuation. Exceptions that are from this class are not
caught with a \f(CW\*(C`catch\*(C'\fR block, but only with a \f(CW\*(C`continuation\*(C'\fR. That's a cheap
way to implement a \fIworkflow interruption\fR. Dancer users should ignore this
feature.
.SS "What it means for Dancer users"
.IX Subsection "What it means for Dancer users"
Users can throw and catch exceptions, using \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR. They can reuse
some Dancer core exceptions (\f(CW\*(C`Dancer::Exception::Base::*\*(C'\fR), but they can also
create new exception classes, and use them for their own means. That way it's
easy to use custom exceptions in a Dancer application. Have a look at
\&\f(CW\*(C`register_exception\*(C'\fR, \f(CW\*(C`raise\*(C'\fR, and the methods in Dancer::Exception::Base.
.SH "METHODS"
.IX Header "METHODS"
.SS "try"
.IX Subsection "try"
Same as in Try::Tiny
.SS "catch"
.IX Subsection "catch"
Same as in Try::Tiny. The exception can be retrieved as the first parameter:
.PP
.Vb 1
\&    try { ... } catch { my ($exception) = @_; };
.Ve
.SS "continuation"
.IX Subsection "continuation"
To be used by Dancer developers only, in Dancer core code.
.SS "raise"
.IX Subsection "raise"
.Vb 2
\&  # raise Dancer::Exception::Base::Custom
\&  raise Custom => "user $username is unknown";
\&
\&  # raise Dancer::Exception::Base::Custom::Frontend
\&  raise \*(AqCustom::Frontend\*(Aq => "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 \*(Aq+My::Own::ExceptionSystem::Invalid::Login\*(Aq => "user $username is unknown";
.Ve
.PP
raise provides an easy way to throw an exception. First parameter is the name
of the exception class, without the \f(CW\*(C`Dancer::Exception::\*(C'\fR prefix. other
parameters are stored as \fIraising arguments\fR in the exception. Usually the
parameters is an exception message, but it's left to the exception class
implementation.
.PP
If the exception class name starts with a \f(CW\*(C`+\*(C'\fR, then the
\&\f(CW\*(C`Dancer::Exception::\*(C'\fR won't be added. This allows one to build their own
exception class hierarchy, but you should first look at \f(CW\*(C`register_exception\*(C'\fR
before implementing your own class hierarchy. If you really wish to build your
own exception class hierarchy, we recommend that all exceptions inherit of
Dancer::Exception::. Or at least it should implement its methods.
.PP
The exception class can also be written as words separated by underscores, it'll be
camelized automatically. So \f(CW\*(AqException::Foo\*(Aq\fR and \f(CW\*(Aqexception_foo\*(Aq\fR are
equivalent. Be careful, \f(CW\*(AqMyException\*(Aq\fR can't be written \f(CW\*(Aqmyexception\*(Aq\fR, as
it would be camelized into \f(CW\*(AqMyexception\*(Aq\fR.
.SS "register_exception"
.IX Subsection "register_exception"
This method allows one to register custom exceptions, usable by Dancer users in
their route code (actually pretty much everywhere).
.PP
.Vb 4
\&  # simple exception
\&  register_exception (\*(AqInvalidCredentials\*(Aq,
\&                      message_pattern => "invalid credentials : %s",
\&                     );
.Ve
.PP
This registers a new custom exception. To use it, do:
.PP
.Vb 1
\&  raise InvalidCredentials => "user Herbert not found";
.Ve
.PP
The exception message can be retrieved with the \f(CW\*(C`$exception\->message\*(C'\fR method, and we'll be
\&\f(CW"invalid credentials : user Herbert not found"\fR (see methods in Dancer::Exception::Base)
.PP
.Vb 5
\&  # complex exception
\&  register_exception (\*(AqInvalidLogin\*(Aq,
\&                      composed_from => [qw(Fatal InvalidCredentials)],
\&                      message_pattern => "wrong login or password",
\&                   );
.Ve
.PP
In this example, the \f(CW\*(C`InvalidLogin\*(C'\fR is built as a composition of the \f(CW\*(C`Fatal\*(C'\fR
and \f(CW\*(C`InvalidCredentials\*(C'\fR exceptions. See the \f(CW\*(C`does\*(C'\fR method in
Dancer::Exception::Base.
.SS "registered_exceptions"
.IX Subsection "registered_exceptions"
.Vb 1
\&  my @exception_classes = registered_exceptions;
.Ve
.PP
Returns the list of exception class names. It will list core exceptions \f(CW\*(C`and\*(C'\fR
custom exceptions (except the one you've registered with a leading \f(CW\*(C`+\*(C'\fR, see
\&\f(CW\*(C`register_exception\*(C'\fR). The list is sorted.
.SH "GLOBAL VARIABLE"
.IX Header "GLOBAL VARIABLE"
.ie n .SS "$Dancer::Exception::Verbose"
.el .SS "\f(CW$Dancer::Exception::Verbose\fP"
.IX Subsection "$Dancer::Exception::Verbose"
When set to 1, exceptions will stringify with a long stack trace. This variable
is similar to \f(CW$Carp::Verbose\fR. I recommend you use it like that:
.PP
.Vb 2
\&  local $Dancer::Exception::Verbose;
\&  $Dancer::Exception::Verbose = 1;
.Ve
.PP
All the Carp global variables can also be used to alter the stacktrace
generation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.