Tie::Handle::Filter - [DEPRECATED] filters filehandle output through a coderef
version 0.011
use Tie::Handle::Filter;
# prefix output to STDERR with standard Greenwich time
BEGIN {
tie *STDERR, 'Tie::Handle::Filter', *STDERR,
sub { scalar(gmtime) . ': ', @_ };
}
DEPRECATION NOTICE: This module distribution is deprecated in favor of Text::OutputFilter, which is more robust while being functionally identical, or PerlIO::via::dynamic, which uses a different mechanism that may offer better performance.
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.
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
.
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
.
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.
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.
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.
open
(e.g., re-opening the file handle)
-
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
.
Mark Gardner mjgardner@cpan.org
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.