1Exception::Class::Base(U3s)er Contributed Perl DocumentatEixocneption::Class::Base(3)
2
6 Exception::Class::Base - A base class for exception objects
7
9 version 1.37
10
12 use Exception::Class 'MyException';
13 eval { MyException->throw( error => 'I feel funny.' ) };
15 print $@->error();
17
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
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
27 default is to not include a stacktrace. Calling this method with a
28 value changes this behavior. It always returns the current value
29 (after any change is applied).
30 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 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 This is a class method, not an object method.
40 MyException->NoRefs($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 refcount of these
46 references, delaying their destruction.
47 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
51 with their stringified representation.
52 This method defaults to true. As with "Trace()", it is inherited by
54 subclasses but setting it in a subclass makes it independent
55 thereafter.
56 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 MyException->RespectOverload($boolean)
62 When a "Devel::StackTrace" object stringifies, by default it ignores
63 stringification overloading on any objects being dealt with.
64 Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
66 this method provides a way to tell "Devel::StackTrace" to respect
67 overloading.
68 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 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 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 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 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 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 MyException->Fields
95 This method returns the extra fields defined for the given class, as an
96 array.
97 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 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
107 with this object as its argument.
108 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 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.
118 If only a single value is given to the constructor it is assumed to be
120 the message parameter.
121 Additional keys corresponding to the fields defined for the particular
123 exception subclass will also be accepted.
124 MyException->new(...)
126 This method takes the same parameters as "throw()", but instead of
127 dying simply returns a new exception object.
128 This method is always called when constructing a new exception object
130 via the "throw()" method.
131 MyException->description()
133 Returns the description for the given "Exception::Class::Base"
134 subclass. The "Exception::Class::Base" class's description is "Generic
135 exception" (this may change in the future). This is also an object
136 method.
137 $exception->rethrow()
139 Simply dies with the object as its sole argument. It's just syntactic
140 sugar. This does not change any of the object's attribute values.
141 However, it will cause "caller()" to report the die as coming from
142 within the "Exception::Class::Base" class rather than where rethrow was
143 called.
144 Of course, you always have access to the original stacktrace for the
146 exception object.
147 $exception->message()
149 $exception->error()
150 Returns the error/message associated with the exception.
151 $exception->pid()
153 Returns the pid at the time the exception was thrown.
154 $exception->uid()
156 Returns the real user id at the time the exception was thrown.
157 $exception->gid()
159 Returns the real group id at the time the exception was thrown.
160 $exception->euid()
162 Returns the effective user id at the time the exception was thrown.
163 $exception->egid()
165 Returns the effective group id at the time the exception was thrown.
166 $exception->time()
168 Returns the time in seconds since the epoch at the time the exception
169 was thrown.
170 $exception->package()
172 Returns the package from which the exception was thrown.
173 $exception->file()
175 Returns the file within which the exception was thrown.
176 $exception->line()
178 Returns the line where the exception was thrown.
179 $exception->trace()
181 Returns the trace object associated with the object.
182 $exception->show_trace($boolean)
184 This method can be used to set whether or not a stack trace is included
185 when the as_string method is called or the object is stringified.
186 $exception->as_string()
188 Returns a string form of the error message (something like what you'd
189 expect from die). If the class or object is set to show traces then
190 then the full trace is also included. The result looks like
191 "Carp::confess()".
192 $exception->full_message()
194 Called by the "as_string()" method to get the message. By default,
195 this is the same as calling the "message()" method, but may be
196 overridden by a subclass. See below for details.
197
199 A lightweight exception is one which records no information about its
200 context when it is created. This can be achieved by setting
201 "$class->NoContextInfo()" to a true value.
202 You can make this the default for a class of exceptions by setting it
204 after creating the class:
205 use Exception::Class (
207 'LightWeight',
208 'HeavyWeight',
209 );
210 LightWeight->NoContextInfo(1);
212 A lightweight exception does have a stack trace object, nor does it
214 record the time, pid, uid, euid, gid, or egid. It only has a message.
215
217 "Exception::Class::Base" objects are overloaded so that stringification
218 produces a normal error message. This just calls the
219 "$exception->as_string()" method described above. This means that you
220 can just "print $@" after an "eval" and not worry about whether or not
221 its an actual object. It also means an application or module could do
222 this:
223 $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
225 and this would probably not break anything (unless someone was
227 expecting a different type of exception object from "die()").
228
230 By default, the "as_string()" method simply returns the value "message"
231 or "error" param plus a stack trace, if the class's "Trace()" method
232 returns a true value or "show_trace" was set when creating the
233 exception.
234 However, once you add new fields to a subclass, you may want to include
236 those fields in the stringified error.
237 Inside the "as_string()" method, the message (non-stack trace) portion
239 of the error is generated by calling the "full_message()" method. This
240 can be easily overridden. For example:
241 sub full_message {
243 my $self = shift;
244 my $msg = $self->message;
246 $msg .= " and foo was " . $self->foo;
248 return $msg;
250 }
251
253 Dave Rolsky <autarch@urth.org>
254
256 This software is copyright (c) 2013 by Dave Rolsky.
257 This is free software; you can redistribute it and/or modify it under
259 the same terms as the Perl 5 programming language system itself.
260perl v5.16.3 2013-02-24 Exception::Class::Base(3)