NAME

Log::Dump - simple logger mainly for debugging

SYNOPSIS

use Log::Dump; # installs 'log' and other methods

# class log
__PACKAGE__->log( error => 'foo' );

# object log
sub some_method {
  my $self = shift;

  # you can pass multiple messages (will be concatenated)
  # and objects (will be dumped via L<Data::Dump>).
  $self->log( info => 'my self is ', $self );
}

# you can control which log should be shown by labels.
sub broken_method {
  my $self = shift;

  $self->logfilter('broken_only');
  $self->log( broken_only => 'shown' );
  $self->log( debug       => 'not shown' );
}

# you can log to a file
__PACKAGE__->logfile('log.txt');
__PACKAGE__->log( file => 'will be saved' );
__PACKAGE__->logfile('');  # to close

# you can color logs to stderr
sub important_method {
  my $self = shift;
  $self->logcolor( important => 'bold red on_white' );
  $self->log( important => 'bold red message' );
  $self->logcolor(0);  # no color
}

# you can log with timestamp
__PACKAGE__->logtime(1);
$self->log( $ENV{REMOTE_ADDR} => 'foo' );
__PACKAGE__->logtime(0); # hide timestamp

# you can turn off the logging; set to true to turn on.
__PACKAGE__->logger(0);

# or you can use better loggers (if they have a 'log' method)
__PACKAGE__->logger( Log::Dispatch->new );

DESCRIPTION

Log::Dump is a simple logger mix-in mainly for debugging. This installs six methods into a caller (the class that used Log::Dump) via Sub::Install. The point is you don't need to load extra dumper modules or you don't need to concatenate messages. Just log things and they will be dumped (and concatenated if necessary) to stderr, and to a file if you prefer. Also, you can use these logging methods as class methods or object methods (though usually you don't want to mix them, especially when you're doing something special).

METHODS

log

logs things to stderr. The first argument (other than class/object) is considered as a label for the messages, and will be wrapped with square blackets. Objects in the messages will be dumped through Data::Dump, and multiple messages will be concatenated. And usually line feed/carriage return will be appended.

The fatal label is special: if you log things with this label, the logger croaks the messages (and usually the program will die).

Also, if you log things with error or warn labels, the logger carps the messages (with a line number and a file name).

Other labels have no special meaning for the logger, but as you can filter some of the logs with these labels, try using meaningful ones for you.

Note that these special labels doesn't work with custom loggers. Actually, you can pass anything to log method to conform to your logger's requirement.

logger

turns on/off the logger if you set this to true/false (preferably, 1/0 to avoid confusion). And if you set a class name (or an object) that provides log method, it will be used while logging.

logfilter

If you specify some labels through this, only logs with those labels will be shown. Set a false value to disable this filtering.

logfile

If you want to log to a file, set a file name, and an optional open mode for IO::File (w for write by default). When you set a false value, the opened file will be closed. Note that this doesn't disable logging to stderr. Logs will be dumped both to stderr and to a file while the file is open.

logcolor

If you want to color logs to stderr, provide a label and its color specification (actually a hash of them) to logcolor. Then, log will be colored (if Term::ANSIColor is installed and your terminal supports the specification). If you set a false scalar, coloring will be disabled. See Term::ANSIColor for color specifications.

logtime

If you set this to true, timestamp will be prepended. You can pass a strftime format if you need finer control. Set a false value to disable this timestamp.

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kenichi Ishigaki.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.