← Index
NYTProf Performance Profile   « block view • line view • sub view »
For bin/pan_genome_post_analysis
  Run on Fri Mar 27 11:43:32 2015
Reported on Fri Mar 27 11:45:27 2015

Filename/Users/ap13/perl5/lib/perl5/Bio/Root/Exception.pm
StatementsExecuted 13 statements in 1.14ms
Subroutines
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
11122µs49µsBio::Root::Exception::::BEGIN@2Bio::Root::Exception::BEGIN@2
0000s0sBio::Root::Exception::::_reformat_stacktraceBio::Root::Exception::_reformat_stacktrace
0000s0sBio::Root::Exception::::newBio::Root::Exception::new
0000s0sBio::Root::Exception::::pretty_formatBio::Root::Exception::pretty_format
0000s0sBio::Root::Exception::::stringifyBio::Root::Exception::stringify
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1package Bio::Root::Exception;
221.09ms276µs
# spent 49µs (22+27) within Bio::Root::Exception::BEGIN@2 which was called: # once (22µs+27µs) by Bio::Root::Root::BEGIN@146 at line 2
use strict;
# spent 49µs making 1 call to Bio::Root::Exception::BEGIN@2 # spent 27µs making 1 call to strict::import
3
4# ABSTRACT: generic exception objects for Bioperl
5# AUTHOR: Steve Chervitz <sac@bioperl.org>
6# OWNER: 2001 Steve Chervitz
7# LICENSE: Perl_5
8
9=head1 SYNOPSIS
10
11=head2 Throwing exceptions using L<Error.pm throw|Error::throw>:
12
13 use Bio::Root::Exception;
14 use Error;
15
16 # Set Error::Debug to include stack trace data in the error messages
17 $Error::Debug = 1;
18
19 $file = shift;
20 open my $IN, '<', $file
21 or Bio::Root::FileOpenException->throw("Could not read file '$file': $!");
22
23=head2 Throwing exceptions using L<Bioperl throw|Bio::Root::Root/throw>:
24
25 # Here we have an object that ISA Bio::Root::Root, so it inherits throw().
26
27 open my $IN, '<', $file
28 or $object->throw(-class => 'Bio::Root::FileOpenException',
29 -text => "Could not read file '$file'",
30 -value => $!);
31
32=head2 Catching and handling exceptions using L<Error.pm try|Error/try>:
33
34 use Bio::Root::Exception;
35 use Error qw(:try);
36
37 # Note that we need to import the 'try' tag from Error.pm
38
39 # Set Error::Debug to include stack trace data in the error messages
40 $Error::Debug = 1;
41
42 my $file = shift;
43 my $IN;
44 try {
45 open $IN, '<', $file
46 or Bio::Root::FileOpenException->throw("Could not read file '$file': $!");
47 }
48 catch Bio::Root::FileOpenException with {
49 my $err = shift;
50 print STDERR "Using default input file: $default_file\n";
51 open $IN, '<', $default_file or die "Could not read file '$default_file': $!";
52 }
53 otherwise {
54 my $err = shift;
55 print STDERR "An unexpected exception occurred: \n$err";
56
57 # By placing an the error object reference within double quotes,
58 # you're invoking its stringify() method.
59 }
60 finally {
61 # Any code that you want to execute regardless of whether or not
62 # an exception occurred.
63 };
64 # the ending semicolon is essential!
65
66
67=head2 Defining a new Exception type as a subclass of Bio::Root::Exception:
68
69 @Bio::TestException::ISA = qw( Bio::Root::Exception );
70
71=head1 DESCRIPTION
72
73=head2 Exceptions defined in L<Bio::Root::Exception>
74
75These are generic exceptions for typical problem situations that could arise
76in any module or script.
77
78=for :list
79* C<Bio::Root::Exception()>
80* C<Bio::Root::NotImplemented()>
81* C<Bio::Root::IOException()>
82* C<Bio::Root::FileOpenException()>
83* C<Bio::Root::SystemException()>
84* C<Bio::Root::BadParameter()>
85* C<Bio::Root::OutOfRange()>
86* C<Bio::Root::NoSuchThing()>
87
88Using defined exception classes like these is a good idea because it
89indicates the basic nature of what went wrong in a convenient,
90computable way.
91
92If there is a type of exception that you want to throw
93that is not covered by the classes listed above, it is easy to define
94a new one that fits your needs. Just write a line like the following
95in your module or script where you want to use it (or put it somewhere
96that is accessible to your code):
97
98 @NoCanDoException::ISA = qw( Bio::Root::Exception );
99
100All of the exceptions defined in this module inherit from a common
101base class exception, Bio::Root::Exception. This allows a user to
102write a handler for all Bioperl-derived exceptions as follows:
103
104 use Bio::Whatever;
105 use Error qw(:try);
106
107 try {
108 # some code that depends on Bioperl
109 }
110 catch Bio::Root::Exception with {
111 my $err = shift;
112 print "A Bioperl exception occurred:\n$err\n";
113 };
114
115So if you do create your own exceptions, just be sure they inherit
116from Bio::Root::Exception directly, or indirectly by inheriting from a
117Bio::Root::Exception subclass.
118
119The exceptions in Bio::Root::Exception are extensions of Graham Barr's
120L<Error> module available from CPAN. Despite this dependency, the
121L<Bio::Root::Exception> module does not explicitly C<require Error>.
122This permits Bio::Root::Exception to be loaded even when
123Error.pm is not available.
124
125=head2 Throwing exceptions within Bioperl modules
126
127Error.pm is not part of the Bioperl distibution, and may not be
128present within any given perl installation. So, when you want to
129throw an exception in a Bioperl module, the safe way to throw it
130is to use L<Bio::Root::Root/throw> which can use Error.pm
131when it's available. See documentation in Bio::Root::Root for details.
132
133=head1 SEE ALSO
134
135See the C<examples/exceptions> directory of the Bioperl distribution for
136working demo code.
137
138L<Bio::Root::Root/throw> for information about throwing
139L<Bio::Root::Exception>-based exceptions.
140
141L<Error> (available from CPAN, author: GBARR)
142
143Error.pm is helping to guide the design of exception handling in Perl 6.
144See these RFC's:
145
146 http://dev.perl.org/rfc/63.pod
147
148 http://dev.perl.org/rfc/88.pod
149
150=head1 EXCEPTIONS
151
152=cut
153
1541500nsmy $debug = $Error::Debug; # Prevents the "used only once" warning.
1551600nsmy $DEFAULT_VALUE = "__DUMMY__"; # Permits eval{} based handlers to work
156
157=head2 L<Bio::Root::Exception>
158
159 Purpose : A generic base class for all BioPerl exceptions.
160 By including a "catch Bio::Root::Exception" block, you
161 should be able to trap all BioPerl exceptions.
162 Example : throw Bio::Root::Exception("A generic exception", $!);
163
164=cut
165
166#---------------------------------------------------------
16718µs@Bio::Root::Exception::ISA = qw( Error );
168#---------------------------------------------------------
169
170=head1 Methods defined by Bio::Root::Exception
171
172=head2 new
173
174 Purpose : Guarantees that -value is set properly before
175 calling Error::new().
176
177 Arguments: key-value style arguments same as for Error::new()
178
179 You can also specify plain arguments as ($message, $value)
180 where $value is optional.
181
182 -value, if defined, must be non-zero and not an empty string
183 in order for eval{}-based exception handlers to work.
184 These require that if($@) evaluates to true, which will not
185 be the case if the Error has no value (Error overloads
186 numeric operations to the Error::value() method).
187
188 It is OK to create Bio::Root::Exception objects without
189 specifying -value. In this case, an invisible dummy value is used.
190
191 If you happen to specify a -value of zero (0), it will
192 be replaced by the string "The number zero (0)".
193
194 If you happen to specify a -value of empty string (""), it will
195 be replaced by the string "An empty string ("")".
196
197=cut
198
199sub new {
200 my ($class, @args) = @_;
201 my ($value, %params);
202 if( @args % 2 == 0 && $args[0] =~ /^-/) {
203 %params = @args;
204 $value = $params{'-value'};
205 }
206 else {
207 $params{-text} = $args[0];
208 $value = $args[1];
209 }
210
211 if( defined $value ) {
212 $value = "The number zero (0)" if $value =~ /^\d+$/ && $value == 0;
213 $value = "An empty string (\"\")" if $value eq "";
214 }
215 else {
216 $value ||= $DEFAULT_VALUE;
217 }
218 $params{-value} = $value;
219
220 my $self = $class->SUPER::new( %params );
221 return $self;
222}
223
224=head2 pretty_format()
225
226 Purpose : Get a nicely formatted string containing information about the
227 exception. Format is similar to that produced by
228 Bio::Root::Root::throw(), with the addition of the name of
229 the exception class in the EXCEPTION line and some other
230 data available via the Error object.
231 Example : print $error->pretty_format;
232
233=cut
234
235sub pretty_format {
236 my $self = shift;
237 my $msg = $self->text;
238 my $stack = '';
239 if( $Error::Debug ) {
240 $stack = $self->_reformat_stacktrace();
241 }
242 my $value_string = $self->value ne $DEFAULT_VALUE ? "VALUE: ".$self->value."\n" : "";
243 my $class = ref($self);
244
245 my $title = "------------- EXCEPTION: $class -------------";
246 my $footer = "\n" . '-' x CORE::length($title);
247 my $out = "\n$title\n"
248 . "MSG: $msg\n". $value_string. $stack. $footer . "\n";
249 return $out;
250}
251
252
253=head2 _reformat_stacktrace
254
255Reformatting of the stack performed by _reformat_stacktrace:
256for :list
2571. Shift the file:line data in line i to line i+1.
2582. change xxx::__ANON__() to "try{} block"
2593. skip the "require" and "Error::subs::try" stack entries (boring)
260
261This means that the first line in the stack won't have any file:line data
262But this isn't a big issue since it's for a Bio::Root::-based method
263that doesn't vary from exception to exception.
264
265=cut
266
267sub _reformat_stacktrace {
268 my $self = shift;
269 my $msg = $self->text;
270 my $stack = $self->stacktrace();
271 $stack =~ s/\Q$msg//;
272 my @stack = split( /\n/, $stack);
273 my @new_stack = ();
274 my ($method, $file, $linenum, $prev_file, $prev_linenum);
275 my $stack_count = 0;
276 foreach my $i( 0..$#stack ) {
277 # print "STACK-ORIG: $stack[$i]\n";
278 if( ($stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/) ||
279 ($stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/)) {
280 ($method, $file, $linenum) = ($1, $2, $3);
281 $stack_count++;
282 }
283 else{
284 next;
285 }
286 if( $stack_count == 1 ) {
287 push @new_stack, "STACK: $method";
288 ($prev_file, $prev_linenum) = ($file, $linenum);
289 next;
290 }
291
292 if( $method =~ /__ANON__/ ) {
293 $method = "try{} block";
294 }
295 if( ($method =~ /^require/ and $file =~ /Error\.pm/ ) ||
296 ($method =~ /^Error::subs::try/ ) ) {
297 last;
298 }
299 push @new_stack, "STACK: $method $prev_file:$prev_linenum";
300 ($prev_file, $prev_linenum) = ($file, $linenum);
301 }
302 push @new_stack, "STACK: $prev_file:$prev_linenum";
303
304 return join "\n", @new_stack;
305}
306
307=head2 stringify()
308
309 Purpose : Overrides Error::stringify() to call pretty_format().
310 This is called automatically when an exception object
311 is placed between double quotes.
312 Example : catch Bio::Root::Exception with {
313 my $error = shift;
314 print "$error";
315 }
316
317See Also: L<pretty_format()|pretty_format>
318
319=cut
320
321sub stringify {
322 my ($self, @args) = @_;
323 return $self->pretty_format( @args );
324}
325
326=head1 Subclasses of Bio::Root::Exception
327
328=head2 L<Bio::Root::NotImplemented>
329
330 Purpose : Indicates that a method has not been implemented.
331 Example : throw Bio::Root::NotImplemented(
332 -text => "Method \"foo\" not implemented in module FooBar.",
333 -value => "foo" );
334
335=cut
336
337#---------------------------------------------------------
33814µs@Bio::Root::NotImplemented::ISA = qw( Bio::Root::Exception );
339#---------------------------------------------------------
340
341=head2 L<Bio::Root::IOException>
342
343 Purpose : Indicates that some input/output-related trouble has occurred.
344 Example : throw Bio::Root::IOException(
345 -text => "Can't save data to file $file.",
346 -value => $! );
347
348=cut
349
350#---------------------------------------------------------
35114µs@Bio::Root::IOException::ISA = qw( Bio::Root::Exception );
352#---------------------------------------------------------
353
354
355=head2 L<Bio::Root::FileOpenException>
356
357 Purpose : Indicates that a file could not be opened.
358 Example : throw Bio::Root::FileOpenException(
359 -text => "Can't open file $file for reading.",
360 -value => $! );
361
362=cut
363
364#---------------------------------------------------------
36514µs@Bio::Root::FileOpenException::ISA = qw( Bio::Root::IOException );
366#---------------------------------------------------------
367
368
369=head2 L<Bio::Root::SystemException>
370
371 Purpose : Indicates that a system call failed.
372 Example : unlink($file) or throw Bio::Root::SystemException(
373 -text => "Can't unlink file $file.",
374 -value => $! );
375
376=cut
377
378#---------------------------------------------------------
37914µs@Bio::Root::SystemException::ISA = qw( Bio::Root::Exception );
380#---------------------------------------------------------
381
382
383=head2 L<Bio::Root::BadParameter>
384
385 Purpose : Indicates that one or more parameters supplied to a method
386 are invalid, unspecified, or conflicting.
387 Example : throw Bio::Root::BadParameter(
388 -text => "Required parameter \"-foo\" was not specified",
389 -value => "-foo" );
390
391=cut
392
393#---------------------------------------------------------
39413µs@Bio::Root::BadParameter::ISA = qw( Bio::Root::Exception );
395#---------------------------------------------------------
396
397
398=head2 L<Bio::Root::OutOfRange>
399
400 Purpose : Indicates that a specified (start,end) range or
401 an index to an array is outside the permitted range.
402 Example : throw Bio::Root::OutOfRange(
403 -text => "Start coordinate ($start) cannot be less than zero.",
404 -value => $start );
405
406=cut
407
408#---------------------------------------------------------
40914µs@Bio::Root::OutOfRange::ISA = qw( Bio::Root::Exception );
410#---------------------------------------------------------
411
412
413=head2 L<Bio::Root::NoSuchThing>
414
415 Purpose : Indicates that a requested thing cannot be located
416 and therefore could possibly be bogus.
417 Example : throw Bio::Root::NoSuchThing(
418 -text => "Accession M000001 could not be found.",
419 -value => "M000001" );
420
421=cut
422
423#---------------------------------------------------------
42413µs@Bio::Root::NoSuchThing::ISA = qw( Bio::Root::Exception );
425#---------------------------------------------------------
426
427113µs1;