1IO::WrapTie(3)        User Contributed Perl Documentation       IO::WrapTie(3)
2
3
4

NAME

6       IO::WrapTie - wrap tieable objects in IO::Handle interface
7
8       This is currently Alpha code, released for comments.
9         Please give me your feedback!
10

SYNOPSIS

12       First of all, you'll need tie(), so:
13
14          require 5.004;
15
16       Function interface (experimental).  Use this with any existing class...
17
18          use IO::WrapTie;
19          use FooHandle;                  ### implements TIEHANDLE interface
20
21          ### Suppose we want a "FooHandle->new(&FOO_RDWR, 2)".
22          ### We can instead say...
23
24          $FH = wraptie('FooHandle', &FOO_RDWR, 2);
25
26          ### Now we can use...
27          print $FH "Hello, ";            ### traditional operator syntax...
28          $FH->print("world!\n");         ### ...and OO syntax as well!
29
30       OO interface (preferred).  You can inherit from the IO::WrapTie::Slave
31       mixin to get a nifty "new_tie()" constructor...
32
33          #------------------------------
34          package FooHandle;                        ### a class which can TIEHANDLE
35
36          use IO::WrapTie;
37          @ISA = qw(IO::WrapTie::Slave);            ### inherit new_tie()
38          ...
39
40
41          #------------------------------
42          package main;
43
44          $FH = FooHandle->new_tie(&FOO_RDWR, 2);   ### $FH is an IO::WrapTie::Master
45          print $FH "Hello, ";                      ### traditional operator syntax
46          $FH->print("world!\n");                   ### OO syntax
47
48       See IO::Scalar as an example.  It also shows you how to create classes
49       which work both with and without 5.004.
50

DESCRIPTION

52       Suppose you have a class "FooHandle", where...
53
54       ·   FooHandle does not inherit from IO::Handle; that is, it performs
55           filehandle-like I/O, but to something other than an underlying file
56           descriptor.  Good examples are IO::Scalar (for printing to a
57           string) and IO::Lines (for printing to an array of lines).
58
59       ·   FooHandle implements the TIEHANDLE interface (see perltie); that
60           is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, READ, and
61           READLINE.
62
63       ·   FooHandle implements the traditional OO interface of FileHandle and
64           IO::Handle; i.e., it contains methods like getline(), read(),
65           print(), seek(), tell(), eof(), etc.
66
67       Normally, users of your class would have two options:
68
69       ·   Use only OO syntax, and forsake named I/O operators like 'print'.
70
71       ·   Use with tie, and forsake treating it as a first-class object
72           (i.e., class-specific methods can only be invoked through the
73           underlying object via tied()... giving the object a "split
74           personality").
75
76       But now with IO::WrapTie, you can say:
77
78           $WT = wraptie('FooHandle', &FOO_RDWR, 2);
79           $WT->print("Hello, world\n");   ### OO syntax
80           print $WT "Yes!\n";             ### Named operator syntax too!
81           $WT->weird_stuff;               ### Other methods!
82
83       And if you're authoring a class like FooHandle, just have it inherit
84       from "IO::WrapTie::Slave" and that first line becomes even prettier:
85
86           $WT = FooHandle->new_tie(&FOO_RDWR, 2);
87
88       The bottom line: now, almost any class can look and work exactly like
89       an IO::Handle... and be used both with OO and non-OO filehandle syntax.
90

HOW IT ALL WORKS

92   The data structures
93       Consider this example code, using classes in this distribution:
94
95           use IO::Scalar;
96           use IO::WrapTie;
97
98           $WT = wraptie('IO::Scalar',\$s);
99           print $WT "Hello, ";
100           $WT->print("world!\n");
101
102       In it, the wraptie() function creates a data structure as follows:
103
104                                 * $WT is a blessed reference to a tied filehandle
105                     $WT           glob; that glob is tied to the "Slave" object.
106                      |          * You would do all your i/o with $WT directly.
107                      |
108                      |
109                      |     ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle
110                      V    /
111               .-------------.
112               |             |
113               |             |   * Perl i/o operators work on the tied object,
114               |  "Master"   |     invoking the TIEHANDLE methods.
115               |             |   * Method invocations are delegated to the tied
116               |             |     slave.
117               `-------------'
118                      |
119           tied(*$WT) |     .---isa--> IO::WrapTie::Slave
120                      V    /
121               .-------------.
122               |             |
123               |   "Slave"   |   * Instance of FileHandle-like class which doesn't
124               |             |     actually use file descriptors, like IO::Scalar.
125               |  IO::Scalar |   * The slave can be any kind of object.
126               |             |   * Must implement the TIEHANDLE interface.
127               `-------------'
128
129       NOTE: just as an IO::Handle is really just a blessed reference to a
130       traditional filehandle glob... so also, an IO::WrapTie::Master is
131       really just a blessed reference to a filehandle glob which has been
132       tied to some "slave" class.
133
134   How wraptie() works
135       1.  The call to function "wraptie(SLAVECLASS, TIEARGS...)" is passed
136           onto "IO::WrapTie::Master::new()".  Note that class
137           IO::WrapTie::Master is a subclass of IO::Handle.
138
139       2.  The "IO::WrapTie::Master::new" method creates a new IO::Handle
140           object, reblessed into class IO::WrapTie::Master.  This object is
141           the master, which will be returned from the constructor.  At the
142           same time...
143
144       3.  The "new" method also creates the slave: this is an instance of
145           SLAVECLASS which is created by tying the master's IO::Handle to
146           SLAVECLASS via "tie(HANDLE, SLAVECLASS, TIEARGS...)".  This call to
147           "tie()" creates the slave in the following manner:
148
149       4.  Class SLAVECLASS is sent the message "TIEHANDLE(TIEARGS...)"; it
150           will usually delegate this to "SLAVECLASS::new(TIEARGS...)",
151           resulting in a new instance of SLAVECLASS being created and
152           returned.
153
154       5.  Once both master and slave have been created, the master is
155           returned to the caller.
156
157   How I/O operators work (on the master)
158       Consider using an i/o operator on the master:
159
160           print $WT "Hello, world!\n";
161
162       Since the master ($WT) is really a [blessed] reference to a glob, the
163       normal Perl i/o operators like "print" may be used on it.  They will
164       just operate on the symbol part of the glob.
165
166       Since the glob is tied to the slave, the slave's PRINT method (part of
167       the TIEHANDLE interface) will be automatically invoked.
168
169       If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be
170       invoked, and that method happens to delegate to the "print()" method of
171       the same class.  So the real work is ultimately done by
172       IO::Scalar::print().
173
174   How methods work (on the master)
175       Consider using a method on the master:
176
177           $WT->print("Hello, world!\n");
178
179       Since the master ($WT) is blessed into the class IO::WrapTie::Master,
180       Perl first attempts to find a "print()" method there.  Failing that,
181       Perl next attempts to find a "print()" method in the superclass,
182       IO::Handle.  It just so happens that there is such a method; that
183       method merely invokes the "print" i/o operator on the self object...
184       and for that, see above!
185
186       But let's suppose we're dealing with a method which isn't part of
187       IO::Handle... for example:
188
189           my $sref = $WT->sref;
190
191       In this case, the intuitive behavior is to have the master delegate the
192       method invocation to the slave (now do you see where the designations
193       come from?).  This is indeed what happens: IO::WrapTie::Master contains
194       an AUTOLOAD method which performs the delegation.
195
196       So: when "sref()" can't be found in IO::Handle, the AUTOLOAD method of
197       IO::WrapTie::Master is invoked, and the standard behavior of delegating
198       the method to the underlying slave (here, an IO::Scalar) is done.
199
200       Sometimes, to get this to work properly, you may need to create a
201       subclass of IO::WrapTie::Master which is an effective master for your
202       class, and do the delegation there.
203

