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