1IO::WrapTie(3) User Contributed Perl Documentation IO::WrapTie(3)
2
6 IO::WrapTie - wrap tieable objects in IO::Handle interface
7 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 require 5.004;
15 Function interface (experimental). Use this with any existing class...
17 use IO::WrapTie;
19 use FooHandle; ### implements TIEHANDLE interface
20 ### Suppose we want a "FooHandle->new(&FOO_RDWR, 2)".
22 ### We can instead say...
23 $FH = wraptie('FooHandle', &FOO_RDWR, 2);
25 ### Now we can use...
27 print $FH "Hello, "; ### traditional operator syntax...
28 $FH->print("world!\n"); ### ...and OO syntax as well!
29 OO interface (preferred). You can inherit from the IO::WrapTie::Slave
31 mixin to get a nifty "new_tie()" constructor...
32 #------------------------------
34 package FooHandle; ### a class which can TIEHANDLE
35 use IO::WrapTie;
37 @ISA = qw(IO::WrapTie::Slave); ### inherit new_tie()
38 ...
39 #------------------------------
42 package main;
43 $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 See IO::Scalar as an example. It also shows you how to create classes
49 which work both with and without 5.004.
50
52 Suppose you have a class "FooHandle", where...
53 · 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 · FooHandle implements the TIEHANDLE interface (see perltie); that
60 is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, READ, and
61 READLINE.
62 · 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 Normally, users of your class would have two options:
68 · Use only OO syntax, and forsake named I/O operators like 'print'.
70 · 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 But now with IO::WrapTie, you can say:
77 $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 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 $WT = FooHandle->new_tie(&FOO_RDWR, 2);
87 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
92 The data structures
93 Consider this example code, using classes in this distribution:
94 use IO::Scalar;
96 use IO::WrapTie;
97 $WT = wraptie('IO::Scalar',\$s);
99 print $WT "Hello, ";
100 $WT->print("world!\n");
101 In it, the wraptie() function creates a data structure as follows:
103 * $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 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 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 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 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 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 5. Once both master and slave have been created, the master is
155 returned to the caller.
156 How I/O operators work (on the master)
158 Consider using an i/o operator on the master:
159 print $WT "Hello, world!\n";
161 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 Since the glob is tied to the slave, the slave's PRINT method (part of
167 the TIEHANDLE interface) will be automatically invoked.
168 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 How methods work (on the master)
175 Consider using a method on the master:
176 $WT->print("Hello, world!\n");
178 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 But let's suppose we're dealing with a method which isn't part of
187 IO::Handle... for example:
188 my $sref = $WT->sref;
190 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 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 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
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 $O = FooHandle->new(&FOO_RDWR, 2);
211 $O->print("Hello, world\n"); ### OO syntax is okay, BUT....
212 sub nope { print $_[0] "Nope!\n" }
214 X nope($O); ### ERROR!!! (not a glob ref)
215 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 tie *T, 'FooHandle', &FOO_RDWR, 2;
223 print T "Hello, world\n"; ### Operator is okay, BUT...
224 tied(*T)->other_stuff; ### yuck! AND...
226 sub nope { shift->print("Nope!\n") }
228 X nope(\*T); ### ERROR!!! (method "print" on unblessed ref)
229 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 $IO = FooHandle->new(&FOO_RDWR, 2);
239 print $IO "Hello!\n";
240 you get a warning from Perl like:
242 Filehandle GEN001 never opened
244 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 $IO = FooHandle->new_tie(&FOO_RDWR, 2);
251 print $IO "Hello!\n";
252 and so is not too bad. ":-)"
254
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 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 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 I have not explored all the ramifications of this use of tie(). Here
269 there be dragons.
270
272 $Id: WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $
273
275 Primary Maintainer
276 Dianne Skoll (dfs@roaringpenguin.com).
277 Original Author
279 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
280 (http://www.zeegee.com).
281
283 Hey! The above document had some coding errors, which are explained
284 below:
285 Around line 481:
287 '=item' outside of any '=over'
288 =over without closing =back
290perl v5.28.0 2015-04-22 IO::WrapTie(3)