/ 
Tie-Handle-Filter-0.009-TRIAL
River stage one • 1 direct dependent • 2 total dependents
/ Tie::Handle::Filter

NAME

Tie::Handle::Filter - filters the output to a filehandle through a coderef

VERSION

version 0.009

SYNOPSIS

use Tie::Handle::Filter;

# prefix output to STDERR with standard Greenwich time
BEGIN {
    tie *STDERR, 'Tie::Handle::Filter', *STDERR,
        sub { scalar(gmtime) . ': ', @_ };
}

DESCRIPTION

This is a small module for changing output when it is sent to a given file handle. By default it passes everything unchanged, but when provided a code reference, that reference is passed the string being sent to the tied file handle and may return a transformed result.

METHODS

PRINT

All arguments to print and say directed at the tied file handle are passed to the user-defined function, and the result is then passed to print.

PRINTF

The second and subsequent arguments to printf (i.e., everything but the format string) directed at the tied file handle are passed to the user-defined function, and the result is then passed preceded by the format string to printf.

Please note that this does not include calls to sprintf.

WRITE

The first argument to syswrite (i.e., the buffer scalar variable) directed at the tied file handle is passed to the user-defined function, and the result is then passed along with the optional second and third arguments (i.e., length of data in bytes and offset within the string) to syswrite.

Note that if you do not provide a length argument to syswrite, it will be computed from the result of the user-defined function. However, if you do provide a length (and possibly offset), they will be relative to the results of the user-defined function, not the input.

EXTENDS

REQUIRES

OTHER INCLUDED MODULES

Tie::Handle::Filter::Output::Timestamp

Prepends filehandle output with a timestamp, optionally formatted via strftime.

Tie::Handle::Filter::Output::Timestamp::EveryLine

Prepends every line of filehandle output with a timestamp, optionally formatted via strftime.

DIAGNOSTICS

Wherever possible this module attempts to emulate the built-in functions it ties, so it will return values as expected from whatever function is called. Certain operations may also croak (throw a fatal exception) if they fail, such as aliasing the file handle during a tie or attempting to perform an unsupported operation on a tied file handle.

BUGS AND LIMITATIONS

If your function needs to know what operation was used to call it, consider using (caller 1)[3] to determine the method used to call it, which will return Tie::Handle::Filter::PRINT, Tie::Handle::Filter::PRINTF, or Tie::Handle::Filter::WRITE per "Tying FileHandles" in perltie.

Currently this module is biased towards write-only file handles, such as STDOUT, STDERR, or ones used for logging. It does not (yet) define the following methods and their associated functions, so don't do them with file handles tied to this class.

READ

read
sysread

READLINE

<HANDLE>
readline

GETC

getc

OPEN

open (e.g., re-opening the file handle)

BINMODE

binmode

EOF

eof

TELL

tell

SEEK

seek

AUTHOR

Mark Gardner <mjgardner@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by cPanel, Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.