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

NAME

6       Exception::Class::Base - Base class for exception classes created by
7       Exception::Class
8

SYNOPSIS

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

DESCRIPTION

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

METHODS

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
29       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
33       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
37       This is a class method, not an object method.
38
39   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
46       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
51       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
55       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
59   MyException->RespectOverload($boolean)
60       When a "Devel::StackTrace" object stringifies, by default it ignores
61       stringification overloading on any objects being dealt with.
62
63       Since "Exception::Class::Base" uses "Devel::StackTrace" internally,
64       this method provides a way to tell "Devel::StackTrace" to respect
65       overloading.
66
67       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
71       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
75   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
80       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
84       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
88       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
92   MyException->Fields
93       This method returns the extra fields defined for the given class, as an
94       array.
95
96       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
100   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
107       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
112       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
117       If only a single value is given to the constructor it is assumed to be
118       the message parameter.
119
120       Additional keys corresponding to the fields defined for the particular
121       exception subclass will also be accepted.
122
123   MyException->new(...)
124       This method takes the same parameters as "throw()", but instead of
125       dying simply returns a new exception object.
126
127       This method is always called when constructing a new exception object
128       via the "throw()" method.
129
130   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
136   $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
143       Of course, you always have access to the original stacktrace for the
144       exception object.
145
146   $exception->message()
147   $exception->error()
148       Returns the error/message associated with the exception.
149
150   $exception->pid()
151       Returns the pid at the time the exception was thrown.
152
153   $exception->uid()
154       Returns the real user id at the time the exception was thrown.
155
156   $exception->gid()
157       Returns the real group id at the time the exception was thrown.
158
159   $exception->euid()
160       Returns the effective user id at the time the exception was thrown.
161
162   $exception->egid()
163       Returns the effective group id at the time the exception was thrown.
164
165   $exception->time()
166       Returns the time in seconds since the epoch at the time the exception
167       was thrown.
168
169   $exception->package()
170       Returns the package from which the exception was thrown.
171
172   $exception->file()
173       Returns the file within which the exception was thrown.
174
175   $exception->line()
176       Returns the line where the exception was thrown.
177
178   $exception->trace()
179       Returns the trace object associated with the object.
180
181   $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
186   $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
192   $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

OVERLOADING

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
205        $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
206
207       and this would probably not break anything (unless someone was
208       expecting a different type of exception object from "die()").
209

OVERRIDING THE as_string METHOD

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
216       However, once you add new fields to a subclass, you may want to include
217       those fields in the stringified error.
218
219       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
223         sub full_message
224         {
225             my $self = shift;
226
227             my $msg = $self->message;
228
229             $msg .= " and foo was " . $self->foo;
230
231             return $msg;
232         }
233

AUTHOR

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
242       The full text of the license can be found in the LICENSE file included
243       with this module.
244
245
246
247perl v5.10.1                      2010-11-12         Exception::Class::Base(3)
Impressum