NOTES

205       Why not simply use the object's OO interface?
206           Because that means forsaking the use of named operators like
207       print(), and you may need to pass the object to a subroutine which will
208       attempt to use those operators:
209
210           $O = FooHandle->new(&FOO_RDWR, 2);
211           $O->print("Hello, world\n");  ### OO syntax is okay, BUT....
212
213           sub nope { print $_[0] "Nope!\n" }
214        X  nope($O);                     ### ERROR!!! (not a glob ref)
215
216       Why not simply use tie()?
217           Because (1) you have to use tied() to invoke methods in the
218       object's public interface (yuck), and (2) you may need to pass the tied
219       symbol to another subroutine which will attempt to treat it in an OO-
220       way... and that will break it:
221
222           tie *T, 'FooHandle', &FOO_RDWR, 2;
223           print T "Hello, world\n";   ### Operator is okay, BUT...
224
225           tied(*T)->other_stuff;      ### yuck! AND...
226
227           sub nope { shift->print("Nope!\n") }
228        X  nope(\*T);                  ### ERROR!!! (method "print" on unblessed ref)
229
230       Why a master and slave?
231         Why not simply write FooHandle to inherit from IO::Handle?
232           I tried this, with an implementation similar to that of IO::Socket.
233       The problem is that the whole point is to use this with objects that
234       don't have an underlying file/socket descriptor..  Subclassing
235       IO::Handle will work fine for the OO stuff, and fine with named
236       operators if you tie()... but if you just attempt to say:
237
238           $IO = FooHandle->new(&FOO_RDWR, 2);
239           print $IO "Hello!\n";
240
241       you get a warning from Perl like:
242
243           Filehandle GEN001 never opened
244
245       because it's trying to do system-level i/o on an (unopened) file
246       descriptor.  To avoid this, you apparently have to tie() the handle...
247       which brings us right back to where we started!  At least the
248       IO::WrapTie mixin lets us say:
249
250           $IO = FooHandle->new_tie(&FOO_RDWR, 2);
251           print $IO "Hello!\n";
252
253       and so is not too bad.  ":-)"
254

WARNINGS

256       Remember: this stuff is for doing FileHandle-like i/o on things without
257       underlying file descriptors.  If you have an underlying file
258       descriptor, you're better off just inheriting from IO::Handle.
259
260       Be aware that new_tie() always returns an instance of a kind of
261       IO::WrapTie::Master... it does not return an instance of the i/o class
262       you're tying to!
263
264       Invoking some methods on the master object causes AUTOLOAD to delegate
265       them to the slave object... so it looks like you're manipulating a
266       "FooHandle" object directly, but you're not.
267
268       I have not explored all the ramifications of this use of tie().  Here
269       there be dragons.
270

VERSION

272       $Id: WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $
273

AUTHOR

275       Primary Maintainer
276           Dianne Skoll (dfs@roaringpenguin.com).
277
278       Original Author
279           Eryq (eryq@zeegee.com).  President, ZeeGee Software Inc
280           (http://www.zeegee.com).
281

POD ERRORS

283       Hey! The above document had some coding errors, which are explained
284       below:
285
286       Around line 481:
287           '=item' outside of any '=over'
288
289           =over without closing =back
290
291
292
293perl v5.28.0                      2015-04-22                    IO::WrapTie(3)
Impressum