1Dancer::Exception(3)  User Contributed Perl Documentation Dancer::Exception(3)
2
3
4

NAME

6       Dancer::Exception - class for throwing and catching exceptions
7

VERSION

9       version 1.3513
10

SYNOPSIS

12           use Dancer::Exception qw(:all);
13
14           register_exception('DataProblem',
15                               message_pattern => "test message : %s"
16                             );
17
18           sub do_stuff {
19             raise DataProblem => "we've lost data!";
20           }
21
22           try {
23             do_stuff()
24           } catch {
25             # an exception was thrown
26             my ($exception) = @_;
27             if ($exception->does('DataProblem')) {
28               # handle the data problem
29               my $message = $exception->message();
30             } else {
31               $exception->rethrow
32             }
33           };
34

DESCRIPTION

36       Dancer::Exception is based on Try::Tiny. You can try and catch
37       exceptions, like in Try::Tiny.
38
39       Exceptions are objects, from subclasses of Dancer::Exception::Base.
40
41       However, for internal Dancer usage, we introduce a special class of
42       exceptions, called Dancer::Continuation. Exceptions that are from this
43       class are not caught with a "catch" block, but only with a
44       "continuation". That's a cheap way to implement a workflow
45       interruption. Dancer users should ignore this feature.
46
47   What it means for Dancer users
48       Users can throw and catch exceptions, using "try" and "catch". They can
49       reuse some Dancer core exceptions ("Dancer::Exception::Base::*"), but
50       they can also create new exception classes, and use them for their own
51       means. That way it's easy to use custom exceptions in a Dancer
52       application. Have a look at "register_exception", "raise", and the
53       methods in Dancer::Exception::Base.
54

METHODS

56   try
57       Same as in Try::Tiny
58
59   catch
60       Same as in Try::Tiny. The exception can be retrieved as the first
61       parameter:
62
63           try { ... } catch { my ($exception) = @_; };
64
65   continuation
66       To be used by Dancer developers only, in Dancer core code.
67
68   raise
69         # raise Dancer::Exception::Base::Custom
70         raise Custom => "user $username is unknown";
71
72         # raise Dancer::Exception::Base::Custom::Frontend
73         raise 'Custom::Frontend' => "user $username is unknown";
74
75         # same, raise Dancer::Exception::Base::Custom::Frontend
76         raise custom_frontend => "user $username is unknown";
77
78         # raise My::Own::ExceptionSystem::Invalid::Login
79         raise '+My::Own::ExceptionSystem::Invalid::Login' => "user $username is unknown";
80
81       raise provides an easy way to throw an exception. First parameter is
82       the name of the exception class, without the "Dancer::Exception::"
83       prefix. other parameters are stored as raising arguments in the
84       exception. Usually the parameters is an exception message, but it's
85       left to the exception class implementation.
86
87       If the exception class name starts with a "+", then the
88       "Dancer::Exception::" won't be added. This allows one to build their
89       own exception class hierarchy, but you should first look at
90       "register_exception" before implementing your own class hierarchy. If
91       you really wish to build your own exception class hierarchy, we
92       recommend that all exceptions inherit of Dancer::Exception::. Or at
93       least it should implement its methods.
94
95       The exception class can also be written as words separated by
96       underscores, it'll be camelized automatically. So 'Exception::Foo' and
97       'exception_foo' are equivalent. Be careful, 'MyException' can't be
98       written 'myexception', as it would be camelized into 'Myexception'.
99
100   register_exception
101       This method allows one to register custom exceptions, usable by Dancer
102       users in their route code (actually pretty much everywhere).
103
104         # simple exception
105         register_exception ('InvalidCredentials',
106                             message_pattern => "invalid credentials : %s",
107                            );
108
109       This registers a new custom exception. To use it, do:
110
111         raise InvalidCredentials => "user Herbert not found";
112
113       The exception message can be retrieved with the "$exception->message"
114       method, and we'll be "invalid credentials : user Herbert not found"
115       (see methods in Dancer::Exception::Base)
116
117         # complex exception
118         register_exception ('InvalidLogin',
119                             composed_from => [qw(Fatal InvalidCredentials)],
120                             message_pattern => "wrong login or password",
121                          );
122
123       In this example, the "InvalidLogin" is built as a composition of the
124       "Fatal" and "InvalidCredentials" exceptions. See the "does" method in
125       Dancer::Exception::Base.
126
127   registered_exceptions
128         my @exception_classes = registered_exceptions;
129
130       Returns the list of exception class names. It will list core exceptions
131       "and" custom exceptions (except the one you've registered with a
132       leading "+", see "register_exception"). The list is sorted.
133

GLOBAL VARIABLE

135   $Dancer::Exception::Verbose
136       When set to 1, exceptions will stringify with a long stack trace. This
137       variable is similar to $Carp::Verbose. I recommend you use it like
138       that:
139
140         local $Dancer::Exception::Verbose;
141         $Dancer::Exception::Verbose = 1;
142
143       All the Carp global variables can also be used to alter the stacktrace
144       generation.
145

AUTHOR

147       Dancer Core Developers
148
150       This software is copyright (c) 2010 by Alexis Sukrieh.
151
152       This is free software; you can redistribute it and/or modify it under
153       the same terms as the Perl 5 programming language system itself.
154
155
156
157perl v5.36.0                      2022-07-22              Dancer::Exception(3)
Impressum