Phylo/Util/Logger.pm

filter: Statementstmt 59.2% 90 / 152 Branchbran 34.8% 23 / 66 Conditioncond 23.8% 5 / 21 MC/DCmcdc 7.6% 1 / 13 Subroutinesub 62.0% 18 / 29 Podpod 94.1% 16 / 17 totaltotal 51.3% 153 / 298 CC 45 SCAR 36.8
CC
45
Cov
49%
VERBOSE
121.0
start_color
20.0
stop_color
20.0
CRAP 39.8
« Phylo/Matrices/Datatype.pm ↑ Summary Phylo/NeXML/DOM/Element/Twig.pm »
1 package Bio::Phylo::Util::Logger;
2 57 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 57 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 57 ▶use base 'Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
5 57 ▶use Term::ANSIColor;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 57 ▶use Bio::Phylo::Util::Exceptions 'throw';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 57 ▶use Bio::Phylo::Util::CONSTANT qw'/looks_like/';
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 57 our ( %VERBOSITY, $PREFIX, %STYLE );
10 57 our $STYLE = 'detailed';
11 57 our $COLORED = 1; # new default: we use colors
12 57 our $TRACEBACK = 0;
13 57 our @EXPORT_OK = qw(DEBUG INFO WARN ERROR FATAL VERBOSE);
14 57 our %EXPORT_TAGS = ( 'simple' => [@EXPORT_OK], 'levels' => [@EXPORT_OK] );
15 57 our %COLORS = (
16 'DEBUG' => 'blue',
17 'INFO' => 'green',
18 'WARN' => 'yellow',
19 'ERROR' => 'bold red',
20 'FATAL' => 'red',
21 );
22  
23 57 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=7.0
24
25 # compute the path to the root of Bio::Phylo,
26 # use that as the default prefix
27 57 my $package = __PACKAGE__;
28 57 my $file = __FILE__;
29 57 $package =~ s/::/\//g;
30 57 $package .= '.pm';
31 57 $file =~ s/\Q$package\E$//;
32 57 $PREFIX = $file;
33
34 # set verbosity to 2, i.e. warn
35 57 ▶ $VERBOSITY{'*'} = $ENV{'BIO_PHYLO_VERBOSITY'} || 2;
Condition50%1/2
$ENV{'BIO_PHYLO_VERBOSITY'} || 2
l!l
057
MC/DC0%0/1
$ENV{'BIO_PHYLO_VERBOSITY'} || 2
$ENV{'BIO_PHYLO_VERBOSITY'}
Truth table50%1/2
A
A= $ENV{'BIO_PHYLO_VERBOSITY'}
Aresult
11
00
36
37 # define verbosity styles
38 57 %STYLE = (
39 'simple' => '${level}: $message',
40 'detailed' => '$level $sub [$file $line] - $message',
41 );
42 }
43  
44 {
45 57 my %levels = ( FATAL => 0, ERROR => 1, WARN => 2, INFO => 3, DEBUG => 4 );
46 0 ▶ my @listeners = ( sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
47 0 my ( $string, $level ) = @_;
48 0 ▶ if ( $COLORED and -t STDERR ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Bio::Phylo::Util::Logger::COLORED and -t STDERR) { } 0 0 0
Condition0%0/3
$Bio::Phylo::Util::Logger::COLORED and -t STDERR
!ll&&!rl&&r
000
MC/DC0%0/2
$Bio::Phylo::Util::Logger::COLORED and -t STDERR
$Bio::Phylo::Util::Logger::COLORED -t STDERR
Truth table0%0/3
A and B
A= $Bio::Phylo::Util::Logger::COLOREDB= -t STDERR
ABresult
0X0
100
111
49 0 print STDERR colored( $string, $COLORS{$level} );
50 }
51 else {
52 0 print STDERR $string;
53 }
54 57 } ); # default
55  
56 # dummy constructor that dispatches to VERBOSE(),
57 # then returns the package name
58 200 ▶ sub new {
Subroutine new: called CC=2 SCAR=7.1
Pod documented
59 200 my $class = shift;
60 200 ▶ $class->VERBOSE(@_) if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 200 200
61 200 return $class;
62 }
63  
64 # set additional listeners
65 2 ▶ sub set_listeners {
Subroutine set_listeners: called CC=3 SCAR=11.0
Pod documented
66 2 my ( $class, @args ) = @_;
67 2 for my $arg (@args) {
68 2 ▶ if ( looks_like_instance $arg, 'CODE' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (&looks_like_instance($arg, 'CODE')) { } 1 1 2
69 1 push @listeners, $arg;
70 }
71 else {
72 1 throw 'BadArgs' => "$arg not a CODE reference";
73 }
74 }
75 1 return $class;
76 }
77
78 # this is never called directly. rather, messages are dispatched here
79 # by the DEBUG() ... FATAL() subs below
80 246997 ▶ sub LOG ($$) {
Subroutine LOG: called CC=7 SCAR=25.2
Pod undocumented
81 246997 my ( $message, $level ) = @_;
82 57 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
83
84 # probe the call stack
85 246997 my ( $pack2, $file2, $line2, $sub ) = caller( $TRACEBACK + 2 );
86 246997 my ( $pack1, $file, $line, $sub1 ) = caller( $TRACEBACK + 1 );
87
88 # cascade verbosity from global to local
89 246997 my $verbosity = $VERBOSITY{'*'}; # global
90 246997 ▶ $verbosity = $VERBOSITY{$pack1} if exists $VERBOSITY{$pack1}; # package
Branch: 1 branch
BranchTrueFalseTotal
if exists $Bio::Phylo::Util::Logger::VERBOSITY{$pack1} 0 246997 246997
91 246997 ▶ $verbosity = $VERBOSITY{$sub} if $sub and exists $VERBOSITY{$sub}; # sub
Branch: 1 branch
BranchTrueFalseTotal
if $sub and exists $Bio::Phylo::Util::Logger::VERBOSITY{$sub} 0 246997 246997
Condition33%1/3
$sub and exists $Bio::Phylo::Util::Logger::VERBOSITY{$sub}
!ll&&!rl&&r
02469970
MC/DC0%0/2
$sub and exists $Bio::Phylo::Util::Logger::VERBOSITY{$sub}
$sub exists $Bio::Phylo::Util::Logger::VERBOSITY{$sub}
Truth table33%1/3
A and B
A= $subB= exists $Bio::Phylo::Util::Logger::VERBOSITY{$sub}
ABresult
0X0
100
111
92
93 # verbosity is higher than the current caller, proceed
94 246997 ▶ if ( $verbosity >= $levels{$level} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($verbosity >= $levels{$level}) 0 246997 246997
95  
96 # strip the prefix from the calling file's path
97 0 ▶ if ( index($file, $PREFIX) == 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (index($file, $Bio::Phylo::Util::Logger::PREFIX) == 0) 0 0 0
98 0 $file =~ s/^\Q$PREFIX\E//;
99 }
100
101 # select one of the templates
102 0 my $string;
103 0 my $s = $STYLE{$STYLE};
104 0 $string = eval "qq[$s\n]";
105
106 # dispatch to the listeners
107 0 $_->( $string, $level, $sub, $file, $line, $message ) for @listeners;
108 }
109 }
110
111 # these subs both return their verbosity constants and, if
112 # provided with a message, dispatch the message to LOG()
113 0 ▶ sub FATAL (;$) { LOG $_[0], 'FATAL' if $_[0]; $levels{'FATAL'} }
Subroutine FATAL: not called CC=2 SCAR=17.9
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] 0 0 0
114 0 ▶ sub ERROR (;$) { LOG $_[0], 'ERROR' if $_[0]; $levels{'ERROR'} }
Subroutine ERROR: not called CC=2 SCAR=17.9
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] 0 0 0
115 4 ▶ sub WARN (;$) { LOG $_[0], 'WARN' if $_[0]; $levels{'WARN'} }
Subroutine WARN: called CC=2 SCAR=7.2
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] 4 0 4
116 64218 ▶ sub INFO (;$) { LOG $_[0], 'INFO' if $_[0]; $levels{'INFO'} }
Subroutine INFO: called CC=2 SCAR=7.2
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] 64218 0 64218
117 182785 ▶ sub DEBUG (;$) { LOG $_[0], 'DEBUG' if $_[0]; $levels{'DEBUG'} }
Subroutine DEBUG: called CC=2 SCAR=6.9
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] 182775 10 182785
118  
119 0 ▶ sub PREFIX {
Subroutine PREFIX: not called CC=2 SCAR=17.9
Pod documented
120 0 my ( $class, $prefix ) = @_;
121 0 ▶ $PREFIX = $prefix if $prefix;
Branch: 1 branch
BranchTrueFalseTotal
if $prefix 0 0 0
122 0 return $PREFIX;
123 }
124  
125 14 ▶ sub VERBOSE {
Subroutine VERBOSE: called CC=21 SCAR=48.0
Pod documented
126 14 ▶ shift if ref $_[0] or $_[0] eq __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
if ref $_[0] or $_[0] eq __PACKAGE__ 2 12 14
Condition66%2/3
ref $_[0] or $_[0] eq __PACKAGE__
l!l&&r!l&&!r
0212
MC/DC50%1/2
ref $_[0] or $_[0] eq __PACKAGE__
ref $_[0] $_[0] eq __PACKAGE__
Truth table66%2/3
A or B
A= ref $_[0]B= $_[0] eq __PACKAGE__
ABresult
1X1
011
000
127 14 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 14 0 14
128 14 my %opt = looks_like_hash @_;
129 14 my $level = $opt{'-level'};
130
131 # verbosity is specified
132 14 ▶ if ( defined $level ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $level) 14 0 14
133  
134 # check validity
135 14 ▶ if ( $level > 4 xor $level < 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($level > 4 xor $level < 0) 0 14 14
Condition25%1/4
$level > 4 xor $level < 0
l&&rl&&!r!l&&r!l&&!r
00014
MC/DC0%0/2
$level > 4 xor $level < 0
$level > 4 $level < 0
Truth table25%1/4
A xor B
A= $level > 4B= $level < 0
ABresult
110
101
011
000
136 0 throw 'OutOfBounds' => "'-level' can be between 0 and 4, not $level";
137 }
138
139 # verbosity is specified for one or more packages
140 14 ▶ if ( my $class = $opt{'-class'} ) {
Branch: 2 branches
BranchTrueFalseTotal
if (my $class = $opt{'-class'}) { } 0 14 14
elsif (my $method = $opt{'-method'}) { } 0 14 14
141 0 ▶ if ( ref $class eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $class eq 'ARRAY') { } 0 0 0
142 0 for my $c ( @{ $class } ) {
143 0 $VERBOSITY{$c} = $level;
144 0 INFO "Changed verbosity for class $c to $level";
145 }
146 }
147 else {
148 0 $VERBOSITY{$class} = $level;
149 0 INFO "Changed verbosity for class $class to $level";
150 }
151 }
152
153 # verbosity is specified for one or more methods
154 elsif ( my $method = $opt{'-method'} ) {
155 0 ▶ if ( ref $method eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $method eq 'ARRAY') { } 0 0 0
156 0 for my $m ( @{ $method } ) {
157 0 $VERBOSITY{$m} = $level;
158 0 INFO "Changed verbosity for method $m to $level";
159 }
160 }
161 else {
162 0 $VERBOSITY{$method} = $level;
163 0 INFO "Changed verbosity for method $method to $level";
164 }
165 }
166
167 # verbosity is set globally
168 else {
169 14 $VERBOSITY{'*'} = $level;
170 14 INFO "Changed global verbosity to $VERBOSITY{'*'}";
171 }
172 }
173
174 # log to a file
175 14 ▶ if ( $opt{'-file'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt{"-file"}) 0 14 14
176 0 ▶ open my $fh, '>>', $opt{'-file'} or throw 'FileError' => $!;
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">>", $opt{"-file"} or &throw("FileError", $!) 0 0 0
177 0 ▶ __PACKAGE__->set_listeners(sub { print $fh shift });
Subroutine __ANON__: not called CC=1 SCAR=6.9
178 }
179
180 # log to a handle
181 14 ▶ if ( $opt{'-handle'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt{"-handle"}) 0 14 14
182 0 my $fh = $opt{'-handle'};
183 0 ▶ __PACKAGE__->set_listeners(sub { print $fh shift });
Subroutine __ANON__: not called CC=1 SCAR=6.9
184 }
185
186 # log to listeners
187 14 ▶ if ( $opt{'-listeners'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt{"-listeners"}) 0 14 14
188 0 __PACKAGE__->set_listeners(@{$opt{'-listeners'}});
189 }
190
191 # update the prefix
192 14 ▶ if ( $opt{'-prefix'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt{"-prefix"}) 0 14 14
193 0 __PACKAGE__->PREFIX($opt{'-prefix'});
194 }
195
196 # set logstyle
197 14 ▶ if ( $opt{'-style'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt{"-style"}) 0 14 14
198 0 my $s = lc $opt{'-style'};
199 0 ▶ if ( exists $STYLE{$s} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $Bio::Phylo::Util::Logger::STYLE{$s}) 0 0 0
200 0 $STYLE = $s;
201 }
202 }
203
204 # turn colors on/off. default is on.
205 14 ▶ $COLORED = !!$opt{'-colors'} if defined $opt{'-colors'};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opt{"-colors"} 0 14 14
206 }
207 14 return $VERBOSITY{'*'};
208 }
209
210 # Change the terminal to a predefined color. For example to make sure that
211 # an entire exception (or part of it) is marked up as FATAL, or so that the
212 # output from an external command is marked up as DEBUG.
213 0 ▶ sub start_color {
Subroutine start_color: not called CC=4 SCAR=30.0
Pod documented
214 0 my ( $self, $level, $handle ) = @_;
215 0 ▶ $handle = \*STDERR if not $handle;
Branch: 1 branch
BranchTrueFalseTotal
unless $handle 0 0 0
216 0 ▶ if ( $COLORED and -t $handle ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Bio::Phylo::Util::Logger::COLORED and -t $handle) 0 0 0
Condition0%0/3
$Bio::Phylo::Util::Logger::COLORED and -t $handle
!ll&&!rl&&r
000
MC/DC0%0/2
$Bio::Phylo::Util::Logger::COLORED and -t $handle
$Bio::Phylo::Util::Logger::COLORED -t $handle
Truth table0%0/3
A and B
A= $Bio::Phylo::Util::Logger::COLOREDB= -t $handle
ABresult
0X0
100
111
217 0 print $handle color $COLORS{$level};
218 }
219 0 return $COLORS{$level};
220 }
221
222 0 ▶ sub stop_color {
Subroutine stop_color: not called CC=4 SCAR=30.0
Pod documented
223 0 my ( $self, $handle ) = @_;
224 0 ▶ $handle = \*STDERR if not $handle;
Branch: 1 branch
BranchTrueFalseTotal
unless $handle 0 0 0
225 0 ▶ if ( $COLORED and -t $handle ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Bio::Phylo::Util::Logger::COLORED and -t $handle) 0 0 0
Condition0%0/3
$Bio::Phylo::Util::Logger::COLORED and -t $handle
!ll&&!rl&&r
000
MC/DC0%0/2
$Bio::Phylo::Util::Logger::COLORED and -t $handle
$Bio::Phylo::Util::Logger::COLORED -t $handle
Truth table0%0/3
A and B
A= $Bio::Phylo::Util::Logger::COLOREDB= -t $handle
ABresult
0X0
100
111
226 0 print $handle color 'reset';
227 }
228 0 return $self;
229 }
230
231 # aliases for singleton methods
232 0 ▶ sub fatal {
Subroutine fatal: not called CC=1 SCAR=6.9
Pod documented
233 0 my $self = shift;
234 0 $TRACEBACK++;
235 0 FATAL shift;
236 0 $TRACEBACK--;
237 }
238 0 ▶ sub error {
Subroutine error: not called CC=1 SCAR=6.9
Pod documented
239 0 my $self = shift;
240 0 $TRACEBACK++;
241 0 ERROR shift;
242 0 $TRACEBACK--;
243 }
244 4 ▶ sub warn {
Subroutine warn: called CC=1 SCAR=0.0
Pod documented
245 4 my $self = shift;
246 4 $TRACEBACK++;
247 4 WARN shift;
248 4 $TRACEBACK--;
249 }
250 62206 ▶ sub info {
Subroutine info: called CC=1 SCAR=0.0
Pod documented
251 62206 my $self = shift;
252 62206 $TRACEBACK++;
253 62206 INFO shift;
254 62206 $TRACEBACK--;
255 }
256 182785 ▶ sub debug {
Subroutine debug: called CC=1 SCAR=0.0
Pod documented
257 182785 my $self = shift;
258 182785 $TRACEBACK++;
259 182785 DEBUG shift;
260 182785 $TRACEBACK--;
261 }
262
263 # empty destructor so we don't go up inheritance tree at the end
264 0 ▶ sub DESTROY {}
Subroutine DESTROY: not called CC=1 SCAR=0.0
265 }
266 57 1;
267  
268 =head1 NAME
269  
270 Bio::Phylo::Util::Logger - Logger of internal messages of several severity
271 levels
272  
273 =head1 SYNOPSIS
274  
275 use strict;
276 use Bio::Phylo::Util::Logger ':levels'; # import level constants
277 use Bio::Phylo::IO 'parse';
278 use Bio::Phylo::Factory;
279
280 # Set the verbosity level of the tree class.
281 # "DEBUG" is the most verbose level. All log messages
282 # emanating from the tree class will be
283 # transmitted. For this to work the level constants
284 # have to have been imported!
285 use Bio::Phylo::Forest::Tree 'verbose' => DEBUG; # note: DEBUG is not quoted!
286
287 # Create a file handle for logger to write to.
288 # This is not necessary, by default the logger
289 # writes to STDERR, but sometimes you will want
290 # to write to a file, as per this example.
291 open my $fh, '>', 'parsing.log' or die $!;
292
293 # Create a logger object.
294 my $fac = Bio::Phylo::Factory->new;
295 my $logger = $fac->create_logger;
296
297 # Set the verbosity level of the set_name
298 # method in the base class. Messages coming
299 # from this method will be transmitted.
300 $logger->VERBOSE(
301 '-level' => DEBUG, # note, not quoted, this is a constant!
302 '-method' => 'Bio::Phylo::set_name', # quoted, otherwise bareword error!
303 );
304
305 # 'Listeners' are subroutine references that
306 # are executed when a message is transmitted.
307 # The first argument passed to these subroutines
308 # is the log message. This particular listener
309 # will write the message to the 'parsing.log'
310 # file, if the $fh file handle is still open.
311 $logger->set_listeners(
312 sub {
313 my ($msg) = @_;
314 if ( $fh->opened ) {
315 print $fh $msg;
316 }
317 }
318 );
319  
320 # Now parse a tree, and see what is logged.
321 my $tree = parse(
322 '-format' => 'newick',
323 '-string' => do { local $/; <DATA> },
324 )->first;
325  
326 # Cleanly close the log handle.
327 close $fh;
328
329 __DATA__
330 ((((A,B),C),D),E);
331  
332 The example above will write something like the following to the log file:
333  
334 INFO Bio::Phylo::Forest::Tree::new [Bio/Phylo/Forest/Tree.pm, 99] - constructor called for 'Bio::Phylo::Forest::Tree'
335 INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] - setting name 'A'
336 INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] - setting name 'B'
337 INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] - setting name 'C'
338 INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] - setting name 'D'
339 INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] - setting name 'E'
340  
341 =head1 DESCRIPTION
342  
343 This class defines a logger, a utility object for logging messages.
344 The other objects in Bio::Phylo use this logger to give detailed feedback
345 about what they are doing at per-class, per-method, user-configurable log levels
346 (DEBUG, INFO, WARN, ERROR and FATAL). These log levels are constants that are
347 optionally exported by this class by passing the ':levels' argument to your
348 'use' statement, like so:
349  
350 use Bio::Phylo::Util::Logger ':levels';
351  
352 If for some reason you don't want this behaviour (i.e. because there is
353 something else by these same names in your namespace) you must use the fully
354 qualified names for these levels, i.e. Bio::Phylo::Util::Logger::DEBUG and
355 so on.
356  
357 The least verbose is level FATAL, in which case only 'fatal' messages are shown.
358 The most verbose level, DEBUG, shows debugging messages, including from internal
359 methods (i.e. ones that start with underscores, and special 'ALLCAPS' perl
360 methods like DESTROY or TIEARRAY). For example, to monitor what the root class
361 is doing, you would say:
362  
363 $logger->( -class => 'Bio::Phylo', -level => DEBUG )
364  
365 To define global verbosity you can omit the -class argument. To set verbosity
366 at a more granular level, you can use the -method argument, which takes a
367 fully qualified method name such as 'Bio::Phylo::set_name', such that messages
368 originating from within that method's body get a different verbosity level.
369  
370 =head1 METHODS
371  
372 =head2 CONSTRUCTOR
373  
374 =over
375  
376 =item new()
377  
378 Constructor for Logger.
379  
380 Type : Constructor
381 Title : new
382 Usage : my $logger = Bio::Phylo::Util::Logger->new;
383 Function: Instantiates a logger
384 Returns : a Bio::Phylo::Util::Logger object
385 Args : -level => Bio::Phylo::Util::Logger::INFO (DEBUG/INFO/WARN/ERROR/FATAL)
386 -class => a package (or array ref) for which to set verbosity (optional)
387 -method => a sub name (or array ref) for which to set verbosity (optional)
388 -file => a file to which to append logging messages
389 -listeners => array ref of subs that handle logging messages
390 -prefix => a path fragment to strip from the paths in logging messages
391
392  
393 =back
394  
395 =head2 VERBOSITY LEVELS
396  
397 =over
398  
399 =item FATAL
400  
401 Rarely happens, usually an exception is thrown instead.
402  
403 =item ERROR
404  
405 If this happens, something is seriously wrong that needs to be addressed.
406  
407 =item WARN
408  
409 If this happens, something is seriously wrong that needs to be addressed.
410  
411 =item INFO
412  
413 If something weird is happening, turn up verbosity to this level as it might
414 explain some of the assumptions the code is making.
415  
416 =item DEBUG
417  
418 This is very verbose, probably only useful if you write core Bio::Phylo code.
419  
420 =back
421  
422 =head2 LOGGING METHODS
423  
424 =over
425  
426 =item debug()
427  
428 Prints argument debugging message, depending on verbosity.
429  
430 Type : logging method
431 Title : debug
432 Usage : $logger->debug( "debugging message" );
433 Function: prints debugging message, depending on verbosity
434 Returns : invocant
435 Args : logging message
436  
437 =item info()
438  
439 Prints argument informational message, depending on verbosity.
440  
441 Type : logging method
442 Title : info
443 Usage : $logger->info( "info message" );
444 Function: prints info message, depending on verbosity
445 Returns : invocant
446 Args : logging message
447  
448 =item warn()
449  
450 Prints argument warning message, depending on verbosity.
451  
452 Type : logging method
453 Title : warn
454 Usage : $logger->warn( "warning message" );
455 Function: prints warning message, depending on verbosity
456 Returns : invocant
457 Args : logging message
458  
459 =item error()
460  
461 Prints argument error message, depending on verbosity.
462  
463 Type : logging method
464 Title : error
465 Usage : $logger->error( "error message" );
466 Function: prints error message, depending on verbosity
467 Returns : invocant
468 Args : logging message
469  
470 =item fatal()
471  
472 Prints argument fatal message, depending on verbosity.
473  
474 Type : logging method
475 Title : fatal
476 Usage : $logger->fatal( "fatal message" );
477 Function: prints fatal message, depending on verbosity
478 Returns : invocant
479 Args : logging message
480  
481 =item set_listeners()
482  
483 Adds listeners to send log messages to.
484  
485 Type : Mutator
486 Title : set_listeners()
487 Usage : $logger->set_listeners( sub { warn shift } )
488 Function: Sets additional listeners to log to (e.g. a file)
489 Returns : invocant
490 Args : One or more code references
491 Comments: On execution of the listeners, the @_ arguments are:
492 $log_string, # the formatted log string
493 $level, # log level, i.e DEBUG, INFO, WARN, ERROR or FATAL
494 $subroutine, # the calling subroutine
495 $filename, # filename where log method was called
496 $line, # line where log method was called
497 $msg # the unformatted message
498  
499 =item start_color()
500  
501 Changes color of output stream to that of specified logging level. This so that for
502 example all errors are automatically marked up as 'FATAL', or all output generated
503 by an external program is marked up as 'DEBUG'
504  
505 Type : Mutator
506 Title : start_color()
507 Usage : $logger->start_color( 'DEBUG', \*STDOUT )
508 Function: Changes color of output stream
509 Returns : color name
510 Args : Log level whose color to use,
511 (optional) which stream to change, default is STDERR
512  
513 =item stop_color()
514  
515 Resets the color initiated by start_color()
516  
517 Type : Mutator
518 Title : stop_color()
519 Usage : $logger->stop_color( \*STDOUT )
520 Function: Changes color of output stream
521 Returns : color name
522 Args : (Optional) which stream to reset, default is STDERR
523  
524  
525 =item PREFIX()
526  
527 Getter and setter of path prefix to strip from source file paths in messages.
528 By default, messages will have a field such as C<[$PREFIX/Bio/Phylo.pm, 280]>,
529 which indicates the message was sent from line 280 in file Bio/Phylo.pm inside
530 path $PREFIX. This is done so that your log won't be cluttered with
531 unnecessarily long paths. To find out what C<$PREFIX> is set to, call the
532 PREFIX() method on the logger, and to change it provide a path argument
533 relative to which the paths to source files will be constructed.
534  
535 Type : Mutator/Accessor
536 Title : PREFIX()
537 Usage : $logger->PREFIX( '/path/to/bio/phylo' )
538 Function: Sets/gets $PREFIX
539 Returns : Verbose level
540 Args : Optional: a path
541 Comments:
542  
543 =item VERBOSE()
544  
545 Setter for the verbose level. This comes in five levels:
546  
547 FATAL = only fatal messages (though, when something fatal happens, you'll most
548 likely get an exception object),
549
550 ERROR = errors (hopefully recoverable),
551
552 WARN = warnings (recoverable),
553
554 INFO = info (useful diagnostics),
555
556 DEBUG = debug (almost every method call)
557  
558 Without additional arguments, i.e. by just calling VERBOSE( -level => $level ),
559 you set the global verbosity level. By default this is 2. By increasing this
560 level, the number of messages quickly becomes too great to make sense out of.
561 To focus on a particular class, you can add the -class => 'Some::Class'
562 (where 'Some::Class' stands for any of the class names in the Bio::Phylo
563 release) argument, which means that messages originating from that class will
564 have a different (presumably higher) verbosity level than the global level.
565 By adding the -method => 'Fully::Qualified::method_name' (say,
566 'Bio::Phylo::set_name'), you can change the verbosity of a specific method. When
567 evaluating whether or not to transmit a message, the method-specific verbosity
568 level takes precedence over the class-specific level, which takes precedence
569 over the global level.
570  
571 Type : Mutator
572 Title : VERBOSE()
573 Usage : $logger->VERBOSE( -level => $level )
574 Function: Sets/gets verbose level
575 Returns : Verbose level
576 Args : -level => 4 # or lower
577
578 # optional, or any other class
579 -class => 'Bio::Phylo'
580
581 # optional, fully qualified method name
582 -method' => 'Bio::Phylo::set_name'
583  
584 =back
585  
586 =head1 SEE ALSO
587  
588 There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo>
589 for any user or developer questions and discussions.
590  
591 Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com>.
592  
593 =head1 CITATION
594  
595 If you use Bio::Phylo in published research, please cite it:
596  
597 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
598 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
599 I<BMC Bioinformatics> B<12>:63.
600 L<http://dx.doi.org/10.1186/1471-2105-12-63>
601  
602 =cut
« Phylo/Matrices/Datatype.pm ↑ Summary Phylo/NeXML/DOM/Element/Twig.pm »