local-lib5/man/man3/IO::WrapTie.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "IO::WrapTie 3"
 132 .TH IO::WrapTie 3 "2005-02-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 IO::WrapTie \- wrap tieable objects in IO::Handle interface
 135 .PP
 136 \&\fIThis is currently Alpha code, released for comments.
 137   Please give me your feedback!\fR
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 First of all, you'll need \fItie()\fR, so:
 141 .PP
 142 .Vb 1
 143 \&   require 5.004;
 144 .Ve
 145 .PP
 146 \&\fIFunction interface (experimental).\fR
 147 Use this with any existing class...
 148 .PP
 149 .Vb 2
 150 \&   use IO::WrapTie;
 151 \&   use FooHandle;                  ### implements TIEHANDLE interface
 152 .Ve
 153 .PP
 154 .Vb 2
 155 \&   ### Suppose we want a "FooHandle\->new(&FOO_RDWR, 2)".
 156 \&   ### We can instead say...
 157 .Ve
 158 .PP
 159 .Vb 1
 160 \&   $FH = wraptie('FooHandle', &FOO_RDWR, 2);
 161 .Ve
 162 .PP
 163 .Vb 3
 164 \&   ### Now we can use...
 165 \&   print $FH "Hello, ";            ### traditional operator syntax...
 166 \&   $FH\->print("world!\en");         ### ...and OO syntax as well!
 167 .Ve
 168 .PP
 169 \&\fI\s-1OO\s0 interface (preferred).\fR
 170 You can inherit from the IO::WrapTie::Slave mixin to get a
 171 nifty \f(CW\*(C`new_tie()\*(C'\fR constructor...
 172 .PP
 173 .Vb 2
 174 \&   #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 175 \&   package FooHandle;                        ### a class which can TIEHANDLE
 176 .Ve
 177 .PP
 178 .Vb 3
 179 \&   use IO::WrapTie;
 180 \&   @ISA = qw(IO::WrapTie::Slave);            ### inherit new_tie()
 181 \&   ...
 182 .Ve
 183 .PP
 184 .Vb 2
 185 \&   #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 186 \&   package main;
 187 .Ve
 188 .PP
 189 .Vb 3
 190 \&   $FH = FooHandle\->new_tie(&FOO_RDWR, 2);   ### $FH is an IO::WrapTie::Master
 191 \&   print $FH "Hello, ";                      ### traditional operator syntax
 192 \&   $FH\->print("world!\en");                   ### OO syntax
 193 .Ve
 194 .PP
 195 See IO::Scalar as an example.  It also shows you how to create classes
 196 which work both with and without 5.004.
 197 .SH "DESCRIPTION"
 198 .IX Header "DESCRIPTION"
 199 Suppose you have a class \f(CW\*(C`FooHandle\*(C'\fR, where...
 200 .IP "\(bu" 4
 201 \&\fBFooHandle does not inherit from IO::Handle;\fR that is, it performs
 202 filehandle-like I/O, but to something other than an underlying
 203 file descriptor.  Good examples are IO::Scalar (for printing to a
 204 string) and IO::Lines (for printing to an array of lines).
 205 .IP "\(bu" 4
 206 \&\fBFooHandle implements the \s-1TIEHANDLE\s0 interface\fR (see perltie);
 207 that is, it provides methods \s-1TIEHANDLE\s0, \s-1GETC\s0, \s-1PRINT\s0, \s-1PRINTF\s0,
 208 \&\s-1READ\s0, and \s-1READLINE\s0.
 209 .IP "\(bu" 4
 210 \&\fBFooHandle implements the traditional \s-1OO\s0 interface\fR of
 211 FileHandle and IO::Handle; i.e., it contains methods like \fIgetline()\fR,
 212 \&\fIread()\fR, \fIprint()\fR, \fIseek()\fR, \fItell()\fR, \fIeof()\fR, etc.
 213 .PP
 214 Normally, users of your class would have two options:
 215 .IP "\(bu" 4
 216 \&\fBUse only \s-1OO\s0 syntax,\fR and forsake named I/O operators like 'print'.
 217 .IP "\(bu" 4
 218 \&\fBUse with tie,\fR and forsake treating it as a first-class object
 219 (i.e., class-specific methods can only be invoked through the underlying
 220 object via \fItied()\fR... giving the object a \*(L"split personality\*(R").
 221 .PP
 222 But now with IO::WrapTie, you can say:
 223 .PP
 224 .Vb 4
 225 \&    $WT = wraptie('FooHandle', &FOO_RDWR, 2);
 226 \&    $WT\->print("Hello, world\en");   ### OO syntax
 227 \&    print $WT "Yes!\en";             ### Named operator syntax too!
 228 \&    $WT\->weird_stuff;               ### Other methods!
 229 .Ve
 230 .PP
 231 And if you're authoring a class like FooHandle, just have it inherit
 232 from \f(CW\*(C`IO::WrapTie::Slave\*(C'\fR and that first line becomes even prettier:
 233 .PP
 234 .Vb 1
 235 \&    $WT = FooHandle\->new_tie(&FOO_RDWR, 2);
 236 .Ve
 237 .PP
 238 \&\fBThe bottom line:\fR now, almost any class can look and work exactly like
 239 an IO::Handle... and be used both with \s-1OO\s0 and non-OO filehandle syntax.
 240 .SH "HOW IT ALL WORKS"
 241 .IX Header "HOW IT ALL WORKS"
 242 .Sh "The data structures"
 243 .IX Subsection "The data structures"
 244 Consider this example code, using classes in this distribution:
 245 .PP
 246 .Vb 2
 247 \&    use IO::Scalar;
 248 \&    use IO::WrapTie;
 249 .Ve
 250 .PP
 251 .Vb 3
 252 \&    $WT = wraptie('IO::Scalar',\e$s);
 253 \&    print $WT "Hello, ";
 254 \&    $WT\->print("world!\en");
 255 .Ve
 256 .PP
 257 In it, the \fIwraptie()\fR function creates a data structure as follows:
 258 .PP
 259 .Vb 24
 260 \&                          * $WT is a blessed reference to a tied filehandle
 261 \&              $WT           glob; that glob is tied to the "Slave" object.
 262 \&               |          * You would do all your i/o with $WT directly.
 263 \&               |
 264 \&               |
 265 \&               |     ,\-\-\-isa\-\-> IO::WrapTie::Master >\-\-isa\-\-> IO::Handle
 266 \&               V    /
 267 \&        .\-\-\-\-\-\-\-\-\-\-\-\-\-.
 268 \&        |             |
 269 \&        |             |   * Perl i/o operators work on the tied object,
 270 \&        |  "Master"   |     invoking the TIEHANDLE methods.
 271 \&        |             |   * Method invocations are delegated to the tied
 272 \&        |             |     slave.
 273 \&        `\-\-\-\-\-\-\-\-\-\-\-\-\-'
 274 \&               |
 275 \&    tied(*$WT) |     .\-\-\-isa\-\-> IO::WrapTie::Slave
 276 \&               V    /
 277 \&        .\-\-\-\-\-\-\-\-\-\-\-\-\-.
 278 \&        |             |
 279 \&        |   "Slave"   |   * Instance of FileHandle\-like class which doesn't
 280 \&        |             |     actually use file descriptors, like IO::Scalar.
 281 \&        |  IO::Scalar |   * The slave can be any kind of object.
 282 \&        |             |   * Must implement the TIEHANDLE interface.
 283 \&        `\-\-\-\-\-\-\-\-\-\-\-\-\-'
 284 .Ve
 285 .PP
 286 \&\fI\s-1NOTE:\s0\fR just as an IO::Handle is really just a blessed reference to a
 287 \&\fItraditional\fR filehandle glob... so also, an IO::WrapTie::Master
 288 is really just a blessed reference to a filehandle
 289 glob \fIwhich has been tied to some \*(L"slave\*(R" class.\fR
 290 .Sh "How \fIwraptie()\fP works"
 291 .IX Subsection "How wraptie() works"
 292 .IP "1." 4
 293 The call to function \f(CW\*(C`wraptie(SLAVECLASS, TIEARGS...)\*(C'\fR is
 294 passed onto \f(CW\*(C`IO::WrapTie::Master::new()\*(C'\fR.
 295 Note that class IO::WrapTie::Master is a subclass of IO::Handle.
 296 .IP "2." 4
 297 The \f(CW\*(C`IO::WrapTie::Master::new\*(C'\fR method creates a new IO::Handle object,
 298 reblessed into class IO::WrapTie::Master.  This object is the \fImaster\fR,
 299 which will be returned from the constructor.  At the same time...
 300 .IP "3." 4
 301 The \f(CW\*(C`new\*(C'\fR method also creates the \fIslave\fR: this is an instance
 302 of \s-1SLAVECLASS\s0 which is created by tying the master's IO::Handle
 303 to \s-1SLAVECLASS\s0 via \f(CW\*(C`tie(HANDLE, SLAVECLASS, TIEARGS...)\*(C'\fR.
 304 This call to \f(CW\*(C`tie()\*(C'\fR creates the slave in the following manner:
 305 .IP "4." 4
 306 Class \s-1SLAVECLASS\s0 is sent the message \f(CW\*(C`TIEHANDLE(TIEARGS...)\*(C'\fR; it
 307 will usually delegate this to \f(CW\*(C`SLAVECLASS::new(TIEARGS...)\*(C'\fR, resulting
 308 in a new instance of \s-1SLAVECLASS\s0 being created and returned.
 309 .IP "5." 4
 310 Once both master and slave have been created, the master is returned
 311 to the caller.
 312 .Sh "How I/O operators work (on the master)"
 313 .IX Subsection "How I/O operators work (on the master)"
 314 Consider using an i/o operator on the master:
 315 .PP
 316 .Vb 1
 317 \&    print $WT "Hello, world!\en";
 318 .Ve
 319 .PP
 320 Since the master ($WT) is really a [blessed] reference to a glob,
 321 the normal Perl i/o operators like \f(CW\*(C`print\*(C'\fR may be used on it.
 322 They will just operate on the symbol part of the glob.
 323 .PP
 324 Since the glob is tied to the slave, the slave's \s-1PRINT\s0 method
 325 (part of the \s-1TIEHANDLE\s0 interface) will be automatically invoked.
 326 .PP
 327 If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be
 328 invoked, and that method happens to delegate to the \f(CW\*(C`print()\*(C'\fR method
 329 of the same class.  So the \fIreal\fR work is ultimately done by
 330 \&\fIIO::Scalar::print()\fR.
 331 .Sh "How methods work (on the master)"
 332 .IX Subsection "How methods work (on the master)"
 333 Consider using a method on the master:
 334 .PP
 335 .Vb 1
 336 \&    $WT\->print("Hello, world!\en");
 337 .Ve
 338 .PP
 339 Since the master ($WT) is blessed into the class IO::WrapTie::Master,
 340 Perl first attempts to find a \f(CW\*(C`print()\*(C'\fR method there.  Failing that,
 341 Perl next attempts to find a \f(CW\*(C`print()\*(C'\fR method in the superclass,
 342 IO::Handle.  It just so happens that there \fIis\fR such a method;
 343 that method merely invokes the \f(CW\*(C`print\*(C'\fR i/o operator on the self object...
 344 and for that, see above!
 345 .PP
 346 But let's suppose we're dealing with a method which \fIisn't\fR part
 347 of IO::Handle... for example:
 348 .PP
 349 .Vb 1
 350 \&    my $sref = $WT\->sref;
 351 .Ve
 352 .PP
 353 In this case, the intuitive behavior is to have the master delegate the
 354 method invocation to the slave (now do you see where the designations
 355 come from?).  This is indeed what happens: IO::WrapTie::Master contains
 356 an \s-1AUTOLOAD\s0 method which performs the delegation.
 357 .PP
 358 So: when \f(CW\*(C`sref()\*(C'\fR can't be found in IO::Handle, the \s-1AUTOLOAD\s0 method
 359 of IO::WrapTie::Master is invoked, and the standard behavior of
 360 delegating the method to the underlying slave (here, an IO::Scalar)
 361 is done.
 362 .PP
 363 Sometimes, to get this to work properly, you may need to create
 364 a subclass of IO::WrapTie::Master which is an effective master for
 365 \&\fIyour\fR class, and do the delegation there.
 366 .SH "NOTES"
 367 .IX Header "NOTES"
 368 \&\fBWhy not simply use the object's \s-1OO\s0 interface?\fR
 369     Because that means forsaking the use of named operators
 370 like \fIprint()\fR, and you may need to pass the object to a subroutine
 371 which will attempt to use those operators:
 372 .PP
 373 .Vb 2
 374 \&    $O = FooHandle\->new(&FOO_RDWR, 2);
 375 \&    $O\->print("Hello, world\en");  ### OO syntax is okay, BUT....
 376 .Ve
 377 .PP
 378 .Vb 2
 379 \&    sub nope { print $_[0] "Nope!\en" }
 380 \& X  nope($O);                     ### ERROR!!! (not a glob ref)
 381 .Ve
 382 .PP
 383 \&\fBWhy not simply use \f(BItie()\fB?\fR
 384     Because (1) you have to use \fItied()\fR to invoke methods in the
 385 object's public interface (yuck), and (2) you may need to pass
 386 the tied symbol to another subroutine which will attempt to treat
 387 it in an OO\-way... and that will break it:
 388 .PP
 389 .Vb 2
 390 \&    tie *T, 'FooHandle', &FOO_RDWR, 2;
 391 \&    print T "Hello, world\en";   ### Operator is okay, BUT...
 392 .Ve
 393 .PP
 394 .Vb 1
 395 \&    tied(*T)\->other_stuff;      ### yuck! AND...
 396 .Ve
 397 .PP
 398 .Vb 2
 399 \&    sub nope { shift\->print("Nope!\en") }
 400 \& X  nope(\e*T);                  ### ERROR!!! (method "print" on unblessed ref)
 401 .Ve
 402 .PP
 403 \&\fBWhy a master and slave?
 404   Why not simply write FooHandle to inherit from IO::Handle?\fR
 405     I tried this, with an implementation similar to that of IO::Socket.
 406 The problem is that \fIthe whole point is to use this with objects
 407 that don't have an underlying file/socket descriptor.\fR.
 408 Subclassing IO::Handle will work fine for the \s-1OO\s0 stuff, and fine with
 409 named operators \fIif\fR you \fItie()\fR... but if you just attempt to say:
 410 .PP
 411 .Vb 2
 412 \&    $IO = FooHandle\->new(&FOO_RDWR, 2);
 413 \&    print $IO "Hello!\en";
 414 .Ve
 415 .PP
 416 you get a warning from Perl like:
 417 .PP
 418 .Vb 1
 419 \&    Filehandle GEN001 never opened
 420 .Ve
 421 .PP
 422 because it's trying to do system-level i/o on an (unopened) file
 423 descriptor.  To avoid this, you apparently have to \fItie()\fR the handle...
 424 which brings us right back to where we started!  At least the
 425 IO::WrapTie mixin lets us say:
 426 .PP
 427 .Vb 2
 428 \&    $IO = FooHandle\->new_tie(&FOO_RDWR, 2);
 429 \&    print $IO "Hello!\en";
 430 .Ve
 431 .PP
 432 and so is not \fItoo\fR bad.  \f(CW\*(C`:\-)\*(C'\fR
 433 .SH "WARNINGS"
 434 .IX Header "WARNINGS"
 435 Remember: this stuff is for doing FileHandle-like i/o on things
 436 \&\fIwithout underlying file descriptors\fR.  If you have an underlying
 437 file descriptor, you're better off just inheriting from IO::Handle.
 438 .PP
 439 \&\fBBe aware that \f(BInew_tie()\fB always returns an instance of a
 440 kind of IO::WrapTie::Master...\fR it does \fBnot\fR return an instance
 441 of the i/o class you're tying to!
 442 .PP
 443 Invoking some methods on the master object causes \s-1AUTOLOAD\s0 to delegate
 444 them to the slave object... so it \fIlooks\fR like you're manipulating a
 445 \&\*(L"FooHandle\*(R" object directly, but you're not.
 446 .PP
 447 I have not explored all the ramifications of this use of \fItie()\fR.
 448 \&\fIHere there be dragons\fR.
 449 .SH "VERSION"
 450 .IX Header "VERSION"
 451 $Id: WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $
 452 .SH "AUTHOR"
 453 .IX Header "AUTHOR"
 454 .RE
 455 .IP "Primary Maintainer"
 456 .IX Item "Primary Maintainer"
 457 David F. Skoll (\fIdfs@roaringpenguin.com\fR).
 458 .RE
 459 .IP "Original Author"
 460 .IX Item "Original Author"
 461 Eryq (\fIeryq@zeegee.com\fR).
 462 President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).