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

ATTRIBUTES

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

METHODS

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

OPERATORS

199       Mojo::Exception overloads the following operators.
200
201   bool
202         my $bool = !!$e;
203
204       Always true.
205
206   stringify
207         my $str = "$e";
208
209       Alias for "to_string".
210

SEE ALSO

212       Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
213
214
215
216perl v5.36.0                      2022-07-22                Mojo::Exception(3)
Impressum