The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-Replace-0.04
River stage one • 2 direct dependents • 2 total dependents
1 ++
/ Tie::Handle::Base

Name

Tie::Handle::Base - A base class for tied filehandles

Synopsis

 package Tie::Handle::Mine;
 use parent 'Tie::Handle::Base';
 sub WRITE {
     my $self = shift;
     print STDERR "Debug: Output '$_[0]'\n";
     return $self->SUPER::WRITE(@_);
 }

Then use your custom tied handle:

 open my $fh, '>', $filename or die $!;
 $fh = Tie::Handle::Mine->new($fh);  # replace orig. handle with tied
 print $fh "Hello, World";           # debug message will be printed
 close $fh;

Description

A base class for tied filehandles similar to Tie::StdHandle, but with a few important differences.

  • The tied object is a hashref, so that subclasses have an easier time storing information in the object hash. The inner handle which is wrapped by this tied handle should be passed to its TIEHANDLE and is stored with the hash key _innerhandle. Subclasses should consider all fields with an underscore as reserved. If no handle is passed to TIEHANDLE, it will create a new anonymous one as the inner handle.

  • It provides a constructor new which will create a new lexical filehandle, tie it to the class, and return that filehandle. Any arguments to new are passed through to TIEHANDLE, including the (optional) inner handle as the first argument. Subclasses may choose to override new and/or TIEHANDLE to modify this behavior.

  • A few limitations that exist in Tie::StdHandle (at least versions up to and including 4.4) have been lifted: BINMODE accepts the LAYER argument, and WRITE will return the length of the string written (similar caveats in regards to Unicode/UTF-8 data as documented in syswrite apply).

  • Although the functions PRINT and PRINTF are implemented in terms of WRITE, so that you can modify the output behavior by only overriding WRITE, WRITE itself is implemented in terms of a function _WRITE which takes a filehandle and emulates syswrite behavior using the core print. This might be an important detail to you if you are overriding any of these functions; see the code for details.

This documentation describes version 0.04 of this module.

Notes

See Also: perltie, "tie" in perlfunc, Tie::Handle, Tie::StdHandle

The full list of functions that tied handles can/should implement is:

 BINMODE, CLOSE, DESTROY,  EOF,  FILENO, GETC,      OPEN,  PRINT,
 PRINTF,  READ,  READLINE, SEEK, TELL,   TIEHANDLE, UNTIE, WRITE

Author, Copyright, and License

Copyright (c) 2017 Hauke Daempfling (haukex@zero-g.net) at the Leibniz Institute of Freshwater Ecology and Inland Fisheries (IGB), Berlin, Germany, http://www.igb-berlin.de/

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.