Profile of /usr/local/lib/perl5/site_perl/5.10.1/Exception/Class/Base.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 01.HTTP.t
Run on Tue May 4 15:25:55 2010
Reported on Tue May 4 15:26:10 2010

File | /usr/local/lib/perl5/site_perl/5.10.1/Exception/Class/Base.pm
Statements Executed | 65
Statement Execution Time | 2.59ms

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 9.52ms | 9.58ms | Exception::Class::Base::::BEGIN@8Exception::Class::Base::BEGIN@8
1 | 1 | 1 | 3.76ms | 4.24ms | Exception::Class::Base::::BEGIN@9Exception::Class::Base::BEGIN@9
1 | 1 | 1 | 88µs | 88µs | Exception::Class::Base::::BEGIN@36Exception::Class::Base::BEGIN@36
1 | 1 | 1 | 45µs | 117µs | Exception::Class::Base::::BEGIN@14Exception::Class::Base::BEGIN@14
1 | 1 | 1 | 15µs | 101µs | Exception::Class::Base::::BEGIN@11Exception::Class::Base::BEGIN@11
1 | 1 | 1 | 14µs | 17µs | Exception::Class::Base::::BEGIN@3Exception::Class::Base::BEGIN@3
1 | 1 | 1 | 14µs | 42µs | Exception::Class::Base::::BEGIN@4Exception::Class::Base::BEGIN@4
1 | 1 | 1 | 13µs | 70µs | Exception::Class::Base::::BEGIN@30Exception::Class::Base::BEGIN@30
1 | 1 | 1 | 12µs | 27µs | Exception::Class::Base::::BEGIN@65Exception::Class::Base::BEGIN@65
1 | 1 | 1 | 12µs | 38µs | Exception::Class::Base::::BEGIN@43Exception::Class::Base::BEGIN@43
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::ClassesException::Class::Base::Classes
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::FieldsException::Class::Base::Fields
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::__ANON__[:30]Exception::Class::Base::__ANON__[:30]
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::__ANON__[:41]Exception::Class::Base::__ANON__[:41]
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::__ANON__[:64]Exception::Class::Base::__ANON__[:64]
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::_initializeException::Class::Base::_initialize
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::as_stringException::Class::Base::as_string
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::caughtException::Class::Base::caught
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::descriptionException::Class::Base::description
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::full_messageException::Class::Base::full_message
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::newException::Class::Base::new
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::rethrowException::Class::Base::rethrow
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::show_traceException::Class::Base::show_trace
0 | 0 | 0 | 0s | 0s | Exception::Class::Base::::throwException::Class::Base::throw

Call graph for these subroutines as a Graphviz dot language file.

