1Exception::Class::Base(U3s)er Contributed Perl DocumentatEixocneption::Class::Base(3)
2
3
4

NAME

6       Exception::Class::Base - A base class for exception objects
7

VERSION

9       version 1.45
10

SYNOPSIS

12         use Exception::Class 'MyException';
13
14         eval { MyException->throw( error => 'I feel funny.' ) };
15
16         print $@->error;
17

DESCRIPTION

19       This class is the base class for all exceptions created by
20       Exception::Class.  It provides a number of methods for getting
21       information about the exception.
22

METHODS

24   MyException->Trace($boolean)
25       Each "Exception::Class::Base" subclass can be set individually to
26       include a stacktrace when the "as_string" method is called. The default
27       is to not include a stacktrace. Calling this method with a value
28       changes this behavior.  It always returns the current value (after any
29       change is applied).
30
31       This value is inherited by any subclasses. However, if this value is
32       set for a subclass, it will thereafter be independent of the value in
33       "Exception::Class::Base".
34
35       Do not call this on the "Exception::Class::Base" class directly or
36       you'll change it for all exception classes that use Exception::Class,
37       including ones created in modules you don't control.
38
39       This is a class method, not an object method.
40
41   MyException->UnsafeRefCapture($boolean)
42       When a "Devel::StackTrace" object is created, it walks through the
43       stack and stores the arguments which were passed to each subroutine on
44       the stack. If any of these arguments are references, then that means
45       that the "Devel::StackTrace" ends up increasing the ref count of these
46       references, delaying their destruction.
47
48       Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
49       this method provides a way to tell "Devel::StackTrace" not to store
50       these references. Instead, "Devel::StackTrace" replaces references with
51       their stringified representation.
52
53       This method defaults to false. As with "Trace", it is inherited by
54       subclasses but setting it in a subclass makes it independent
55       thereafter.
56
57       Do not call this on the "Exception::Class::Base" class directly or
58       you'll change it for all exception classes that use Exception::Class,
59       including ones created in modules you don't control.
60
61   MyException->RespectOverload($boolean)
62       When a "Devel::StackTrace" object stringifies, by default it ignores
63       stringification overloading on any objects being dealt with.
64
65       Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
66       this method provides a way to tell "Devel::StackTrace" to respect
67       overloading.
68
69       This method defaults to false. As with "Trace", it is inherited by
70       subclasses but setting it in a subclass makes it independent
71       thereafter.
72
73       Do not call this on the "Exception::Class::Base" class directly or
74       you'll change it for all exception classes that use Exception::Class,
75       including ones created in modules you don't control.
76
77   MyException->MaxArgLength($boolean)
78       When a "Devel::StackTrace" object stringifies, by default it displays
79       the full argument for each function. This parameter can be used to
80       limit the maximum length of each argument.
81
82       Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
83       this method provides a way to tell "Devel::StackTrace" to limit the
84       length of arguments.
85
86       This method defaults to 0. As with "Trace", it is inherited by
87       subclasses but setting it in a subclass makes it independent
88       thereafter.
89
90       Do not call this on the "Exception::Class::Base" class directly or
91       you'll change it for all exception classes that use Exception::Class,
92       including ones created in modules you don't control.
93
94   MyException->Fields
95       This method returns the extra fields defined for the given class, as a
96       list.
97
98       Do not call this on the "Exception::Class::Base" class directly or
99       you'll change it for all exception classes that use Exception::Class,
100       including ones created in modules you don't control.
101
102   MyException->throw( $message )
103   MyException->throw( message => $message )
104   MyException->throw( error => $error )
105       This method creates a new object with the given error message. If no
106       error message is given, this will be an empty string. It then dies with
107       this object as its argument.
108
109       This method also takes a "show_trace" parameter which indicates whether
110       or not the particular exception object being created should show a
111       stacktrace when its "as_string" method is called. This overrides the
112       value of "Trace" for this class if it is given.
113
114       The frames included in the trace can be controlled by the
115       "ignore_class" and "ignore_package" parameters. These are passed
116       directly to Devel::Stacktrace's constructor. See "Devel::Stacktrace"
117       for more details. This class always passes "__PACKAGE__" for
118       "ignore_class" and 'Exception::Class' for "ignore_package", in addition
119       to any arguments you provide.
120
121       If only a single value is given to the constructor it is assumed to be
122       the message parameter.
123
124       Additional keys corresponding to the fields defined for the particular
125       exception subclass will also be accepted.
126
127   MyException->new(...)
128       This method takes the same parameters as "throw", but instead of dying
129       simply returns a new exception object.
130
131       This method is always called when constructing a new exception object
132       via the "throw" method.
133
134   MyException->description
135       Returns the description for the given "Exception::Class::Base"
136       subclass. The "Exception::Class::Base" class's description is "Generic
137       exception" (this may change in the future). This is also an object
138       method.
139
140   $exception->rethrow
141       Simply dies with the object as its sole argument. It's just syntactic
142       sugar.  This does not change any of the object's attribute values.
143       However, it will cause "caller" to report the die as coming from within
144       the "Exception::Class::Base" class rather than where rethrow was
145       called.
146
147       Of course, you always have access to the original stacktrace for the
148       exception object.
149
150   $exception->message
151   $exception->error
152       Returns the error/message associated with the exception.
153
154   $exception->pid
155       Returns the pid at the time the exception was thrown.
156
157   $exception->uid
158       Returns the real user id at the time the exception was thrown.
159
160   $exception->gid
161       Returns the real group id at the time the exception was thrown.
162
163   $exception->euid
164       Returns the effective user id at the time the exception was thrown.
165
166   $exception->egid
167       Returns the effective group id at the time the exception was thrown.
168
169   $exception->time
170       Returns the time in seconds since the epoch at the time the exception
171       was thrown.
172
173   $exception->package
174       Returns the package from which the exception was thrown.
175
176   $exception->file
177       Returns the file within which the exception was thrown.
178
179   $exception->line
180       Returns the line where the exception was thrown.
181
182   $exception->context_hash
183       Returns a hash reference with the following keys:
184
185       •   time
186
187       •   pid
188
189       •   uid
190
191       •   euid
192
193       •   gid
194
195       •   egid
196
197   $exception->field_hash
198       Returns a hash reference where the keys are any fields defined for the
199       exception class and the values are the values associated with the field
200       in the given object.
201
202   $exception->trace
203       Returns the trace object associated with the object.
204
205   $exception->show_trace($boolean)
206       This method can be used to set whether or not a stack trace is included
207       when the as_string method is called or the object is stringified.
208
209   $exception->as_string
210       Returns a string form of the error message (something like what you'd
211       expect from die). If the class or object is set to show traces then
212       then the full trace is also included. The result looks like
213       "Carp::confess".
214
215   $exception->full_message
216       Called by the "as_string" method to get the message. By default, this
217       is the same as calling the "message" method, but may be overridden by a
218       subclass. See below for details.
219

