/ 
Tie-LogFile-0.1
River stage zero No dependents
/ Tie::LogFile

NAME

Tie::LogFile - Simple Log Autoformating

SYNOPSIS

use Tie::LogFile;
my $logfile = '/var/log/foo';

tie(*LOG, 'Tie::LogFile', $logfile,
	format  => '%c (%p) [%d] %m',
	tformat => '%X %x')           or die $!;
	
print LOG "Starting Run";
# Do stuff...
print LOG "Did @stuff";
# Clean up
print LOG "Exiting";

close(LOG) or die "Couldn't close $logfile\n";

DESCRIPTION

This module provides a quick and simple way to print out a log file with a repetative format. In many of my projects I had something like this:

sub logit {
	print $LOG scalar localtime, @_;
}

This is less than flexible, and still lends itself to loglines that do not follow the logs format. The Tie::LogFile module is format based, when you first tie (really create) the filehandle, you have the option of giving the format you wish the log lines to follow. The format is in the same format as printf. See the formats section for more information.

Tieing The Handle

The basic form of the tie call is as follows:

tie *HANDLE, 'Tie::LogFile', '/path/to/log';

If this is foreign to you, you might want to take a look at the perltie manpage. After the required arguements, there are several options that can be passed:

  • format

    The format option allows one to set the general format for the log file. The syntax of this option is in the same vain as sprintf, but with it's own set of tags. The most basic of these tags is %d for the time/date stamp, and %m for the log message. The tags are case sensitive. The default format is "[%d] %m". At the minimum, the %m tag much be specified.

  • tformat

    Sets the time format printed for the %d top level tag. This format is passed directly to Date::Format::time2str() if you have Data::Format installed, otherwise it is passed to POSIX::strftime(). If no format is set, then neither module is used, and the %d tag is filled with the output of scalar localtime.

  • mode

    By default Tie::LogFile opens the logfile using the >> file mode, you can change with the mode option. However, at least for now, Tie::LogFile only supports > and >>.

  • force_newline

    By default Tie::LogFile makes sure that there is a newline at the end of every print, this this behavior can be changed with the force_newline option.

  • autoflush

    By default Tie::LogFile does not autoflush the filehandle. Autoflush can be turned on with this option.

Log Formatting

In it's intial release, Tie::LogFile supports 5 formatting tags. Anyone with a good idea for a tag is encouraged to try it out, and tell the author. Any good tags will make it into furture revisions.

The included tags are:

  • %m

    The log message, this is what ever you pass to print or printf. This tag is the only manditory tag.

  • %d

    The date/time stamp. You can alter the format of this, by using the tformat option.

  • %p

    The process ID ($$).

  • %c

    Tie::LogFile maintains a count of the number of lines it prints, use %c to include that count in your log files.

  • %%

    A literal '%'.

Including your own tags.

There is an easy interface for defining your own tags for the format option. The %Tie::LogFile::formats hash contains a coderef for each tag. For example the default definition for the %p tag is something like:

$Tie::LogFile::formats{'p'} = sub { $$ };

You can override include tags, as in this very confusing tag:

$Tie::LogFile::formats{'d'} = sub { scalar localtime(rand(1000000000)) };

Or define new tags, such as:

$Tie::LogFile::formats{'u'} = sub { POSIX::uname() };

The subs in the formats hash are passed two things, $_[0] is the tied typeglob, while $_[1] is the logline being printed. For example:

$Tie::LogFile::formats{'l'} = sub { length $_[1] };

BUGS

No know bugs, but bugs are always a possibility.

TODO

  • Reading from the handle.

  • More Speed.

AUTHOR

Chris Reinhardt, <ctriv@dyndns.org>

SEE ALSO

Date::Format, POSIX, perltie, perl.