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 handleDESCRIPTION
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
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.