.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::WrapTie 3"
.TH IO::WrapTie 3 "2015-04-23" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::WrapTie \- wrap tieable objects in IO::Handle interface
.PP
This is currently Alpha code, released for comments.  
  Please give me your feedback!
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
First of all, you'll need \fItie()\fR, so:
.PP
.Vb 1
\&   require 5.004;
.Ve
.PP
\&\fIFunction interface (experimental).\fR
Use this with any existing class...
.PP
.Vb 2
\&   use IO::WrapTie;
\&   use FooHandle;                  ### implements TIEHANDLE interface
\&
\&   ### Suppose we want a "FooHandle\->new(&FOO_RDWR, 2)".
\&   ### We can instead say...
\&
\&   $FH = wraptie(\*(AqFooHandle\*(Aq, &FOO_RDWR, 2); 
\&
\&   ### Now we can use...    
\&   print $FH "Hello, ";            ### traditional operator syntax...
\&   $FH\->print("world!\en");         ### ...and OO syntax as well!
.Ve
.PP
\&\fI\s-1OO\s0 interface (preferred).\fR
You can inherit from the IO::WrapTie::Slave mixin to get a
nifty \f(CW\*(C`new_tie()\*(C'\fR constructor...
.PP
.Vb 2
\&   #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-    
\&   package FooHandle;                        ### a class which can TIEHANDLE
\&
\&   use IO::WrapTie;  
\&   @ISA = qw(IO::WrapTie::Slave);            ### inherit new_tie()
\&   ...
\&
\&
\&   #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-    
\&   package main; 
\&
\&   $FH = FooHandle\->new_tie(&FOO_RDWR, 2);   ### $FH is an IO::WrapTie::Master
\&   print $FH "Hello, ";                      ### traditional operator syntax
\&   $FH\->print("world!\en");                   ### OO syntax
.Ve
.PP
See IO::Scalar as an example.  It also shows you how to create classes
which work both with and without 5.004.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Suppose you have a class \f(CW\*(C`FooHandle\*(C'\fR, where...
.IP "\(bu" 4
\&\fBFooHandle does not inherit from IO::Handle;\fR that is, it performs
filehandle-like I/O, but to something other than an underlying
file descriptor.  Good examples are IO::Scalar (for printing to a
string) and IO::Lines (for printing to an array of lines).
.IP "\(bu" 4
\&\fBFooHandle implements the \s-1TIEHANDLE\s0 interface\fR (see perltie);
that is, it provides methods \s-1TIEHANDLE, GETC, PRINT, PRINTF,
READ,\s0 and \s-1READLINE.\s0
.IP "\(bu" 4
\&\fBFooHandle implements the traditional \s-1OO\s0 interface\fR of
FileHandle and IO::Handle; i.e., it contains methods like \fIgetline()\fR, 
\&\fIread()\fR, \fIprint()\fR, \fIseek()\fR, \fItell()\fR, \fIeof()\fR, etc.
.PP
Normally, users of your class would have two options:
.IP "\(bu" 4
\&\fBUse only \s-1OO\s0 syntax,\fR and forsake named I/O operators like 'print'.
.IP "\(bu" 4
\&\fBUse with tie,\fR and forsake treating it as a first-class object 
(i.e., class-specific methods can only be invoked through the underlying
object via \fItied()\fR... giving the object a \*(L"split personality\*(R").
.PP
But now with IO::WrapTie, you can say:
.PP
.Vb 4
\&    $WT = wraptie(\*(AqFooHandle\*(Aq, &FOO_RDWR, 2);
\&    $WT\->print("Hello, world\en");   ### OO syntax
\&    print $WT "Yes!\en";             ### Named operator syntax too!
\&    $WT\->weird_stuff;               ### Other methods!
.Ve
.PP
And if you're authoring a class like FooHandle, just have it inherit 
from \f(CW\*(C`IO::WrapTie::Slave\*(C'\fR and that first line becomes even prettier:
.PP
.Vb 1
\&    $WT = FooHandle\->new_tie(&FOO_RDWR, 2);
.Ve
.PP
\&\fBThe bottom line:\fR now, almost any class can look and work exactly like
an IO::Handle... and be used both with \s-1OO\s0 and non-OO filehandle syntax.
.SH "HOW IT ALL WORKS"
.IX Header "HOW IT ALL WORKS"
.SS "The data structures"
.IX Subsection "The data structures"
Consider this example code, using classes in this distribution:
.PP
.Vb 2
\&    use IO::Scalar;
\&    use IO::WrapTie;
\&
\&    $WT = wraptie(\*(AqIO::Scalar\*(Aq,\e$s);
\&    print $WT "Hello, ";
\&    $WT\->print("world!\en");
.Ve
.PP
In it, the \fIwraptie()\fR function creates a data structure as follows:
.PP
.Vb 10
\&                          * $WT is a blessed reference to a tied filehandle
\&              $WT           glob; that glob is tied to the "Slave" object.
\&               |          * You would do all your i/o with $WT directly.
\&               |       
\&               |
\&               |     ,\-\-\-isa\-\-> IO::WrapTie::Master >\-\-isa\-\-> IO::Handle
\&               V    /
\&        .\-\-\-\-\-\-\-\-\-\-\-\-\-. 
\&        |             | 
\&        |             |   * Perl i/o operators work on the tied object,  
\&        |  "Master"   |     invoking the TIEHANDLE methods.
\&        |             |   * Method invocations are delegated to the tied 
\&        |             |     slave.
\&        \`\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq 
\&               |    
\&    tied(*$WT) |     .\-\-\-isa\-\-> IO::WrapTie::Slave
\&               V    /   
\&        .\-\-\-\-\-\-\-\-\-\-\-\-\-.
\&        |             |
\&        |   "Slave"   |   * Instance of FileHandle\-like class which doesn\*(Aqt
\&        |             |     actually use file descriptors, like IO::Scalar.
\&        |  IO::Scalar |   * The slave can be any kind of object.
\&        |             |   * Must implement the TIEHANDLE interface.
\&        \`\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.PP
\&\fI\s-1NOTE:\s0\fR just as an IO::Handle is really just a blessed reference to a 
\&\fItraditional\fR filehandle glob... so also, an IO::WrapTie::Master 
is really just a blessed reference to a filehandle 
glob \fIwhich has been tied to some \*(L"slave\*(R" class.\fR
.SS "How \fIwraptie()\fP works"
.IX Subsection "How wraptie() works"
.IP "1." 4
The call to function \f(CW\*(C`wraptie(SLAVECLASS, TIEARGS...)\*(C'\fR is 
passed onto \f(CW\*(C`IO::WrapTie::Master::new()\*(C'\fR.  
Note that class IO::WrapTie::Master is a subclass of IO::Handle.
.IP "2." 4
The \f(CW\*(C`IO::WrapTie::Master::new\*(C'\fR method creates a new IO::Handle object,
reblessed into class IO::WrapTie::Master.  This object is the \fImaster\fR, 
which will be returned from the constructor.  At the same time...
.IP "3." 4
The \f(CW\*(C`new\*(C'\fR method also creates the \fIslave\fR: this is an instance 
of \s-1SLAVECLASS\s0 which is created by tying the master's IO::Handle 
to \s-1SLAVECLASS\s0 via \f(CW\*(C`tie(HANDLE, SLAVECLASS, TIEARGS...)\*(C'\fR.  
This call to \f(CW\*(C`tie()\*(C'\fR creates the slave in the following manner:
.IP "4." 4
Class \s-1SLAVECLASS\s0 is sent the message \f(CW\*(C`TIEHANDLE(TIEARGS...)\*(C'\fR; it 
will usually delegate this to \f(CW\*(C`SLAVECLASS::new(TIEARGS...)\*(C'\fR, resulting
in a new instance of \s-1SLAVECLASS\s0 being created and returned.
.IP "5." 4
Once both master and slave have been created, the master is returned
to the caller.
.SS "How I/O operators work (on the master)"
.IX Subsection "How I/O operators work (on the master)"
Consider using an i/o operator on the master:
.PP
.Vb 1
\&    print $WT "Hello, world!\en";
.Ve
.PP
Since the master ($WT) is really a [blessed] reference to a glob, 
the normal Perl i/o operators like \f(CW\*(C`print\*(C'\fR may be used on it.
They will just operate on the symbol part of the glob.
.PP
Since the glob is tied to the slave, the slave's \s-1PRINT\s0 method 
(part of the \s-1TIEHANDLE\s0 interface) will be automatically invoked.
.PP
If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be 
invoked, and that method happens to delegate to the \f(CW\*(C`print()\*(C'\fR method 
of the same class.  So the \fIreal\fR work is ultimately done by 
\&\fIIO::Scalar::print()\fR.
.SS "How methods work (on the master)"
.IX Subsection "How methods work (on the master)"
Consider using a method on the master:
.PP
.Vb 1
\&    $WT\->print("Hello, world!\en");
.Ve
.PP
Since the master ($WT) is blessed into the class IO::WrapTie::Master,
Perl first attempts to find a \f(CW\*(C`print()\*(C'\fR method there.  Failing that,
Perl next attempts to find a \f(CW\*(C`print()\*(C'\fR method in the superclass,
IO::Handle.  It just so happens that there \fIis\fR such a method;
that method merely invokes the \f(CW\*(C`print\*(C'\fR i/o operator on the self object...
and for that, see above!
.PP
But let's suppose we're dealing with a method which \fIisn't\fR part
of IO::Handle... for example:
.PP
.Vb 1
\&    my $sref = $WT\->sref;
.Ve
.PP
In this case, the intuitive behavior is to have the master delegate the
method invocation to the slave (now do you see where the designations
come from?).  This is indeed what happens: IO::WrapTie::Master contains
an \s-1AUTOLOAD\s0 method which performs the delegation.
.PP
So: when \f(CW\*(C`sref()\*(C'\fR can't be found in IO::Handle, the \s-1AUTOLOAD\s0 method
of IO::WrapTie::Master is invoked, and the standard behavior of
delegating the method to the underlying slave (here, an IO::Scalar)
is done.
.PP
Sometimes, to get this to work properly, you may need to create 
a subclass of IO::WrapTie::Master which is an effective master for
\&\fIyour\fR class, and do the delegation there.
.SH "NOTES"
.IX Header "NOTES"
\&\fBWhy not simply use the object's \s-1OO\s0 interface?\fR 
    Because that means forsaking the use of named operators
like \fIprint()\fR, and you may need to pass the object to a subroutine
which will attempt to use those operators:
.PP
.Vb 2
\&    $O = FooHandle\->new(&FOO_RDWR, 2);
\&    $O\->print("Hello, world\en");  ### OO syntax is okay, BUT....
\&
\&    sub nope { print $_[0] "Nope!\en" }
\& X  nope($O);                     ### ERROR!!! (not a glob ref)
.Ve
.PP
\&\fBWhy not simply use \f(BItie()\fB?\fR 
    Because (1) you have to use \fItied()\fR to invoke methods in the
object's public interface (yuck), and (2) you may need to pass 
the tied symbol to another subroutine which will attempt to treat 
it in an OO-way... and that will break it:
.PP
.Vb 2
\&    tie *T, \*(AqFooHandle\*(Aq, &FOO_RDWR, 2; 
\&    print T "Hello, world\en";   ### Operator is okay, BUT... 
\&
\&    tied(*T)\->other_stuff;      ### yuck! AND...
\&
\&    sub nope { shift\->print("Nope!\en") }
\& X  nope(\e*T);                  ### ERROR!!! (method "print" on unblessed ref)
.Ve
.PP
\&\fBWhy a master and slave? 
  Why not simply write FooHandle to inherit from IO::Handle?\fR
    I tried this, with an implementation similar to that of IO::Socket.  
The problem is that \fIthe whole point is to use this with objects
that don't have an underlying file/socket descriptor.\fR.
Subclassing IO::Handle will work fine for the \s-1OO\s0 stuff, and fine with 
named operators \fIif\fR you \fItie()\fR... but if you just attempt to say:
.PP
.Vb 2
\&    $IO = FooHandle\->new(&FOO_RDWR, 2);
\&    print $IO "Hello!\en";
.Ve
.PP
you get a warning from Perl like:
.PP
.Vb 1
\&    Filehandle GEN001 never opened
.Ve
.PP
because it's trying to do system-level i/o on an (unopened) file 
descriptor.  To avoid this, you apparently have to \fItie()\fR the handle...
which brings us right back to where we started!  At least the
IO::WrapTie mixin lets us say:
.PP
.Vb 2
\&    $IO = FooHandle\->new_tie(&FOO_RDWR, 2);
\&    print $IO "Hello!\en";
.Ve
.PP
and so is not \fItoo\fR bad.  \f(CW\*(C`:\-)\*(C'\fR
.SH "WARNINGS"
.IX Header "WARNINGS"
Remember: this stuff is for doing FileHandle-like i/o on things
\&\fIwithout underlying file descriptors\fR.  If you have an underlying
file descriptor, you're better off just inheriting from IO::Handle.
.PP
\&\fBBe aware that \f(BInew_tie()\fB always returns an instance of a
kind of IO::WrapTie::Master...\fR it does \fBnot\fR return an instance 
of the i/o class you're tying to!
.PP
Invoking some methods on the master object causes \s-1AUTOLOAD\s0 to delegate
them to the slave object... so it \fIlooks\fR like you're manipulating a 
\&\*(L"FooHandle\*(R" object directly, but you're not.
.PP
I have not explored all the ramifications of this use of \fItie()\fR.
\&\fIHere there be dragons\fR.
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $
.SH "AUTHOR"
.IX Header "AUTHOR"
.IP "Primary Maintainer" 4
.IX Item "Primary Maintainer"
Dianne Skoll (\fIdfs@roaringpenguin.com\fR).
.IP "Original Author" 4
.IX Item "Original Author"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 481:" 4
.IX Item "Around line 481:"
\&'=item' outside of any '=over'
.Sp
=over without closing =back