LIGHTWEIGHT EXCEPTIONS

221       A lightweight exception is one which records no information about its
222       context when it is created. This can be achieved by setting
223       "$class->NoContextInfo" to a true value.
224
225       You can make this the default for a class of exceptions by setting it
226       after creating the class:
227
228         use Exception::Class (
229             'LightWeight',
230             'HeavyWeight',
231         );
232
233         LightWeight->NoContextInfo(1);
234
235       A lightweight exception does have a stack trace object, nor does it
236       record the time, pid, uid, euid, gid, or egid. It only has a message.
237

OVERLOADING

239       "Exception::Class::Base" objects are overloaded so that stringification
240       produces a normal error message. This just calls the
241       "$exception->as_string" method described above. This means that you can
242       just "print $@" after an "eval" and not worry about whether or not its
243       an actual object. It also means an application or module could do this:
244
245         $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
246
247       and this would probably not break anything (unless someone was
248       expecting a different type of exception object from "die").
249

OVERRIDING THE as_string METHOD

251       By default, the "as_string" method simply returns the value "message"
252       or "error" param plus a stack trace, if the class's "Trace" method
253       returns a true value or "show_trace" was set when creating the
254       exception.
255
256       However, once you add new fields to a subclass, you may want to include
257       those fields in the stringified error.
258
259       Inside the "as_string" method, the message (non-stack trace) portion of
260       the error is generated by calling the "full_message" method. This can
261       be easily overridden. For example:
262
263         sub full_message {
264             my $self = shift;
265
266             my $msg = $self->message;
267
268             $msg .= " and foo was " . $self->foo;
269
270             return $msg;
271         }
272

SUPPORT

274       Bugs may be submitted at
275       <https://github.com/houseabsolute/Exception-Class/issues>.
276
277       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
278

SOURCE

280       The source code repository for Exception-Class can be found at
281       <https://github.com/houseabsolute/Exception-Class>.
282

AUTHOR

284       Dave Rolsky <autarch@urth.org>
285

287       This software is copyright (c) 2021 by Dave Rolsky.
288
289       This is free software; you can redistribute it and/or modify it under
290       the same terms as the Perl 5 programming language system itself.
291
292       The full text of the license can be found in the LICENSE file included
293       with this distribution.
294
295
296
297perl v5.36.0                      2023-01-20         Exception::Class::Base(3)
Impressum