1Exception::Class::Base(U3s)er Contributed Perl DocumentatEixocneption::Class::Base(3)
2
6 Exception::Class::Base - Base class for exception classes created by
7 Exception::Class
8
10 use Exception::Class 'MyException';
11 eval { MyException->throw( error => 'I feel funny.' ) };
13 print $@->error();
15
17 This class is the base class for all exceptions created by
18 Exception::Class. It provides a number of methods for getting
19 information about the exception.
20
22 MyException->Trace($boolean)
23 Each "Exception::Class::Base" subclass can be set individually to
24 include a a stracktrace when the "as_string" method is called. The
25 default is to not include a stacktrace. Calling this method with a
26 value changes this behavior. It always returns the current value
27 (after any change is applied).
28 This value is inherited by any subclasses. However, if this value is
30 set for a subclass, it will thereafter be independent of the value in
31 "Exception::Class::Base".
32 Do not call this on the "Exception::Class::Base" class directly or
34 you'll change it for all exception classes that use Exception::Class,
35 including ones created in modules you don't control.
36 This is a class method, not an object method.
38 MyException->NoRefs($boolean)
40 When a "Devel::StackTrace" object is created, it walks through the
41 stack and stores the arguments which were passed to each subroutine on
42 the stack. If any of these arguments are references, then that means
43 that the "Devel::StackTrace" ends up increasing the refcount of these
44 references, delaying their destruction.
45 Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
47 this method provides a way to tell "Devel::StackTrace" not to store
48 these references. Instead, "Devel::StackTrace" replaces references
49 with their stringified representation.
50 This method defaults to true. As with "Trace()", it is inherited by
52 subclasses but setting it in a subclass makes it independent
53 thereafter.
54 Do not call this on the "Exception::Class::Base" class directly or
56 you'll change it for all exception classes that use Exception::Class,
57 including ones created in modules you don't control.
58 MyException->RespectOverload($boolean)
60 When a "Devel::StackTrace" object stringifies, by default it ignores
61 stringification overloading on any objects being dealt with.
62 Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
64 this method provides a way to tell "Devel::StackTrace" to respect
65 overloading.
66 This method defaults to false. As with "Trace()", it is inherited by
68 subclasses but setting it in a subclass makes it independent
69 thereafter.
70 Do not call this on the "Exception::Class::Base" class directly or
72 you'll change it for all exception classes that use Exception::Class,
73 including ones created in modules you don't control.
74 MyException->MaxArgLength($boolean)
76 When a "Devel::StackTrace" object stringifies, by default it displays
77 the full argument for each function. This parameter can be used to
78 limit the maximum length of each argument.
79 Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
81 this method provides a way to tell "Devel::StackTrace" to limit the
82 length of arguments.
83 This method defaults to 0. As with "Trace()", it is inherited by
85 subclasses but setting it in a subclass makes it independent
86 thereafter.
87 Do not call this on the "Exception::Class::Base" class directly or
89 you'll change it for all exception classes that use Exception::Class,
90 including ones created in modules you don't control.
91 MyException->Fields
93 This method returns the extra fields defined for the given class, as an
94 array.
95 Do not call this on the "Exception::Class::Base" class directly or
97 you'll change it for all exception classes that use Exception::Class,
98 including ones created in modules you don't control.
99 MyException->throw( $message )
101 MyException->throw( message => $message )
102 MyException->throw( error => $error )
103 This method creates a new object with the given error message. If no
104 error message is given, this will be an empty string. It then die's
105 with this object as its argument.
106 This method also takes a "show_trace" parameter which indicates whether
108 or not the particular exception object being created should show a
109 stacktrace when its "as_string()" method is called. This overrides the
110 value of "Trace()" for this class if it is given.
111 The frames included in the trace can be controlled by the
113 "ignore_class" and "ignore_package" parameters. These are passed
114 directly to Devel::Stacktrace's constructor. See "Devel::Stacktrace"
115 for more details.
116 If only a single value is given to the constructor it is assumed to be
118 the message parameter.
119 Additional keys corresponding to the fields defined for the particular
121 exception subclass will also be accepted.
122 MyException->new(...)
124 This method takes the same parameters as "throw()", but instead of
125 dying simply returns a new exception object.
126 This method is always called when constructing a new exception object
128 via the "throw()" method.
129 MyException->description()
131 Returns the description for the given "Exception::Class::Base"
132 subclass. The "Exception::Class::Base" class's description is "Generic
133 exception" (this may change in the future). This is also an object
134 method.
135 $exception->rethrow()
137 Simply dies with the object as its sole argument. It's just syntactic
138 sugar. This does not change any of the object's attribute values.
139 However, it will cause "caller()" to report the die as coming from
140 within the "Exception::Class::Base" class rather than where rethrow was
141 called.
142 Of course, you always have access to the original stacktrace for the
144 exception object.
145 $exception->message()
147 $exception->error()
148 Returns the error/message associated with the exception.
149 $exception->pid()
151 Returns the pid at the time the exception was thrown.
152 $exception->uid()
154 Returns the real user id at the time the exception was thrown.
155 $exception->gid()
157 Returns the real group id at the time the exception was thrown.
158 $exception->euid()
160 Returns the effective user id at the time the exception was thrown.
161 $exception->egid()
163 Returns the effective group id at the time the exception was thrown.
164 $exception->time()
166 Returns the time in seconds since the epoch at the time the exception
167 was thrown.
168 $exception->package()
170 Returns the package from which the exception was thrown.
171 $exception->file()
173 Returns the file within which the exception was thrown.
174 $exception->line()
176 Returns the line where the exception was thrown.
177 $exception->trace()
179 Returns the trace object associated with the object.
180 $exception->show_trace($boolean)
182 This method can be used to set whether or not a strack trace is
183 included when the as_string method is called or the object is
184 stringified.
185 $exception->as_string()
187 Returns a string form of the error message (something like what you'd
188 expect from die). If the class or object is set to show traces then
189 then the full trace is also included. The result looks like
190 "Carp::confess()".
191 $exception->full_message()
193 Called by the "as_string()" method to get the message. By default,
194 this is the same as calling the "message()" method, but may be
195 overridden by a subclass. See below for details.
196
198 "Exception::Class::Base" objects are overloaded so that stringification
199 produces a normal error message. This just calls the
200 "$exception->as_string()" method described above. This means that you
201 can just "print $@" after an "eval" and not worry about whether or not
202 its an actual object. It also means an application or module could do
203 this:
204 $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
206 and this would probably not break anything (unless someone was
208 expecting a different type of exception object from "die()").
209
211 By default, the "as_string()" method simply returns the value "message"
212 or "error" param plus a stack trace, if the class's "Trace()" method
213 returns a true value or "show_trace" was set when creating the
214 exception.
215 However, once you add new fields to a subclass, you may want to include
217 those fields in the stringified error.
218 Inside the "as_string()" method, the message (non-stack trace) portion
220 of the error is generated by calling the "full_message()" method. This
221 can be easily overridden. For example:
222 sub full_message
224 {
225 my $self = shift;
226 my $msg = $self->message;
228 $msg .= " and foo was " . $self->foo;
230 return $msg;
232 }
233
235 Dave Rolsky, >autarch@urth.org<
236
238 Copyright (c) 2000-2009 David Rolsky. All rights reserved. This
239 program is free software; you can redistribute it and/or modify it
240 under the same terms as Perl itself.
241 The full text of the license can be found in the LICENSE file included
243 with this module.
244perl v5.12.0 2010-05-01 Exception::Class::Base(3)