Line | State ments | Time on line | Calls | Time in subs | Code
--- | --- | --- | --- | --- | ---
1 |  |  |  |  | package Exception::Class::Base;
2 |  |  |  |  |
3 | 3 | 25µs | 2 | 19µs | # spent 17µs (14+2) within Exception::Class::Base::BEGIN@3 which was called # once (14µs+2µs) by Exception::Class::BEGIN@7 at line 3 use strict; # spent 17µs making 1 call to Exception::Class::Base::BEGIN@3 # spent 2µs making 1 call to strict::import
4 | 3 | 34µs | 2 | 69µs | # spent 42µs (14+28) within Exception::Class::Base::BEGIN@4 which was called # once (14µs+28µs) by Exception::Class::BEGIN@7 at line 4 use warnings; # spent 42µs making 1 call to Exception::Class::Base::BEGIN@4 # spent 28µs making 1 call to warnings::import
5 |  |  |  |  |
6 | 1 | 2µs |  |  | our $VERSION = '1.20';
7 |  |  |  |  |
8 | 3 | 195µs | 1 | 9.58ms | # spent 9.58ms (9.52+58µs) within Exception::Class::Base::BEGIN@8 which was called # once (9.52ms+58µs) by Exception::Class::BEGIN@7 at line 8 use Class::Data::Inheritable; # spent 9.58ms making 1 call to Exception::Class::Base::BEGIN@8
9 | 3 | 316µs | 2 | 4.30ms | # spent 4.24ms (3.76+488µs) within Exception::Class::Base::BEGIN@9 which was called # once (3.76ms+488µs) by Exception::Class::BEGIN@7 at line 9 use Devel::StackTrace 1.20; # spent 4.24ms making 1 call to Exception::Class::Base::BEGIN@9 # spent 59µs making 1 call to UNIVERSAL::VERSION
10 |  |  |  |  |
11 | 3 | 103µs | 2 | 187µs | # spent 101µs (15+86) within Exception::Class::Base::BEGIN@11 which was called # once (15µs+86µs) by Exception::Class::BEGIN@7 at line 11 use base qw(Class::Data::Inheritable); # spent 101µs making 1 call to Exception::Class::Base::BEGIN@11 # spent 86µs making 1 call to base::import
12 |  |  |  |  |
13 |  |  |  |  | BEGIN
14 |  |  |  |  | # spent 117µs (45+73) within Exception::Class::Base::BEGIN@14 which was called # once (45µs+73µs) by Exception::Class::BEGIN@7 at line 26 {
15 | 7 | 19µs | 1 | 18µs | __PACKAGE__->mk_classdata('Trace'); # spent 18µs making 1 call to Class::Data::Inheritable::mk_classdata
16 |  |  |  |  | __PACKAGE__->mk_classdata('NoRefs'); # spent 21µs making 1 call to Class::Data::Inheritable::mk_classdata
17 |  |  |  |  | __PACKAGE__->NoRefs(1); # spent 5µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23]
18 |  |  |  |  |
19 |  |  |  |  | __PACKAGE__->mk_classdata('RespectOverload'); # spent 12µs making 1 call to Class::Data::Inheritable::mk_classdata
20 |  |  |  |  | __PACKAGE__->RespectOverload(0); # spent 3µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23]
21 |  |  |  |  |
22 |  |  |  |  | __PACKAGE__->mk_classdata('MaxArgLength'); # spent 10µs making 1 call to Class::Data::Inheritable::mk_classdata
23 |  |  |  |  | __PACKAGE__->MaxArgLength(0); # spent 3µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23]
24 |  |  |  |  |
25 |  |  |  |  | sub Fields { () }
26 | 1 | 69µs | 1 | 117µs | } # spent 117µs making 1 call to Exception::Class::Base::BEGIN@14
27 |  |  |  |  |
28 |  |  |  |  | use overload
29 |  |  |  |  | # an exception is always true
30 |  |  |  |  | # spent 70µs (13+57) within Exception::Class::Base::BEGIN@30 which was called # once (13µs+57µs) by Exception::Class::BEGIN@7 at line 32 bool => sub { 1 },
31 |  |  |  |  | '""' => 'as_string', # spent 57µs making 1 call to overload::import
32 | 3 | 104µs | 1 | 70µs | fallback => 1; # spent 70µs making 1 call to Exception::Class::Base::BEGIN@30
33 |  |  |  |  |
34 |  |  |  |  | # Create accessor routines
35 |  |  |  |  | BEGIN
36 |  |  |  |  | # spent 88µs within Exception::Class::Base::BEGIN@36 which was called # once (88µs+0s) by Exception::Class::BEGIN@7 at line 68 {
37 | 5 | 19µs |  |  | my @fields = qw( message pid uid euid gid egid time trace );
38 |  |  |  |  |
39 |  |  |  |  | foreach my $f (@fields)
40 |  |  |  |  | {
41 | 16 | 39µs |  |  | my $sub = sub { my $s = shift; return $s->{$f}; };
42 |  |  |  |  |
43 | 3 | 184µs | 2 | 64µs | # spent 38µs (12+26) within Exception::Class::Base::BEGIN@43 which was called # once (12µs+26µs) by Exception::Class::BEGIN@7 at line 43 no strict 'refs'; # spent 38µs making 1 call to Exception::Class::Base::BEGIN@43 # spent 26µs making 1 call to strict::unimport
44 |  |  |  |  | *{$f} = $sub;
45 |  |  |  |  | }
46 |  |  |  |  | *error = \&message;
47 |  |  |  |  |
48 |  |  |  |  | my %trace_fields =
49 |  |  |  |  | ( package => 'package',
50 |  |  |  |  | file => 'filename',
51 |  |  |  |  | line => 'line',
52 |  |  |  |  | );
53 |  |  |  |  |
54 | 6 | 23µs |  |  | while ( my ( $f, $m ) = each %trace_fields )
55 |  |  |  |  | {
56 |  |  |  |  | my $sub = sub
57 |  |  |  |  | {
58 |  |  |  |  | my $s = shift;
59 |  |  |  |  | return $s->{$f} if exists $s->{$f};
60 |  |  |  |  |
61 |  |  |  |  | my $frame = $s->trace->frame(0);
62 |  |  |  |  |
63 |  |  |  |  | return $s->{$f} = $frame ? $frame->$m() : undef;
64 | 1 | 4µs |  |  | };
65 | 3 | 47µs | 2 | 43µs | # spent 27µs (12+16) within Exception::Class::Base::BEGIN@65 which was called # once (12µs+16µs) by Exception::Class::BEGIN@7 at line 65 no strict 'refs'; # spent 27µs making 1 call to Exception::Class::Base::BEGIN@65 # spent 16µs making 1 call to strict::unimport
66 |  |  |  |  | *{$f} = $sub;
67 |  |  |  |  | }
68 | 1 | 1.39ms | 1 | 88µs | } # spent 88µs making 1 call to Exception::Class::Base::BEGIN@36
69 |  |  |  |  |
70 | 1 | 100ns |  |  | 1;
71 |  |  |  |  |
72 |  |  |  |  | sub Classes { Exception::Class::Classes() }
73 |  |  |  |  |
74 |  |  |  |  | sub throw
75 |  |  |  |  | {
76 |  |  |  |  | my $proto = shift;
77 |  |  |  |  |
78 |  |  |  |  | $proto->rethrow if ref $proto;
79 |  |  |  |  |
80 |  |  |  |  | die $proto->new(@_);
81 |  |  |  |  | }
82 |  |  |  |  |
83 |  |  |  |  | sub rethrow
84 |  |  |  |  | {
85 |  |  |  |  | my $self = shift;
86 |  |  |  |  |
87 |  |  |  |  | die $self;
88 |  |  |  |  | }
89 |  |  |  |  |
90 |  |  |  |  | sub new
91 |  |  |  |  | {
92 |  |  |  |  | my $proto = shift;
93 |  |  |  |  | my $class = ref $proto || $proto;
94 |  |  |  |  |
95 |  |  |  |  | my $self = bless {}, $class;
96 |  |  |  |  |
97 |  |  |  |  | $self->_initialize(@_);
98 |  |  |  |  |
99 |  |  |  |  | return $self;
100 |  |  |  |  | }
101 |  |  |  |  |
102 |  |  |  |  | sub _initialize
103 |  |  |  |  | {
104 |  |  |  |  | my $self = shift;
105 |  |  |  |  | my %p = @_ == 1 ? ( error => $_[0] ) : @_;
106 |  |  |  |  |
107 |  |  |  |  | $self->{message} = $p{message} || $p{error} || '';
108 |  |  |  |  |
109 |  |  |  |  | $self->{show_trace} = $p{show_trace} if exists $p{show_trace};
110 |  |  |  |  |
111 |  |  |  |  | # CORE::time is important to fix an error with some versions of
112 |  |  |  |  | # Perl
113 |  |  |  |  | $self->{time} = CORE::time();
114 |  |  |  |  | $self->{pid} = $$;
115 |  |  |  |  | $self->{uid} = $<;
116 |  |  |  |  | $self->{euid} = $>;
117 |  |  |  |  | $self->{gid} = $(;
118 |  |  |  |  | $self->{egid} = $);
119 |  |  |  |  |
120 |  |  |  |  | my @ignore_class = (__PACKAGE__);
121 |  |  |  |  | my @ignore_package = 'Exception::Class';
122 |  |  |  |  |
123 |  |  |  |  | if ( my $i = delete $p{ignore_class} )
124 |  |  |  |  | {
125 |  |  |  |  | push @ignore_class, ( ref($i) eq 'ARRAY' ? @$i : $i );
126 |  |  |  |  | }
127 |  |  |  |  |
128 |  |  |  |  | if ( my $i = delete $p{ignore_package} )
129 |  |  |  |  | {
130 |  |  |  |  | push @ignore_package, ( ref($i) eq 'ARRAY' ? @$i : $i );
131 |  |  |  |  | }
132 |  |  |  |  |
133 |  |  |  |  | $self->{trace} =
134 |  |  |  |  | Devel::StackTrace->new( ignore_class => \@ignore_class,
135 |  |  |  |  | ignore_package => \@ignore_package,
136 |  |  |  |  | no_refs => $self->NoRefs,
137 |  |  |  |  | respect_overload => $self->RespectOverload,
138 |  |  |  |  | max_arg_length => $self->MaxArgLength,
139 |  |  |  |  | );
140 |  |  |  |  |
141 |  |  |  |  | my %fields = map { $_ => 1 } $self->Fields;
142 |  |  |  |  | while ( my ($key, $value) = each %p )
143 |  |  |  |  | {
144 |  |  |  |  | next if $key =~ /^(?:error|message|show_trace)$/;
145 |  |  |  |  |
146 |  |  |  |  | if ( $fields{$key})
147 |  |  |  |  | {
148 |  |  |  |  | $self->{$key} = $value;
149 |  |  |  |  | }
150 |  |  |  |  | else
151 |  |  |  |  | {
152 |  |  |  |  | Exception::Class::Base->throw
153 |  |  |  |  | ( error =>
154 |  |  |  |  | "unknown field $key passed to constructor for class " . ref $self );
155 |  |  |  |  | }
156 |  |  |  |  | }
157 |  |  |  |  | }
158 |  |  |  |  |
159 |  |  |  |  | sub description
160 |  |  |  |  | {
161 |  |  |  |  | return 'Generic exception';
162 |  |  |  |  | }
163 |  |  |  |  |
164 |  |  |  |  | sub show_trace
165 |  |  |  |  | {
166 |  |  |  |  | my $self = shift;
167 |  |  |  |  |
168 |  |  |  |  | if (@_)
169 |  |  |  |  | {
170 |  |  |  |  | $self->{show_trace} = shift;
171 |  |  |  |  | }
172 |  |  |  |  |
173 |  |  |  |  | return exists $self->{show_trace} ? $self->{show_trace} : $self->Trace;
174 |  |  |  |  | }
175 |  |  |  |  |
176 |  |  |  |  | sub as_string
177 |  |  |  |  | {
178 |  |  |  |  | my $self = shift;
179 |  |  |  |  |
180 |  |  |  |  | my $str = $self->full_message;
181 |  |  |  |  | $str .= "\n\n" . $self->trace->as_string
182 |  |  |  |  | if $self->show_trace;
183 |  |  |  |  |
184 |  |  |  |  | return $str;
185 |  |  |  |  | }
186 |  |  |  |  |
187 |  |  |  |  | sub full_message { $_[0]->{message} }
188 |  |  |  |  |
189 |  |  |  |  | #
190 |  |  |  |  | # The %seen bit protects against circular inheritance.
191 |  |  |  |  | #
192 | 1 | 2µs |  |  | eval <<'EOF' if $] == 5.006;
193 |  |  |  |  | sub isa
194 |  |  |  |  | {
195 |  |  |  |  | my ($inheritor, $base) = @_;
196 |  |  |  |  | $inheritor = ref($inheritor) if ref($inheritor);
197 |  |  |  |  |
198 |  |  |  |  | my %seen;
199 |  |  |  |  |
200 |  |  |  |  | no strict 'refs';
201 |  |  |  |  | my @parents = ($inheritor, @{"$inheritor\::ISA"});
202 |  |  |  |  | while (my $class = shift @parents)
203 |  |  |  |  | {
204 |  |  |  |  | return 1 if $class eq $base;
205 |  |  |  |  |
206 |  |  |  |  | push @parents, grep {!$seen{$_}++} @{"$class\::ISA"};
207 |  |  |  |  | }
208 |  |  |  |  | return 0;
209 |  |  |  |  | }
210 |  |  |  |  | EOF
211 |  |  |  |  |
212 |  |  |  |  | sub caught
213 |  |  |  |  | {
214 |  |  |  |  | return Exception::Class->caught(shift);
215 |  |  |  |  | }
216 |  |  |  |  |
217 | 1 | 14µs |  |  | 1;
218 |  |  |  |  |
219 |  |  |  |  | =head1 NAME
220 |  |  |  |  |
221 |  |  |  |  | Exception::Class::Base - Base class for exception classes created by Exception::Class
222 |  |  |  |  |
223 |  |  |  |  | =head1 SYNOPSIS
224 |  |  |  |  |
225 |  |  |  |  | use Exception::Class 'MyException';
226 |  |  |  |  |
227 |  |  |  |  | eval { MyException->throw( error => 'I feel funny.' ) };
228 |  |  |  |  |
229 |  |  |  |  | print $@->error();
230 |  |  |  |  |
231 |  |  |  |  | =head1 DESCRIPTION
232 |  |  |  |  |
233 |  |  |  |  | This class is the base class for all exceptions created by
234 |  |  |  |  | L<Exception::Class>. It provides a number of methods for getting
235 |  |  |  |  | information about the exception.
236 |  |  |  |  |
237 |  |  |  |  | =head1 METHODS
238 |  |  |  |  |
239 |  |  |  |  | =head2 MyException->Trace($boolean)
240 |  |  |  |  |
241 |  |  |  |  | Each C<Exception::Class::Base> subclass can be set individually to
242 |  |  |  |  | include a a stracktrace when the C<as_string> method is called. The
243 |  |  |  |  | default is to not include a stacktrace. Calling this method with a
244 |  |  |  |  | value changes this behavior. It always returns the current value
245 |  |  |  |  | (after any change is applied).
246 |  |  |  |  |
247 |  |  |  |  | This value is inherited by any subclasses. However, if this value is
248 |  |  |  |  | set for a subclass, it will thereafter be independent of the value in
249 |  |  |  |  | C<Exception::Class::Base>.
250 |  |  |  |  |
251 |  |  |  |  | Do not call this on the C<Exception::Class::Base> class directly or
252 |  |  |  |  | you'll change it for all exception classes that use
253 |  |  |  |  | L<Exception::Class>, including ones created in modules you don't
254 |  |  |  |  | control.
255 |  |  |  |  |
256 |  |  |  |  | This is a class method, not an object method.
257 |  |  |  |  |
258 |  |  |  |  | =head2 MyException->NoRefs($boolean)
259 |  |  |  |  |
260 |  |  |  |  | When a C<Devel::StackTrace> object is created, it walks through the
261 |  |  |  |  | stack and stores the arguments which were passed to each subroutine on
262 |  |  |  |  | the stack. If any of these arguments are references, then that means
263 |  |  |  |  | that the C<Devel::StackTrace> ends up increasing the refcount of these
264 |  |  |  |  | references, delaying their destruction.
265 |  |  |  |  |
266 |  |  |  |  | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally,
267 |  |  |  |  | this method provides a way to tell C<Devel::StackTrace> not to store
268 |  |  |  |  | these references. Instead, C<Devel::StackTrace> replaces references
269 |  |  |  |  | with their stringified representation.
270 |  |  |  |  |
271 |  |  |  |  | This method defaults to true. As with C<Trace()>, it is inherited by
272 |  |  |  |  | subclasses but setting it in a subclass makes it independent
273 |  |  |  |  | thereafter.
274 |  |  |  |  |
275 |  |  |  |  | Do not call this on the C<Exception::Class::Base> class directly or
276 |  |  |  |  | you'll change it for all exception classes that use
277 |  |  |  |  | L<Exception::Class>, including ones created in modules you don't
278 |  |  |  |  | control.
279 |  |  |  |  |
280 |  |  |  |  | =head2 MyException->RespectOverload($boolean)
281 |  |  |  |  |
282 |  |  |  |  | When a C<Devel::StackTrace> object stringifies, by default it ignores
283 |  |  |  |  | stringification overloading on any objects being dealt with.
284 |  |  |  |  |
285 |  |  |  |  | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally,
286 |  |  |  |  | this method provides a way to tell C<Devel::StackTrace> to respect
287 |  |  |  |  | overloading.
288 |  |  |  |  |
289 |  |  |  |  | This method defaults to false. As with C<Trace()>, it is inherited by
290 |  |  |  |  | subclasses but setting it in a subclass makes it independent
291 |  |  |  |  | thereafter.
292 |  |  |  |  |
293 |  |  |  |  | Do not call this on the C<Exception::Class::Base> class directly or
294 |  |  |  |  | you'll change it for all exception classes that use
295 |  |  |  |  | L<Exception::Class>, including ones created in modules you don't
296 |  |  |  |  | control.
297 |  |  |  |  |
298 |  |  |  |  | =head2 MyException->MaxArgLength($boolean)
299 |  |  |  |  |
300 |  |  |  |  | When a C<Devel::StackTrace> object stringifies, by default it displays
301 |  |  |  |  | the full argument for each function. This parameter can be used to
302 |  |  |  |  | limit the maximum length of each argument.
303 |  |  |  |  |
304 |  |  |  |  | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally,
305 |  |  |  |  | this method provides a way to tell C<Devel::StackTrace> to limit the
306 |  |  |  |  | length of arguments.
307 |  |  |  |  |
308 |  |  |  |  | This method defaults to 0. As with C<Trace()>, it is inherited by
309 |  |  |  |  | subclasses but setting it in a subclass makes it independent
310 |  |  |  |  | thereafter.
311 |  |  |  |  |
312 |  |  |  |  | Do not call this on the C<Exception::Class::Base> class directly or
313 |  |  |  |  | you'll change it for all exception classes that use
314 |  |  |  |  | L<Exception::Class>, including ones created in modules you don't
315 |  |  |  |  | control.
316 |  |  |  |  |
317 |  |  |  |  | =head2 MyException->Fields
318 |  |  |  |  |
319 |  |  |  |  | This method returns the extra fields defined for the given class, as
320 |  |  |  |  | an array.
321 |  |  |  |  |
322 |  |  |  |  | Do not call this on the C<Exception::Class::Base> class directly or
323 |  |  |  |  | you'll change it for all exception classes that use
324 |  |  |  |  | L<Exception::Class>, including ones created in modules you don't
325 |  |  |  |  | control.
326 |  |  |  |  |
327 |  |  |  |  | =head2 MyException->throw( $message )
328 |  |  |  |  |
329 |  |  |  |  | =head2 MyException->throw( message => $message )
330 |  |  |  |  |
331 |  |  |  |  | =head2 MyException->throw( error => $error )
332 |  |  |  |  |
333 |  |  |  |  | This method creates a new object with the given error message. If no
334 |  |  |  |  | error message is given, this will be an empty string. It then die's
335 |  |  |  |  | with this object as its argument.
336 |  |  |  |  |
337 |  |  |  |  | This method also takes a C<show_trace> parameter which indicates
338 |  |  |  |  | whether or not the particular exception object being created should
339 |  |  |  |  | show a stacktrace when its C<as_string()> method is called. This
340 |  |  |  |  | overrides the value of C<Trace()> for this class if it is given.
341 |  |  |  |  |
342 |  |  |  |  | The frames included in the trace can be controlled by the C<ignore_class>
343 |  |  |  |  | and C<ignore_package> parameters. These are passed directly to
344 |  |  |  |  | Devel::Stacktrace's constructor. See C<Devel::Stacktrace> for more details.
345 |  |  |  |  |
346 |  |  |  |  | If only a single value is given to the constructor it is assumed to be
347 |  |  |  |  | the message parameter.
348 |  |  |  |  |
349 |  |  |  |  | Additional keys corresponding to the fields defined for the particular
350 |  |  |  |  | exception subclass will also be accepted.
351 |  |  |  |  |
352 |  |  |  |  | =head2 MyException->new(...)
353 |  |  |  |  |
354 |  |  |  |  | This method takes the same parameters as C<throw()>, but instead of
355 |  |  |  |  | dying simply returns a new exception object.
356 |  |  |  |  |
357 |  |  |  |  | This method is always called when constructing a new exception object
358 |  |  |  |  | via the C<throw()> method.
359 |  |  |  |  |
360 |  |  |  |  | =head2 MyException->description()
361 |  |  |  |  |
362 |  |  |  |  | Returns the description for the given C<Exception::Class::Base>
363 |  |  |  |  | subclass. The C<Exception::Class::Base> class's description is
364 |  |  |  |  | "Generic exception" (this may change in the future). This is also an
365 |  |  |  |  | object method.
366 |  |  |  |  |
367 |  |  |  |  | =head2 $exception->rethrow()
368 |  |  |  |  |
369 |  |  |  |  | Simply dies with the object as its sole argument. It's just syntactic
370 |  |  |  |  | sugar. This does not change any of the object's attribute values.
371 |  |  |  |  | However, it will cause C<caller()> to report the die as coming from
372 |  |  |  |  | within the C<Exception::Class::Base> class rather than where rethrow
373 |  |  |  |  | was called.
374 |  |  |  |  |
375 |  |  |  |  | Of course, you always have access to the original stacktrace for the
376 |  |  |  |  | exception object.
377 |  |  |  |  |
378 |  |  |  |  | =head2 $exception->message()
379 |  |  |  |  |
380 |  |  |  |  | =head2 $exception->error()
381 |  |  |  |  |
382 |  |  |  |  | Returns the error/message associated with the exception.
383 |  |  |  |  |
384 |  |  |  |  | =head2 $exception->pid()
385 |  |  |  |  |
386 |  |  |  |  | Returns the pid at the time the exception was thrown.
387 |  |  |  |  |
388 |  |  |  |  | =head2 $exception->uid()
389 |  |  |  |  |
390 |  |  |  |  | Returns the real user id at the time the exception was thrown.
391 |  |  |  |  |
392 |  |  |  |  | =head2 $exception->gid()
393 |  |  |  |  |
394 |  |  |  |  | Returns the real group id at the time the exception was thrown.
395 |  |  |  |  |
396 |  |  |  |  | =head2 $exception->euid()
397 |  |  |  |  |
398 |  |  |  |  | Returns the effective user id at the time the exception was thrown.
399 |  |  |  |  |
400 |  |  |  |  | =head2 $exception->egid()
401 |  |  |  |  |
402 |  |  |  |  | Returns the effective group id at the time the exception was thrown.
403 |  |  |  |  |
404 |  |  |  |  | =head2 $exception->time()
405 |  |  |  |  |
406 |  |  |  |  | Returns the time in seconds since the epoch at the time the exception
407 |  |  |  |  | was thrown.
408 |  |  |  |  |
409 |  |  |  |  | =head2 $exception->package()
410 |  |  |  |  |
411 |  |  |  |  | Returns the package from which the exception was thrown.
412 |  |  |  |  |
413 |  |  |  |  | =head2 $exception->file()
414 |  |  |  |  |
415 |  |  |  |  | Returns the file within which the exception was thrown.
416 |  |  |  |  |
417 |  |  |  |  | =head2 $exception->line()
418 |  |  |  |  |
419 |  |  |  |  | Returns the line where the exception was thrown.
420 |  |  |  |  |
421 |  |  |  |  | =head2 $exception->trace()
422 |  |  |  |  |
423 |  |  |  |  | Returns the trace object associated with the object.
424 |  |  |  |  |
425 |  |  |  |  | =head2 $exception->show_trace($boolean)
426 |  |  |  |  |
427 |  |  |  |  | This method can be used to set whether or not a strack trace is
428 |  |  |  |  | included when the as_string method is called or the object is
429 |  |  |  |  | stringified.
430 |  |  |  |  |
431 |  |  |  |  | =head2 $exception->as_string()
432 |  |  |  |  |
433 |  |  |  |  | Returns a string form of the error message (something like what you'd
434 |  |  |  |  | expect from die). If the class or object is set to show traces then
435 |  |  |  |  | then the full trace is also included. The result looks like
436 |  |  |  |  | C<Carp::confess()>.
437 |  |  |  |  |
438 |  |  |  |  | =head2 $exception->full_message()
439 |  |  |  |  |
440 |  |  |  |  | Called by the C<as_string()> method to get the message. By default,
441 |  |  |  |  | this is the same as calling the C<message()> method, but may be
442 |  |  |  |  | overridden by a subclass. See below for details.
443 |  |  |  |  |
444 |  |  |  |  | =head1 OVERLOADING
445 |  |  |  |  |
446 |  |  |  |  | C<Exception::Class::Base> objects are overloaded so that
447 |  |  |  |  | stringification produces a normal error message. This just calls the
448 |  |  |  |  | C<< $exception->as_string() >> method described above. This means
449 |  |  |  |  | that you can just C<print $@> after an C<eval> and not worry about
450 |  |  |  |  | whether or not its an actual object. It also means an application or
451 |  |  |  |  | module could do this:
452 |  |  |  |  |
453 |  |  |  |  | $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };
454 |  |  |  |  |
455 |  |  |  |  | and this would probably not break anything (unless someone was
456 |  |  |  |  | expecting a different type of exception object from C<die()>).
457 |  |  |  |  |
458 |  |  |  |  | =head1 OVERRIDING THE as_string METHOD
459 |  |  |  |  |
460 |  |  |  |  | By default, the C<as_string()> method simply returns the value
461 |  |  |  |  | C<message> or C<error> param plus a stack trace, if the class's
462 |  |  |  |  | C<Trace()> method returns a true value or C<show_trace> was set when
463 |  |  |  |  | creating the exception.
464 |  |  |  |  |
465 |  |  |  |  | However, once you add new fields to a subclass, you may want to
466 |  |  |  |  | include those fields in the stringified error.
467 |  |  |  |  |
468 |  |  |  |  | Inside the C<as_string()> method, the message (non-stack trace)
469 |  |  |  |  | portion of the error is generated by calling the C<full_message()>
470 |  |  |  |  | method. This can be easily overridden. For example:
471 |  |  |  |  |
472 |  |  |  |  | sub full_message
473 |  |  |  |  | {
474 |  |  |  |  | my $self = shift;
475 |  |  |  |  |
476 |  |  |  |  | my $msg = $self->message;
477 |  |  |  |  |
478 |  |  |  |  | $msg .= " and foo was " . $self->foo;
479 |  |  |  |  |
480 |  |  |  |  | return $msg;
481 |  |  |  |  | }
482 |  |  |  |  |
483 |  |  |  |  | =head1 AUTHOR
484 |  |  |  |  |
485 |  |  |  |  | Dave Rolsky, E<gt>autarch@urth.orgE<lt>
486 |  |  |  |  |
487 |  |  |  |  | =head1 COPYRIGHT
488 |  |  |  |  |
489 |  |  |  |  | Copyright (c) 2000-2009 David Rolsky. All rights reserved. This
490 |  |  |  |  | program is free software; you can redistribute it and/or modify it
491 |  |  |  |  | under the same terms as Perl itself.
492 |  |  |  |  |
493 |  |  |  |  | The full text of the license can be found in the LICENSE file included
494 |  |  |  |  | with this module.
495 |  |  |  |  |
496 |  |  |  |  | =cut