NAME

Log::WithCallbacks - A simple, object oriented logfile management library.

SYNOPSIS

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";
} );

DESCRIPTION

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.

METHODS

new

$log_obj = new( $path, [$format] )

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

open( [$mode, $format] )

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.

close

close()

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.

entry

entry( $message, [$format] )

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.

exit

exit( $status_code, $message, [$format] )

Calls entry($message, $format), then sets $! to $status_code (which must be numeric) and terminates the script. See "entry" for more information.

status

$string = status()

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.

mode

$string = entry( [$mode] )

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.

format

$code_ref = format( [$format] )

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

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.

 # 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++ );
    }
 }

BUGS

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.

AUTHOR

Mark Swayne, <mark.swayne@chater.net> Copyright 2002, Mark Swayne Copyright 2005, Zydax, LLC.

LICENSE

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