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.37
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
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
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->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
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
51       with their stringified representation.
52
53       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
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 an
96       array.
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
107       with 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.
118
119       If only a single value is given to the constructor it is assumed to be
120       the message parameter.
121
122       Additional keys corresponding to the fields defined for the particular
123       exception subclass will also be accepted.
124
125   MyException->new(...)
126       This method takes the same parameters as "throw()", but instead of
127       dying simply returns a new exception object.
128
129       This method is always called when constructing a new exception object
130       via the "throw()" method.
131
132   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
138   $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
145       Of course, you always have access to the original stacktrace for the
146       exception object.
147
148   $exception->message()
149   $exception->error()
150       Returns the error/message associated with the exception.
151
152   $exception->pid()
153       Returns the pid at the time the exception was thrown.
154
155   $exception->uid()
156       Returns the real user id at the time the exception was thrown.
157
158   $exception->gid()
159       Returns the real group id at the time the exception was thrown.
160
161   $exception->euid()
162       Returns the effective user id at the time the exception was thrown.
163
164   $exception->egid()
165       Returns the effective group id at the time the exception was thrown.
166
167   $exception->time()
168       Returns the time in seconds since the epoch at the time the exception
169       was thrown.
170
171   $exception->package()
172       Returns the package from which the exception was thrown.
173
174   $exception->file()
175       Returns the file within which the exception was thrown.
176
177   $exception->line()
178       Returns the line where the exception was thrown.
179
180   $exception->trace()
181       Returns the trace object associated with the object.
182
183   $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
187   $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
193   $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

LIGHTWEIGHT EXCEPTIONS

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
203       You can make this the default for a class of exceptions by setting it
204       after creating the class:
205
206         use Exception::Class (
207             'LightWeight',
208             'HeavyWeight',
209         );
210
211         LightWeight->NoContextInfo(1);
212
213       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

OVERLOADING

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

OVERRIDING THE as_string METHOD

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
235       However, once you add new fields to a subclass, you may want to include
236       those fields in the stringified error.
237
238       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
242         sub full_message {
243             my $self = shift;
244
245             my $msg = $self->message;
246
247             $msg .= " and foo was " . $self->foo;
248
249             return $msg;
250         }
251

AUTHOR

253       Dave Rolsky <autarch@urth.org>
254
256       This software is copyright (c) 2013 by Dave Rolsky.
257
258       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.
260
261
262
263perl v5.16.3                      2013-02-24         Exception::Class::Base(3)
Impressum