Profile of Exception/Class/Base.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For bin/dpath
Run on Tue Jun 5 15:31:33 2012
Reported on Tue Jun 5 15:31:49 2012

Filename | /home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Exception/Class/Base.pm
Statements | Executed 58 statements in 7.01ms

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