NAME

PerlIO::via::Logger - PerlIO layer for prefixing current time to log output

SYNOPSIS

 use PerlIO::via::Logger;
 PerlIO::via::Logger->format( '[%b %d, %Y %r] ' );

 use PerlIO::via::Logger format => '[%b %d, %Y %r] ';

 open( my $in,'<:via(Logger)','filein' )
  or die "Can't open file.ln for reading: $!\n";
 
 open( my $out,'>:via(Logger)','fileout' )
  or die "Can't open file.ln for writing: $!\n";

 PerlIO::via::Logger::logify(*STDOUT);  # redirect stdout in one line!

 PerlIO::via::Logger::logify(*openhandle);  # or any other handle

DESCRIPTION

This module implements a PerlIO layer that prefixes the current time to each line of output or input. This module was created because I frequently need to use file logging systems in daemon-style Perl systems. This module was created to fulfill three requirements:

1. Must be low overhead/fast

2. Must be simple to use (i.e. print "something to log\n")

3. Must be able to add a prefix to each line (times in my case)

Note: the format string accepts the format specification of strftime(3) on your system. You may use the command "man 3 strftime" to view the behavior of strftime on your system. Or see this page: http://www.hmug.org/man/3/strftime.php

CLASS METHODS

The following two class methods allow you to alter the prefix formatting string used by the I/O layer and to redirect existing filehandles with (almost) no effort.

For convienance, class methods can also be called as key-value pairs in the use statement. This allows you to use this module in an "import and forget it" fashion.

Please note that the new value of the class methods that are specified, only apply to the file handles that are opened (or to which the layer is assigned using binmode()) after they have been changed.

format

 use PerlIO::via::Logger format => '[%b %d, %Y %r] ';
 
 PerlIO::via::Logger->format( '[%b %d, %Y %r] ' );
 my $format = PerlIO::via::Logger->format;

The class method format returns the format that will be used for adding the time to lines. The optional input parameter specifies the format that will be used for any files that are opened in the future. You should use only the conversion specifiers defined by the ANSI C standard (C89, to play safe). These are aAbBcdHIjmMpSUwWxXyYZ% . The default is '[%b %d, %Y %H:%M:%S] ', though the examples throughout this document use a more elegant - but less portable - format.

logify

 PerlIO::via::Logger::logify( $filehandle );
 PerlIO::via::Logger::logify( *WRITEFH );
 PerlIO::via::Logger::logify( *STDOUT );

The class method logify exists purely for convenience and my personal use. I do not recommend using it unless your systems are for development only, or you understand how it works. In short it will reopen the given filehandle through the Logger I/O layer.

FILL

 PerlIO::via::Logger->FILL()

This method is required for PerlIO modules. Do NOT use it unless you know what you are doing.

PUSHED

 PerlIO::via::Logger->PUSHED()

This method is required for PerlIO modules. Do NOT use it unless you know what you are doing.

EXAMPLES

Here are some examples for your reading pleasure:

Sending STDOUT to a log file

The following code redirects STDOUT through the Logger without using logify() Note the use of >&: instead of >: because this is a filehandle glob.

 #!/usr/bin/perl
 use PerlIO::via::Logger;
 open my $stdout, ">&STDOUT";
 close STDOUT;
 open (STDOUT, ">&:via(Logger)", $stdout)
   or die "Unable to logify standard output: $!\n";
 print "Something that needs a time!\n";

Goes to STDOUT as:

 [Jan 01, 2007 01:23:45] Something that needs a time!

Using an file-based log and silly custom prefix

This would probably be the most common use:

 #!/usr/bin/perl
 use PerlIO::via::Logger format => 'Logtastic: ';
 open (OUT, ">:via(Logger)", 'foo.log')
   or die "Unable to open foo.log: $!\n";
 print OUT "The format string does not need any time variables.";

Would output the following into the file 'foo.log'

 Logtastic: The format string does not need any time variables.

DEPENDANCIES

This module is free of any dependancies beyond what is included by default with the version of Perl I used to create and test it, version 5.8.6.

Required Modules

POSIX

Optional Testing Dependancies

Pod::Simple Test::Pod::Coverage

The Pod tests that are included with this distribution require the two modules listed above. However, running the test suite is optional, and the test scripts will not break if these modules are missing.

BUGS, LIMITATIONS AND FEATURE REQUESTS

Known Bugs and Limitations

None at this time.

Reporting Bugs

Please report any bugs and/or feature requests to bug-PerlIO-via-Logger at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PerlIO-via-Logger. Be as detailed as possible when describing problems. The RT system will notify me automatically and keep you updated as we work to resolve your issue.

SEE ALSO

PerlIO::via and any other PerlIO::via modules on CPAN. POSIX and man 3 strftime on your system.

AUTHOR

Adam J. Kaplan <akaplan at cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2007 Adam J Kaplan. All rights reserved. Based on snippets of code from Elizabeth Mattijsen's PerlIO::via modules. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm PerlIO::via::Logger

perl -MCPAN -e shell
install PerlIO::via::Logger