/ 
Tie-Log-0.1
/ Tie::Log

NAME

Tie::Log - Simple Log Autoformating

SYNOPSIS

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

tie(*LOG, 'Tie::Log', $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::Log 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::Log', '/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. Also, if no format is set, then Tie::Log will not try to load either module.

  • mode

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

  • force_newline

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

Log Formatting

In it's intial release, Tie::Log 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::Log 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::Log::formats hash contains a coderef for each tag. For example the default definition for the %p tag is something like:

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

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

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

Or define new tags, such as:

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

Sharp minds will wonder why not just do this:

$Tie::Log::formats{'u'} = \&POSIX::uname; # Wrong!

The subs in the formats hash are passed two things, $_[0] is the tied typeglob, while $_[1] is the logline being printed. POSIX::uname will die when passed arguments. This has advanteges however. It lets you do something something like this:

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

Somewhere, out there, this is useful to someone.

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.