File Coverage

blib/lib/Bio/Phylo/Util/StackTrace.pm
Criterion Covered Total %
statement 21 36 58.3
branch 5 6 83.3
condition n/a
subroutine 3 4 75.0
pod 2 2 100.0
total 31 48 64.5


line stmt bran cond sub pod time code
1             package Bio::Phylo::Util::StackTrace;
2 57     57   319 use strict;
  57         111  
  57         18443  
3              
4             =head1 NAME
5              
6             Bio::Phylo::Util::StackTrace - Stack traces for exceptions
7              
8             =head1 SYNOPSIS
9              
10             use Bio::Phylo::Util::StackTrace;
11             my $trace = Bio::Phylo::Util::StackTrace->new;
12             print $trace->as_string;
13              
14             =head1 DESCRIPTION
15              
16             This is a simple stack trace object that is used by
17             L<Bio::Phylo::Util::Exceptions>. At the moment of its instantiation,
18             it creates a full list of all frames in the call stack (except those
19             originating from with the exceptions class). These can subsequently
20             be stringified by calling as_string().
21              
22             (If you have no idea what any of this means, don't worry: this class
23             is mostly for internal usage. You can probably ignore this safely.)
24              
25             =head1 METHODS
26              
27             =head2 CONSTRUCTOR
28              
29             =over
30              
31             =item new()
32              
33             Stack trace object constructor.
34              
35             Type : Constructor
36             Title : new
37             Usage : my $trace = Bio::Phylo::Util::StackTrace->new
38             Function: Instantiates a Bio::Phylo::Util::StackTrace
39             object.
40             Returns : A Bio::Phylo::Util::StackTrace.
41             Args : None
42              
43             =cut
44              
45             sub new {
46 176     176 1 297 my $class = shift;
47 176         320 my $self = [];
48 176         281 my $i = 0;
49 176         266 my $j = 0;
50              
51             package DB; # to get @_ stack from previous frames, see perldoc -f caller
52 176         1493 while ( my @frame = caller($i) ) {
53 2566         3619 my $package = $frame[0];
54 2566 100       3588 if ( not Bio::Phylo::Util::StackTrace::_skip_me($package) ) {
55 2214         3379 my @args = @DB::args;
56 2214         6623 $self->[ $j++ ] = [ @frame, @args ];
57             }
58 2566         11952 $i++;
59             }
60              
61             package Bio::Phylo::Util::StackTrace;
62 176         305 shift @$self; # to remove "throw" frame
63 176         3058 return bless $self, $class;
64             }
65              
66             sub _skip_me {
67 2566     2566   3087 my $class = shift;
68 2566         2919 my $skip = 0;
69 2566 100       9423 if ( $class->isa('Bio::Phylo::Util::Exceptions') ) {
70 352         500 $skip++;
71             }
72 2566 50       7756 if ( $class->isa('Bio::Phylo::Util::ExceptionFactory') ) {
73 0         0 $skip++;
74             }
75 2566         4554 return $skip;
76             }
77              
78             =back
79              
80             =head2 SERIALIZERS
81              
82             =over
83              
84             =item as_string()
85              
86             Creates a string representation of the stack trace
87              
88             Type : Serializer
89             Title : as_string
90             Usage : print $trace->as_string
91             Function: Creates a string representation of the stack trace
92             Returns : String
93             Args : None
94              
95             =cut
96              
97             =begin comment
98              
99             fields in frame:
100             [
101             0 'main',
102             +1 '/Users/rvosa/Desktop/exceptions.pl',
103             +2 102,
104             +3 'Object::this_dies',
105             4 1,
106             5 undef,
107             6 undef,
108             7 undef,
109             8 2,
110             9 'UUUUUUUUUUUU',
111             +10 bless( {}, 'Object' ),
112             +11 'very',
113             +12 'violently'
114             ],
115              
116             =end comment
117              
118             =cut
119              
120             sub as_string {
121 0     0 1   my $self = shift;
122 0           my $string = "";
123 0           for my $frame (@$self) {
124 0           my $method = $frame->[3];
125 0           my @args;
126 0           for my $i ( 10 .. $#{$frame} ) {
  0            
127 0           push @args, $frame->[$i];
128             }
129 0           my $file = $frame->[1];
130 0           my $line = $frame->[2];
131             $string .=
132             $method . "("
133 0           . join( ', ', map { "'$_'" } grep { $_ } @args )
  0            
  0            
134             . ") called at $file line $line\n";
135             }
136 0           return $string;
137             }
138              
139             =back
140              
141             =cut
142              
143             =head1 SEE ALSO
144              
145             There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo>
146             for any user or developer questions and discussions.
147              
148             =over
149              
150             =item L<Bio::Phylo::Util::Exceptions>
151              
152             The stack trace object is used internally by the exception classes.
153              
154             =item L<Bio::Phylo::Manual>
155              
156             Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com>.
157              
158             =back
159              
160             =head1 CITATION
161              
162             If you use Bio::Phylo in published research, please cite it:
163              
164             B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
165             and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
166             I<BMC Bioinformatics> B<12>:63.
167             L<http://dx.doi.org/10.1186/1471-2105-12-63>
168              
169             =cut
170              
171             1;