Log::WithCallbacks - A simple, object oriented logfile management library.
use Log::WithCallbacks; my $logfile = '/var/log/perl/mylog'; # Basic usage my $log = Log::WithCallbacks->new( $logfile ); $log->open(); $log->entry("Stuff happened"); $log->exit(23, "Bad stuff happened and I am shutting down"); $log->close(); # Advanced functionality my $errors = Log::WithCallbacks->new( $logfile, sub { return "OOPS: $_[0]\n" } ); $log->entry($hash_ref, sub { Dumper @_ }); $log->exit(5, "Bad stuff happened and I am shutting down", 'standard' }); my $status = $log->status(); my $mode = $log->mode('overwrite'); my $format = $log->format( sub { my $message = shift; return "\t$message\n"; } );
Log::WithCallbacks is intended to simplify aspects of managing a logfile. It uses object oriented interface that is both simple and flexible. This module will not pollute your namespace, it does not export anything.
This method is the class' constructor. You must provide a filename for the logfile; while it is best to use a fully qualified name, any name acceptable to open will do. It is also possible to pass in a subroutine reference to set the default format routine. The default format routine will be used to process the message parameters to all calls to entry and exit. See "format" for more information on format routines.
open
entry
exit
Opens a filehandle to the logfile and sets the status to b<open>. The method has two optional arguments, $mode and $format. $mode can be either append or overwrite, it controls whether the filehandle will append to or overwrite the file it opens. $format provides another opportunity to set the default format routine, see "new" and "format" for more information. This method will die if it cannot open the filehandle, if this is not acceptable, you will need to use eval {} to trap the exception.
$mode
$format
eval {}
Closes an open logfile and sets the status to b<closed>. This method will die if it cannot close the filehandle, if this is not acceptable, you will need to use eval {} to trap the exception.
Writes $message to the logfile, after passing it through the format routine. If the optional $format argument is sent, the routine provided will be used. Otherwise the default format routine will be used. $message is usually a string, but can be just about anything, depending on the format routine that will process it. See "format" for more information on format routines.
$message
Calls entry($message, $format), then sets $! to $status_code (which must be numeric) and terminates the script. See "entry" for more information.
entry($message, $format)
$!
$status_code
Returns the current status of the logfile object. Should only return closed or open. If an untrapped error has occurred, it may return a status of opening or closing.
Gets or sets the mode of the logfile object. Allowed modes are append and overwrite. The mode can only be changed when the object's status is closed. Returns the mode as a string, or 0 on a failed attempt to set the mode.
Gets or sets the object's default format routine. Returns a reference to the default format routine, or 0 on a failed attempt to set the format routine. Can take either the string standard or a code reference as an argument. If $format is standard, then the standard formatter that is built into the module will be used.
Format routines are used to process all messages that are logged. This feature is what makes this module particularly flexible. A format routine takes one argument, usually a string, and returns a list suitable for print to process.
print
# Example Format Routines # Standard Default Routine $log->format( sub { my $message = shift; chomp $message; # Clean up any accidental double lines. return scalar time . ": $message\n"; } ); # Do nothing $log->format( sub { return @_ } ); # Using Data::Dumper to look inside a few variables $log->entry( [$hash_ref, $array_ref], sub { Dumper @_ } ); # Use a closure to generate line numbers { my $counter = 1; $log->format( sub { my $message = shift; chomp $message; return sprintf( "%-3.3d - $message\n", $counter++ ); } }
No known bugs exist. Tainting and better validation of file names should be put in place before this library should handle untrusted input. Of particular concern is the path argument to the contstructor, as this is passed to the open builtin.
path
Mark Swayne, <mark.swayne@chater.net> Copyright 2002, Mark Swayne Copyright 2005, Zydax, LLC.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Log::WithCallbacks, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::WithCallbacks
CPAN shell
perl -MCPAN -e shell install Log::WithCallbacks
For more information on module installation, please visit the detailed CPAN module installation guide.