1IO::WrapTie(3) User Contributed Perl Documentation IO::WrapTie(3)
2
3
4
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
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 package main;
42
43 $FH = FooHandle->new_tie(&FOO_RDWR, 2); ### $FH is an IO::WrapTie::Master
44 print $FH "Hello, "; ### traditional operator syntax
45 $FH->print("world!\n"); ### OO syntax
46
47 See IO::Scalar as an example. It also shows you how to create classes
48 which work both with and without 5.004.
49
51 Suppose you have a class "FooHandle", where...
52
53 · FooHandle does not inherit from IO::Handle; that is, it performs
54 filehandle-like I/O, but to something other than an underlying file
55 descriptor. Good examples are IO::Scalar (for printing to a
56 string) and IO::Lines (for printing to an array of lines).
57
58 · FooHandle implements the TIEHANDLE interface (see perltie); that
59 is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, READ, and
60 READLINE.
61
62 · FooHandle implements the traditional OO interface of FileHandle and
63 IO::Handle; i.e., it contains methods like getline(), read(),
64 print(), seek(), tell(), eof(), etc.
65
66 Normally, users of your class would have two options:
67
68 · Use only OO syntax, and forsake named I/O operators like 'print'.
69
70 · Use with tie, and forsake treating it as a first-class object
71 (i.e., class-specific methods can only be invoked through the
72 underlying object via tied()... giving the object a "split person‐
73 ality").
74
75 But now with IO::WrapTie, you can say:
76
77 $WT = wraptie('FooHandle', &FOO_RDWR, 2);
78 $WT->print("Hello, world\n"); ### OO syntax
79 print $WT "Yes!\n"; ### Named operator syntax too!
80 $WT->weird_stuff; ### Other methods!
81
82 And if you're authoring a class like FooHandle, just have it inherit
83 from "IO::WrapTie::Slave" and that first line becomes even prettier:
84
85 $WT = FooHandle->new_tie(&FOO_RDWR, 2);
86
87 The bottom line: now, almost any class can look and work exactly like
88 an IO::Handle... and be used both with OO and non-OO filehandle syntax.
89
91 The data structures
92
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
136 1. The call to function "wraptie(SLAVECLASS, TIEARGS...)" is passed
137 onto "IO::WrapTie::Master::new()". Note that class IO::Wrap‐
138 Tie::Master is a subclass of IO::Handle.
139
140 2. The "IO::WrapTie::Master::new" method creates a new IO::Handle
141 object, reblessed into class IO::WrapTie::Master. This object is
142 the master, which will be returned from the constructor. At the
143 same time...
144
145 3. The "new" method also creates the slave: this is an instance of
146 SLAVECLASS which is created by tying the master's IO::Handle to
147 SLAVECLASS via "tie(HANDLE, SLAVECLASS, TIEARGS...)". This call to
148 "tie()" creates the slave in the following manner:
149
150 4. Class SLAVECLASS is sent the message "TIEHANDLE(TIEARGS...)"; it
151 will usually delegate this to "SLAVECLASS::new(TIEARGS...)",
152 resulting in a new instance of SLAVECLASS being created and
153 returned.
154
155 5. Once both master and slave have been created, the master is
156 returned to the caller.
157
158 How I/O operators work (on the master)
159
160 Consider using an i/o operator on the master:
161
162 print $WT "Hello, world!\n";
163
164 Since the master ($WT) is really a [blessed] reference to a glob, the
165 normal Perl i/o operators like "print" may be used on it. They will
166 just operate on the symbol part of the glob.
167
168 Since the glob is tied to the slave, the slave's PRINT method (part of
169 the TIEHANDLE interface) will be automatically invoked.
170
171 If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be
172 invoked, and that method happens to delegate to the "print()" method of
173 the same class. So the real work is ultimately done by
174 IO::Scalar::print().
175
176 How methods work (on the master)
177
178 Consider using a method on the master:
179
180 $WT->print("Hello, world!\n");
181
182 Since the master ($WT) is blessed into the class IO::WrapTie::Master,
183 Perl first attempts to find a "print()" method there. Failing that,
184 Perl next attempts to find a "print()" method in the superclass,
185 IO::Handle. It just so happens that there is such a method; that
186 method merely invokes the "print" i/o operator on the self object...
187 and for that, see above!
188
189 But let's suppose we're dealing with a method which isn't part of
190 IO::Handle... for example:
191
192 my $sref = $WT->sref;
193
194 In this case, the intuitive behavior is to have the master delegate the
195 method invocation to the slave (now do you see where the designations
196 come from?). This is indeed what happens: IO::WrapTie::Master contains
197 an AUTOLOAD method which performs the delegation.
198
199 So: when "sref()" can't be found in IO::Handle, the AUTOLOAD method of
200 IO::WrapTie::Master is invoked, and the standard behavior of delegating
201 the method to the underlying slave (here, an IO::Scalar) is done.
202
203 Sometimes, to get this to work properly, you may need to create a sub‐
204 class of IO::WrapTie::Master which is an effective master for your
205 class, and do the delegation there.
206
208 Why not simply use the object's OO interface?
209 Because that means forsaking the use of named operators like
210 print(), and you may need to pass the object to a subroutine which will
211 attempt to use those operators:
212
213 $O = FooHandle->new(&FOO_RDWR, 2);
214 $O->print("Hello, world\n"); ### OO syntax is okay, BUT....
215
216 sub nope { print $_[0] "Nope!\n" }
217 X nope($O); ### ERROR!!! (not a glob ref)
218
219 Why not simply use tie()?
220 Because (1) you have to use tied() to invoke methods in the
221 object's public interface (yuck), and (2) you may need to pass the tied
222 symbol to another subroutine which will attempt to treat it in an
223 OO-way... and that will break it:
224
225 tie *T, 'FooHandle', &FOO_RDWR, 2;
226 print T "Hello, world\n"; ### Operator is okay, BUT...
227
228 tied(*T)->other_stuff; ### yuck! AND...
229
230 sub nope { shift->print("Nope!\n") }
231 X nope(\*T); ### ERROR!!! (method "print" on unblessed ref)
232
233 Why a master and slave?
234 Why not simply write FooHandle to inherit from IO::Handle?
235 I tried this, with an implementation similar to that of IO::Socket.
236 The problem is that the whole point is to use this with objects that
237 don't have an underlying file/socket descriptor.. Subclassing IO::Han‐
238 dle will work fine for the OO stuff, and fine with named operators if
239 you tie()... but if you just attempt to say:
240
241 $IO = FooHandle->new(&FOO_RDWR, 2);
242 print $IO "Hello!\n";
243
244 you get a warning from Perl like:
245
246 Filehandle GEN001 never opened
247
248 because it's trying to do system-level i/o on an (unopened) file
249 descriptor. To avoid this, you apparently have to tie() the handle...
250 which brings us right back to where we started! At least the IO::Wrap‐
251 Tie mixin lets us say:
252
253 $IO = FooHandle->new_tie(&FOO_RDWR, 2);
254 print $IO "Hello!\n";
255
256 and so is not too bad. ":-)"
257
259 Remember: this stuff is for doing FileHandle-like i/o on things without
260 underlying file descriptors. If you have an underlying file descrip‐
261 tor, you're better off just inheriting from IO::Handle.
262
263 Be aware that new_tie() always returns an instance of a kind of
264 IO::WrapTie::Master... it does not return an instance of the i/o class
265 you're tying to!
266
267 Invoking some methods on the master object causes AUTOLOAD to delegate
268 them to the slave object... so it looks like you're manipulating a
269 "FooHandle" object directly, but you're not.
270
271 I have not explored all the ramifications of this use of tie(). Here
272 there be dragons.
273
275 $Id: WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $
276
278Primary Maintainer
279David F. Skoll (dfs@roaringpenguin.com).
280
281Original Author
282Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
283(http://www.zeegee.com).
284
285
286
287perl v5.8.8 2005-02-10 IO::WrapTie(3)