/ 
PerlIO-via-Logger-0.03
River stage zero No dependents
/ PerlIO::via::Logger

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:

'=over 4' =item 1. Must be low overhead/fast =item 2.' Must be extremely simple to use (i.e. print "something to log\n")" =item 3.' Must be able to add a prefix to each line (namely time) =back

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 system- specific behavior, or try this one: 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.

REQUIRED MODULES

POSIX

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.

SEE ALSO

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

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.