/usr/share/doc/libio-stringy-perl/html/WrapTie.pm.html is in libio-stringy-perl 2.110-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | <HTML>
<HEAD>
<TITLE>IO::WrapTie 2.102</TITLE>
</HEAD>
<BODY
bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
<FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::WrapTie 2.102</H1>
</A><UL>
<LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
<LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
<LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
<LI> <A NAME="menu:HOW_IT_ALL_WORKS"><A HREF="#HOW_IT_ALL_WORKS">HOW IT ALL WORKS</A></A>
<UL>
<LI> <A NAME="menu:The_data_structures"><A HREF="#The_data_structures">The data structures</A></A>
<LI> <A NAME="menu:How_wraptie_works"><A HREF="#How_wraptie_works">How wraptie() works</A></A>
<LI> <A NAME="menu:How_I_O_operators_work_on_the_master"><A HREF="#How_I_O_operators_work_on_the_master">How I/O operators work (on the master)</A></A>
<LI> <A NAME="menu:How_methods_work_on_the_master"><A HREF="#How_methods_work_on_the_master">How methods work (on the master)</A></A>
</UL>
<LI> <A NAME="menu:NOTES"><A HREF="#NOTES">NOTES</A></A>
<LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A>
<LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A>
<LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
</UL>
<P><HR>
<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>
<P>IO::WrapTie - wrap tieable objects in IO::Handle interface
<P><I>This is currently Alpha code, released for comments.
Please give me your feedback!</I>
<P><HR>
<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>
<P>First of all, you'll need tie(), so:
<FONT SIZE=3 FACE="courier"><PRE>
require 5.004;
</PRE></FONT>
<P><I>Function interface (experimental).</I>
Use this with any existing class...
<FONT SIZE=3 FACE="courier"><PRE>
use IO::WrapTie;
use FooHandle; ### implements TIEHANDLE interface
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
### Suppose we want a "FooHandle->new(&FOO_RDWR, 2)".
### We can instead say...
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
$FH = wraptie('FooHandle', &FOO_RDWR, 2);
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
### Now we can use...
print $FH "Hello, "; ### traditional operator syntax...
$FH->print("world!\n"); ### ...and OO syntax as well!
</PRE></FONT>
<P><I>OO interface (preferred).</I>
You can inherit from the IO::WrapTie::Slave mixin to get a
nifty <CODE>new_tie()</CODE> constructor...
<FONT SIZE=3 FACE="courier"><PRE>
#------------------------------
package FooHandle; ### a class which can TIEHANDLE
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
use IO::WrapTie;
@ISA = qw(IO::WrapTie::Slave); ### inherit new_tie()
...
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
#------------------------------
package main;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
$FH = FooHandle->new_tie(&FOO_RDWR, 2); ### $FH is an IO::WrapTie::Master
print $FH "Hello, "; ### traditional operator syntax
$FH->print("world!\n"); ### OO syntax
</PRE></FONT>
<P>See IO::Scalar as an example. It also shows you how to create classes
which work both with and without 5.004.
<P><HR>
<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
<P>Suppose you have a class <CODE>FooHandle</CODE>, where...
<UL>
<P><LI>
<P><B>FooHandle does not inherit from IO::Handle;</B> 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).
<P><LI>
<P><B>FooHandle implements the TIEHANDLE interface</B> (see <A HREF="perltie.pm.html">perltie</A>);
that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF,
READ, and READLINE.
<P><LI>
<P><B>FooHandle implements the traditional OO interface</B> of
FileHandle and IO::Handle; i.e., it contains methods like getline(),
read(), print(), seek(), tell(), eof(), etc.
</UL>
<P>Normally, users of your class would have two options:
<UL>
<P><LI>
<P><B>Use only OO syntax,</B> and forsake named I/O operators like 'print'.
<P><LI>
<P><B>Use with tie,</B> and forsake treating it as a first-class object
(i.e., class-specific methods can only be invoked through the underlying
object via tied()... giving the object a "split personality").
</UL>
<P>But now with IO::WrapTie, you can say:
<FONT SIZE=3 FACE="courier"><PRE>
$WT = wraptie('FooHandle', &FOO_RDWR, 2);
$WT->print("Hello, world\n"); ### OO syntax
print $WT "Yes!\n"; ### Named operator syntax too!
$WT->weird_stuff; ### Other methods!
</PRE></FONT>
<P>And if you're authoring a class like FooHandle, just have it inherit
from <CODE>IO::WrapTie::Slave</CODE> and that first line becomes even prettier:
<FONT SIZE=3 FACE="courier"><PRE>
$WT = FooHandle->new_tie(&FOO_RDWR, 2);
</PRE></FONT>
<P><B>The bottom line:</B> now, almost any class can look and work exactly like
an IO::Handle... and be used both with OO and non-OO filehandle syntax.
<P><HR>
<A NAME="HOW_IT_ALL_WORKS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> HOW IT ALL WORKS</H2></A>
<P><HR>
<A NAME="The_data_structures"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> The data structures</H3></A>
<P>Consider this example code, using classes in this distribution:
<FONT SIZE=3 FACE="courier"><PRE>
use IO::Scalar;
use IO::WrapTie;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
$WT = wraptie('IO::Scalar',\$s);
print $WT "Hello, ";
$WT->print("world!\n");
</PRE></FONT>
<P>In it, the wraptie() function creates a data structure as follows:
<FONT SIZE=3 FACE="courier"><PRE>
* $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.
`-------------'
|
tied(*$WT) | .---isa--> IO::WrapTie::Slave
V /
.-------------.
| |
| "Slave" | * Instance of FileHandle-like class which doesn't
| | actually use file descriptors, like IO::Scalar.
| IO::Scalar | * The slave can be any kind of object.
| | * Must implement the TIEHANDLE interface.
`-------------'
</PRE></FONT>
<P><I>NOTE:</I> just as an IO::Handle is really just a blessed reference to a
<I>traditional</I> filehandle glob... so also, an IO::WrapTie::Master
is really just a blessed reference to a filehandle
glob <I>which has been tied to some "slave" class.</I>
<P><HR>
<A NAME="How_wraptie_works"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How wraptie() works</H3></A>
<OL>
<P><LI>
<P>The call to function <CODE>wraptie(SLAVECLASS, TIEARGS...)</CODE> is
passed onto <CODE>IO::WrapTie::Master::new()</CODE>.
Note that class IO::WrapTie::Master is a subclass of IO::Handle.
<P><LI>
<P>The <CODE>IO::WrapTie::Master::new</CODE> method creates a new IO::Handle object,
reblessed into class IO::WrapTie::Master. This object is the <I>master</I>,
which will be returned from the constructor. At the same time...
<P><LI>
<P>The <CODE>new</CODE> method also creates the <I>slave</I>: this is an instance
of SLAVECLASS which is created by tying the master's IO::Handle
to SLAVECLASS via <CODE>tie(HANDLE, SLAVECLASS, TIEARGS...)</CODE>.
This call to <CODE>tie()</CODE> creates the slave in the following manner:
<P><LI>
<P>Class SLAVECLASS is sent the message <CODE>TIEHANDLE(TIEARGS...)</CODE>; it
will usually delegate this to <CODE>SLAVECLASS::new(TIEARGS...)</CODE>, resulting
in a new instance of SLAVECLASS being created and returned.
<P><LI>
<P>Once both master and slave have been created, the master is returned
to the caller.
</OL>
<P><HR>
<A NAME="How_I_O_operators_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How I/O operators work (on the master)</H3></A>
<P>Consider using an i/o operator on the master:
<FONT SIZE=3 FACE="courier"><PRE>
print $WT "Hello, world!\n";
</PRE></FONT>
<P>Since the master ($WT) is really a [blessed] reference to a glob,
the normal Perl i/o operators like <CODE>print</CODE> may be used on it.
They will just operate on the symbol part of the glob.
<P>Since the glob is tied to the slave, the slave's PRINT method
(part of the TIEHANDLE interface) will be automatically invoked.
<P>If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be
invoked, and that method happens to delegate to the <CODE>print()</CODE> method
of the same class. So the <I>real</I> work is ultimately done by
IO::Scalar::print().
<P><HR>
<A NAME="How_methods_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How methods work (on the master)</H3></A>
<P>Consider using a method on the master:
<FONT SIZE=3 FACE="courier"><PRE>
$WT->print("Hello, world!\n");
</PRE></FONT>
<P>Since the master ($WT) is blessed into the class IO::WrapTie::Master,
Perl first attempts to find a <CODE>print()</CODE> method there. Failing that,
Perl next attempts to find a <CODE>print()</CODE> method in the superclass,
IO::Handle. It just so happens that there <I>is</I> such a method;
that method merely invokes the <CODE>print</CODE> i/o operator on the self object...
and for that, see above!
<P>But let's suppose we're dealing with a method which <I>isn't</I> part
of IO::Handle... for example:
<FONT SIZE=3 FACE="courier"><PRE>
my $sref = $WT->sref;
</PRE></FONT>
<P>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 AUTOLOAD method which performs the delegation.
<P>So: when <CODE>sref()</CODE> can't be found in IO::Handle, the AUTOLOAD 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.
<P>Sometimes, to get this to work properly, you may need to create
a subclass of IO::WrapTie::Master which is an effective master for
<I>your</I> class, and do the delegation there.
<P><HR>
<A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A>
<P><B>Why not simply use the object's OO interface?</B>
Because that means forsaking the use of named operators
like print(), and you may need to pass the object to a subroutine
which will attempt to use those operators:
<FONT SIZE=3 FACE="courier"><PRE>
$O = FooHandle->new(&FOO_RDWR, 2);
$O->print("Hello, world\n"); ### OO syntax is okay, BUT....
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
sub nope { print $_[0] "Nope!\n" }
X nope($O); ### ERROR!!! (not a glob ref)
</PRE></FONT>
<P><B>Why not simply use tie()?</B>
Because (1) you have to use tied() 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:
<FONT SIZE=3 FACE="courier"><PRE>
tie *T, 'FooHandle', &FOO_RDWR, 2;
print T "Hello, world\n"; ### Operator is okay, BUT...
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
tied(*T)->other_stuff; ### yuck! AND...
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
sub nope { shift->print("Nope!\n") }
X nope(\*T); ### ERROR!!! (method "print" on unblessed ref)
</PRE></FONT>
<P><B>Why a master and slave?
Why not simply write FooHandle to inherit from IO::Handle?</B>
I tried this, with an implementation similar to that of IO::Socket.
The problem is that <I>the whole point is to use this with objects
that don't have an underlying file/socket descriptor.</I>.
Subclassing IO::Handle will work fine for the OO stuff, and fine with
named operators <I>if</I> you tie()... but if you just attempt to say:
<FONT SIZE=3 FACE="courier"><PRE>
$IO = FooHandle->new(&FOO_RDWR, 2);
print $IO "Hello!\n";
</PRE></FONT>
<P>you get a warning from Perl like:
<FONT SIZE=3 FACE="courier"><PRE>
Filehandle GEN001 never opened
</PRE></FONT>
<P>because it's trying to do system-level i/o on an (unopened) file
descriptor. To avoid this, you apparently have to tie() the handle...
which brings us right back to where we started! At least the
IO::WrapTie mixin lets us say:
<FONT SIZE=3 FACE="courier"><PRE>
$IO = FooHandle->new_tie(&FOO_RDWR, 2);
print $IO "Hello!\n";
</PRE></FONT>
<P>and so is not <I>too</I> bad. <CODE>:-)</CODE>
<P><HR>
<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>
<P>Remember: this stuff is for doing FileHandle-like i/o on things
<I>without underlying file descriptors</I>. If you have an underlying
file descriptor, you're better off just inheriting from IO::Handle.
<P><B>Be aware that new_tie() always returns an instance of a
kind of IO::WrapTie::Master...</B> it does <B>not</B> return an instance
of the i/o class you're tying to!
<P>Invoking some methods on the master object causes AUTOLOAD to delegate
them to the slave object... so it <I>looks</I> like you're manipulating a
"FooHandle" object directly, but you're not.
<P>I have not explored all the ramifications of this use of tie().
<I>Here there be dragons</I>.
<P><HR>
<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>
<P>$Id: WrapTie.pm,v 2.102 2001/08/17 02:06:33 eryq Exp $
<P><HR>
<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>
<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).
<P><HR>
<ADDRESS><FONT SIZE=-1>
Generated Sun Dec 21 13:54:38 2003 by cvu_pod2html
</FONT></ADDRESS>
</FONT></BODY>
</HTML>
|