Bio/Root/Exception.pm

filter: Statementstmt 97.0% 65 / 67 Branchbran 70.0% 14 / 20 Conditioncond 50.0% 9 / 18 MC/DCmcdc 27.2% 3 / 11 Subroutinesub 100% 5 / 5 Podpod 100% 3 / 3 totaltotal 79.8% 99 / 124 CC 18 SCAR 20.3
CC
18
Cov
84%
_reformat_stacktrace
9.8
new
8.5
pretty_format
3.0
CRAP 7.6
« Bio/Tools/Phylo/Phylip/ProtDist.pm ↑ Summary Bio/Annotation/StructuredValue.pm »
1 package Bio::Root::Exception;
2 583 $Bio::Root::Exception::VERSION = '1.7.8';
3 583 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 =head1 NAME
6  
7 Bio::Root::Exception - BioPerl exceptions
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  
75 These are generic exceptions for typical problem situations that could arise
76 in 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  
88 Using defined exception classes like these is a good idea because it
89 indicates the basic nature of what went wrong in a convenient,
90 computable way.
91  
92 If there is a type of exception that you want to throw
93 that is not covered by the classes listed above, it is easy to define
94 a new one that fits your needs. Just write a line like the following
95 in your module or script where you want to use it (or put it somewhere
96 that is accessible to your code):
97  
98 @NoCanDoException::ISA = qw( Bio::Root::Exception );
99  
100 All of the exceptions defined in this module inherit from a common
101 base class exception, Bio::Root::Exception. This allows a user to
102 write 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  
115 So if you do create your own exceptions, just be sure they inherit
116 from Bio::Root::Exception directly, or indirectly by inheriting from a
117 Bio::Root::Exception subclass.
118  
119 The exceptions in Bio::Root::Exception are extensions of Graham Barr's
120 L<Error> module available from CPAN. Despite this dependency, the
121 L<Bio::Root::Exception> module does not explicitly C<require Error>.
122 This permits Bio::Root::Exception to be loaded even when
123 Error.pm is not available.
124  
125 =head2 Throwing exceptions within Bioperl modules
126  
127 Error.pm is not part of the Bioperl distribution, and may not be
128 present within any given perl installation. So, when you want to
129 throw an exception in a Bioperl module, the safe way to throw it
130 is to use L<Bio::Root::Root/throw> which can use Error.pm
131 when it's available. See documentation in Bio::Root::Root for details.
132  
133 =head1 SEE ALSO
134  
135 See the C<examples/exceptions> directory of the Bioperl distribution for
136 working demo code.
137  
138 L<Bio::Root::Root/throw> for information about throwing
139 L<Bio::Root::Exception>-based exceptions.
140  
141 L<Error> (available from CPAN, author: GBARR)
142  
143 Error.pm is helping to guide the design of exception handling in Perl 6.
144 See 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 =head1 AUTHOR Steve Chervitz
153  
154 =cut
155  
156 583 my $debug = $Error::Debug; # Prevents the "used only once" warning.
157 583 my $DEFAULT_VALUE = "__DUMMY__"; # Permits eval{} based handlers to work
158  
159 =head2 L<Bio::Root::Exception>
160  
161 Purpose : A generic base class for all BioPerl exceptions.
162 By including a "catch Bio::Root::Exception" block, you
163 should be able to trap all BioPerl exceptions.
164 Example : throw Bio::Root::Exception("A generic exception", $!);
165  
166 =cut
167  
168 #---------------------------------------------------------
169 583 @Bio::Root::Exception::ISA = qw( Error );
170 #---------------------------------------------------------
171  
172 =head1 Methods defined by Bio::Root::Exception
173  
174 =head2 new
175  
176 Purpose : Guarantees that -value is set properly before
177 calling Error::new().
178  
179 Arguments: key-value style arguments same as for Error::new()
180  
181 You can also specify plain arguments as ($message, $value)
182 where $value is optional.
183  
184 -value, if defined, must be non-zero and not an empty string
185 in order for eval{}-based exception handlers to work.
186 These require that if($@) evaluates to true, which will not
187 be the case if the Error has no value (Error overloads
188 numeric operations to the Error::value() method).
189  
190 It is OK to create Bio::Root::Exception objects without
191 specifying -value. In this case, an invisible dummy value is used.
192  
193 If you happen to specify a -value of zero (0), it will
194 be replaced by the string "The number zero (0)".
195  
196 If you happen to specify a -value of empty string (""), it will
197 be replaced by the string "An empty string ("")".
198  
199 =cut
200  
201 33 ▶sub new {
Subroutine new: called CC=8 SCAR=21.4
Pod documented
202 33 my ($class, @args) = @_;
203 33 my ($value, %params);
204 33 ▶ if( @args % 2 == 0 && $args[0] =~ /^-/) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args % 2 == 0 and $args[0] =~ /^-/) { } 1 32 33
Condition100%3/3
@args % 2 == 0 and $args[0] =~ /^-/
!ll&&!rl&&r
3111
MC/DC100%2/2
@args % 2 == 0 and $args[0] =~ /^-/
@args % 2 == 0 $args[0] =~ /^-/
Truth table100%3/3
A and B
A= @args % 2 == 0B= $args[0] =~ /^-/
ABresult
0X0
100
111
205 1 %params = @args;
206 1 $value = $params{'-value'};
207 }
208 else {
209 32 $params{-text} = $args[0];
210 32 $value = $args[1];
211 }
212  
213 33 ▶ if( defined $value ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) { } 1 32 33
214 1 ▶ $value = "The number zero (0)" if $value =~ /^\d+$/ && $value == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^\d+$/ and $value == 0 0 1 1
Condition33%1/3
$value =~ /^\d+$/ and $value == 0
!ll&&!rl&&r
010
MC/DC0%0/2
$value =~ /^\d+$/ and $value == 0
$value =~ /^\d+$/ $value == 0
Truth table33%1/3
A and B
A= $value =~ /^\d+$/B= $value == 0
ABresult
0X0
100
111
215 1 ▶ $value = "An empty string (\"\")" if $value eq "";
Branch: 1 branch
BranchTrueFalseTotal
if $value eq "" 0 1 1
216 }
217 else {
218 32 ▶ $value ||= $DEFAULT_VALUE;
Condition33%1/3
$value ||= $DEFAULT_VALUE
l!l&&r!l&&!r
0320
MC/DC0%0/2
$value ||= $DEFAULT_VALUE
$value $DEFAULT_VALUE
Truth table33%1/3
A ||= B
A= $valueB= $DEFAULT_VALUE
ABresult
1X1
011
000
219 }
220 33 $params{-value} = $value;
221  
222 33 my $self = $class->SUPER::new( %params );
223 33 return $self;
224 }
225  
226 =head2 pretty_format()
227  
228 Purpose : Get a nicely formatted string containing information about the
229 exception. Format is similar to that produced by
230 Bio::Root::Root::throw(), with the addition of the name of
231 the exception class in the EXCEPTION line and some other
232 data available via the Error object.
233 Example : print $error->pretty_format;
234  
235 =cut
236  
237 23 ▶sub pretty_format {
Subroutine pretty_format: called CC=3 SCAR=11.1
Pod documented
238 23 my $self = shift;
239 23 my $msg = $self->text;
240 23 my $stack = '';
241 23 ▶ if( $Error::Debug ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Error::Debug) 23 0 23
242 23 $stack = $self->_reformat_stacktrace();
243 }
244 23 ▶ my $value_string = $self->value ne $DEFAULT_VALUE ? "VALUE: ".$self->value."\n" : "";
Branch: 1 branch
BranchTrueFalseTotal
$self->value ne $DEFAULT_VALUE ? : 0 23 23
245 23 my $class = ref($self);
246  
247 23 my $title = "------------- EXCEPTION: $class -------------";
248 23 my $footer = "\n" . '-' x CORE::length($title);
249 23 my $out = "\n$title\n"
250 . "MSG: $msg\n". $value_string. $stack. $footer . "\n";
251 23 return $out;
252 }
253  
254  
255 =head2 _reformat_stacktrace
256  
257 Reformatting of the stack performed by _reformat_stacktrace:
258 for :list
259 1. Shift the file:line data in line i to line i+1.
260 2. change xxx::__ANON__() to "try{} block"
261 3. skip the "require" and "Error::subs::try" stack entries (boring)
262  
263 This means that the first line in the stack won't have any file:line data
264 But this isn't a big issue since it's for a Bio::Root::-based method
265 that doesn't vary from exception to exception.
266  
267 =cut
268  
269 23 ▶sub _reformat_stacktrace {
Subroutine _reformat_stacktrace: called CC=9 SCAR=22.8
270 23 my $self = shift;
271 23 my $msg = $self->text;
272 23 my $stack = $self->stacktrace();
273 23 $stack =~ s/\Q$msg//;
274 23 my @stack = split( /\n/, $stack);
275 23 my @new_stack = ();
276 23 my ($method, $file, $linenum, $prev_file, $prev_linenum);
277 23 my $stack_count = 0;
278 23 foreach my $i( 0..$#stack ) {
279 # print "STACK-ORIG: $stack[$i]\n";
280 119 ▶ if( ($stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/) ||
Branch: 1 branch
BranchTrueFalseTotal
if ($stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/ or $stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/) { } 85 34 119
Condition66%2/3
$stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/ or $stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/
l!l&&r!l&&!r
85034
MC/DC50%1/2
$stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/ or $stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/
$stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/ $stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/
Truth table66%2/3
A or B
A= $stack[$i] =~ /^\s*([^(]+)\s*\(.*\) called at (\S+) line (\d+)/B= $stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/
ABresult
1X1
011
000
281 ($stack[$i] =~ /^\s*(require 0) called at (\S+) line (\d+)/)) {
282 85 ($method, $file, $linenum) = ($1, $2, $3);
283 85 $stack_count++;
284 }
285 else{
286 34 next;
287 }
288 85 ▶ if( $stack_count == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stack_count == 1) 23 62 85
289 23 push @new_stack, "STACK: $method";
290 23 ($prev_file, $prev_linenum) = ($file, $linenum);
291 23 next;
292 }
293  
294 62 ▶ if( $method =~ /__ANON__/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($method =~ /__ANON__/) 0 62 62
295 0 $method = "try{} block";
296 }
297 62 ▶ if( ($method =~ /^require/ and $file =~ /Error\.pm/ ) ||
Branch: 1 branch
BranchTrueFalseTotal
if ($method =~ /^require/ and $file =~ /Error\.pm/ or $method =~ /^Error::subs::try/) 0 62 62
Condition33%2/6
$method =~ /^require/ and $file =~ /Error\.pm/ or $method =~ /^Error::subs::try/
l!l&&r!l&&!r
0062
$method =~ /^require/ and $file =~ /Error\.pm/
!ll&&!rl&&r
6200
MC/DC0%0/3
$method =~ /^require/ and $file =~ /Error\.pm/ or $method =~ /^Error::subs::try/
$method =~ /^require/ $file =~ /Error\.pm/ $method =~ /^Error::subs::try/
Truth table20%1/5
A and B or C
A= $method =~ /^require/B= $file =~ /Error\.pm/C= $method =~ /^Error::subs::try/
ABCresult
11X1
0X11
1011
0X00
1000
298 ($method =~ /^Error::subs::try/ ) ) {
299 0 last;
300 }
301 62 push @new_stack, "STACK: $method $prev_file:$prev_linenum";
302 62 ($prev_file, $prev_linenum) = ($file, $linenum);
303 }
304 23 push @new_stack, "STACK: $prev_file:$prev_linenum";
305  
306 23 return join "\n", @new_stack;
307 }
308  
309 =head2 stringify()
310  
311 Purpose : Overrides Error::stringify() to call pretty_format().
312 This is called automatically when an exception object
313 is placed between double quotes.
314 Example : catch Bio::Root::Exception with {
315 my $error = shift;
316 print "$error";
317 }
318  
319 See Also: L<pretty_format()|pretty_format>
320  
321 =cut
322  
323 23 ▶sub stringify {
Subroutine stringify: called CC=1 SCAR=0.0
Pod documented
324 23 my ($self, @args) = @_;
325 23 return $self->pretty_format( @args );
326 }
327  
328 =head1 Subclasses of Bio::Root::Exception
329  
330 =head2 L<Bio::Root::NotImplemented>
331  
332 Purpose : Indicates that a method has not been implemented.
333 Example : throw Bio::Root::NotImplemented(
334 -text => "Method \"foo\" not implemented in module FooBar.",
335 -value => "foo" );
336  
337 =cut
338  
339 #---------------------------------------------------------
340 583 @Bio::Root::NotImplemented::ISA = qw( Bio::Root::Exception );
341 #---------------------------------------------------------
342  
343 =head2 L<Bio::Root::IOException>
344  
345 Purpose : Indicates that some input/output-related trouble has occurred.
346 Example : throw Bio::Root::IOException(
347 -text => "Can't save data to file $file.",
348 -value => $! );
349  
350 =cut
351  
352 #---------------------------------------------------------
353 583 @Bio::Root::IOException::ISA = qw( Bio::Root::Exception );
354 #---------------------------------------------------------
355  
356  
357 =head2 L<Bio::Root::FileOpenException>
358  
359 Purpose : Indicates that a file could not be opened.
360 Example : throw Bio::Root::FileOpenException(
361 -text => "Can't open file $file for reading.",
362 -value => $! );
363  
364 =cut
365  
366 #---------------------------------------------------------
367 583 @Bio::Root::FileOpenException::ISA = qw( Bio::Root::IOException );
368 #---------------------------------------------------------
369  
370  
371 =head2 L<Bio::Root::SystemException>
372  
373 Purpose : Indicates that a system call failed.
374 Example : unlink($file) or throw Bio::Root::SystemException(
375 -text => "Can't unlink file $file.",
376 -value => $! );
377  
378 =cut
379  
380 #---------------------------------------------------------
381 583 @Bio::Root::SystemException::ISA = qw( Bio::Root::Exception );
382 #---------------------------------------------------------
383  
384  
385 =head2 L<Bio::Root::BadParameter>
386  
387 Purpose : Indicates that one or more parameters supplied to a method
388 are invalid, unspecified, or conflicting.
389 Example : throw Bio::Root::BadParameter(
390 -text => "Required parameter \"-foo\" was not specified",
391 -value => "-foo" );
392  
393 =cut
394  
395 #---------------------------------------------------------
396 583 @Bio::Root::BadParameter::ISA = qw( Bio::Root::Exception );
397 #---------------------------------------------------------
398  
399  
400 =head2 L<Bio::Root::OutOfRange>
401  
402 Purpose : Indicates that a specified (start,end) range or
403 an index to an array is outside the permitted range.
404 Example : throw Bio::Root::OutOfRange(
405 -text => "Start coordinate ($start) cannot be less than zero.",
406 -value => $start );
407  
408 =cut
409  
410 #---------------------------------------------------------
411 583 @Bio::Root::OutOfRange::ISA = qw( Bio::Root::Exception );
412 #---------------------------------------------------------
413  
414  
415 =head2 L<Bio::Root::NoSuchThing>
416  
417 Purpose : Indicates that a requested thing cannot be located
418 and therefore could possibly be bogus.
419 Example : throw Bio::Root::NoSuchThing(
420 -text => "Accession M000001 could not be found.",
421 -value => "M000001" );
422  
423 =cut
424  
425 #---------------------------------------------------------
426 583 @Bio::Root::NoSuchThing::ISA = qw( Bio::Root::Exception );
427 #---------------------------------------------------------
428  
429 583 1;
« Bio/Tools/Phylo/Phylip/ProtDist.pm ↑ Summary Bio/Annotation/StructuredValue.pm »