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

NAME

6       Mojo::Exception - Exception base class
7

SYNOPSIS

9         # Create exception classes
10         package MyApp::X::Foo {
11           use Mojo::Base 'Mojo::Exception';
12         }
13         package MyApp::X::Bar {
14           use Mojo::Base 'Mojo::Exception';
15         }
16
17         # Throw exceptions and handle them gracefully
18         use Mojo::Exception qw(check);
19         eval {
20           MyApp::X::Foo->throw('Something went wrong!');
21         };
22         check(
23           'MyApp::X::Foo' => sub { say "Foo: $_" },
24           'MyApp::X::Bar' => sub { say "Bar: $_" }
25         );
26
27         # Generate exception classes on demand
28         use Mojo::Exception qw(check raise);
29         eval {
30           raise 'MyApp::X::Name', 'The name Minion is already taken';
31         };
32         check(
33           'MyApp::X::Name' => sub { say "Name error: $_" },
34           default          => sub { say "Error: $_" }
35         );
36

DESCRIPTION

38       Mojo::Exception is a container for exceptions with context information.
39

FUNCTIONS

41       Mojo::Exception implements the following functions, which can be
42       imported individually.
43
44   check
45         my $bool = check 'MyApp::X::Foo' => sub {...};
46         my $bool = check $err, 'MyApp::X::Foo' => sub {...};
47
48       Process exceptions by dispatching them to handlers with one or more
49       matching conditions. Exceptions that could not be handled will be
50       rethrown automatically. By default $@ will be used as exception source,
51       so "check" needs to be called right after "eval". Note that this
52       function is EXPERIMENTAL and might change without warning!
53
54         # Handle various types of exceptions
55         eval {
56           dangerous_code();
57         };
58         check(
59           'MyApp::X::Foo'     => sub { say "Foo: $_" },
60           qr/^Could not open/ => sub { say "Open error: $_" },
61           default             => sub { say "Something went wrong: $_" },
62           finally             => sub { say 'Dangerous code is done' }
63         );
64
65       Matching conditions can be class names for ISA checks on exception
66       objects, or regular expressions to match string exceptions and
67       stringified exception objects. The matching exception will be the first
68       argument passed to the callback, and is also available as $_.
69
70         # Catch MyApp::X::Foo object or a specific string exception
71         eval {
72           dangerous_code();
73         };
74         check(
75           'MyApp::X::Foo'     => sub { say "Foo: $_" },
76           qr/^Could not open/ => sub { say "Open error: $_" }
77         );
78
79       An array reference can be used to share the same handler with multiple
80       conditions, of which only one needs to match.  And since exception
81       handlers are just callbacks, they can also throw their own exceptions.
82
83         # Handle MyApp::X::Foo and MyApp::X::Bar the same
84         eval {
85           dangerous_code();
86         };
87         check(
88           ['MyApp::X::Foo', 'MyApp::X::Bar'] => sub { die "Foo/Bar: $_" }
89         );
90
91       There are currently two keywords you can use to set special handlers.
92       The "default" handler is used when no other handler matched. And the
93       "finally" handler runs always, it does not affect normal handlers and
94       even runs if the exception was rethrown or if there was no exception to
95       be handled at all.
96
97         # Use "default" to catch everything
98         eval {
99           dangerous_code();
100         };
101         check(
102           default => sub { say "Error: $_" },
103           finally => sub { say 'Dangerous code is done' }
104         );
105
106   raise
107         raise 'Something went wrong!';
108         raise 'MyApp::X::Foo', 'Something went wrong!';
109
110       Raise a Mojo::Exception, if the class does not exist yet (classes are
111       checked for a "new" method), one is created as a Mojo::Exception
112       subclass on demand. Note that this function is EXPERIMENTAL and might
113       change without warning!
114

ATTRIBUTES

116       Mojo::Exception implements the following attributes.
117
118   frames
119         my $frames = $e->frames;
120         $e         = $e->frames([$frame1, $frame2]);
121
122       Stack trace if available.
123
124         # Extract information from the last frame
125         my ($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext,
126             $is_require, $hints, $bitmask, $hinthash) = @{$e->frames->[-1]};
127
128   line
129         my $line = $e->line;
130         $e       = $e->line([3, 'die;']);
131
132       The line where the exception occurred if available.
133
134   lines_after
135         my $lines = $e->lines_after;
136         $e        = $e->lines_after([[4, 'say $foo;'], [5, 'say $bar;']]);
137
138       Lines after the line where the exception occurred if available.
139
140   lines_before
141         my $lines = $e->lines_before;
142         $e        = $e->lines_before([[1, 'my $foo = 23;'], [2, 'my $bar = 24;']]);
143
144       Lines before the line where the exception occurred if available.
145
146   message
147         my $msg = $e->message;
148         $e      = $e->message('Died at test.pl line 3.');
149
150       Exception message, defaults to "Exception!".
151
152   verbose
153         my $bool = $e->verbose;
154         $e       = $e->verbose($bool);
155
156       Show more information with "to_string", such as "frames", defaults to
157       the value of the "MOJO_EXCEPTION_VERBOSE" environment variable.
158

METHODS

160       Mojo::Exception inherits all methods from Mojo::Base and implements the
161       following new ones.
162
163   inspect
164         $e = $e->inspect;
165         $e = $e->inspect($source1, $source2);
166
167       Inspect "message", "frames" and optional additional sources to fill
168       "lines_before", "line" and "lines_after" with context information.
169
170   new
171         my $e = Mojo::Exception->new;
172         my $e = Mojo::Exception->new('Died at test.pl line 3.');
173
174       Construct a new Mojo::Exception object and assign "message" if
175       necessary.
176
177   to_string
178         my $str = $e->to_string;
179
180       Render exception. Note that the output format may change as more
181       features are added, only the error message at the beginning is
182       guaranteed not to be modified to allow regex matching.
183
184   throw
185         Mojo::Exception->throw('Something went wrong!');
186
187       Throw exception from the current execution context.
188
189         # Longer version
190         die Mojo::Exception->new('Something went wrong!')->trace;
191
192   trace
193         $e = $e->trace;
194         $e = $e->trace($skip);
195
196       Generate stack trace and store all "frames", defaults to skipping 1
197       call frame.
198
199         # Skip 3 call frames
200         $e->trace(3);
201
202         # Skip no call frames
203         $e->trace(0);
204

OPERATORS

206       Mojo::Exception overloads the following operators.
207
208   bool
209         my $bool = !!$e;
210
211       Always true.
212
213   stringify
214         my $str = "$e";
215
216       Alias for "to_string".
217

SEE ALSO

219       Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
220
221
222
223perl v5.32.0                      2020-07-28                Mojo::Exception(3)
Impressum