1Dancer::Exception(3) User Contributed Perl Documentation Dancer::Exception(3)
2
6 Dancer::Exception - class for throwing and catching exceptions
7
9 version 1.3513
10
12 use Dancer::Exception qw(:all);
13 register_exception('DataProblem',
15 message_pattern => "test message : %s"
16 );
17 sub do_stuff {
19 raise DataProblem => "we've lost data!";
20 }
21 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
36 Dancer::Exception is based on Try::Tiny. You can try and catch
37 exceptions, like in Try::Tiny.
38 Exceptions are objects, from subclasses of Dancer::Exception::Base.
40 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 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
56 try
57 Same as in Try::Tiny
58 catch
60 Same as in Try::Tiny. The exception can be retrieved as the first
61 parameter:
62 try { ... } catch { my ($exception) = @_; };
64 continuation
66 To be used by Dancer developers only, in Dancer core code.
67 raise
69 # raise Dancer::Exception::Base::Custom
70 raise Custom => "user $username is unknown";
71 # raise Dancer::Exception::Base::Custom::Frontend
73 raise 'Custom::Frontend' => "user $username is unknown";
74 # same, raise Dancer::Exception::Base::Custom::Frontend
76 raise custom_frontend => "user $username is unknown";
77 # raise My::Own::ExceptionSystem::Invalid::Login
79 raise '+My::Own::ExceptionSystem::Invalid::Login' => "user $username is unknown";
80 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 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 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 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 # simple exception
105 register_exception ('InvalidCredentials',
106 message_pattern => "invalid credentials : %s",
107 );
108 This registers a new custom exception. To use it, do:
110 raise InvalidCredentials => "user Herbert not found";
112 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 # complex exception
118 register_exception ('InvalidLogin',
119 composed_from => [qw(Fatal InvalidCredentials)],
120 message_pattern => "wrong login or password",
121 );
122 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 registered_exceptions
128 my @exception_classes = registered_exceptions;
129 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
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 local $Dancer::Exception::Verbose;
141 $Dancer::Exception::Verbose = 1;
142 All the Carp global variables can also be used to alter the stacktrace
144 generation.
145
147 Dancer Core Developers
148
150 This software is copyright (c) 2010 by Alexis Sukrieh.
151 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.
154perl v5.36.0 2022-07-22 Dancer::Exception(3)