{ "content": [ { "type": "text", "text": "# IO::WrapTie (info)\n\n## NAME\n\nIO::WrapTie - wrap tieable objects in IO::Handle interface This is currently Alpha code, released for comments. Please give me your feedback!\n\n## SYNOPSIS\n\nFirst of all, you'll need tie(), so:\nrequire 5.004;\nFunction interface (experimental). Use this with any existing class...\nuse IO::WrapTie;\nuse FooHandle; ### implements TIEHANDLE interface\n### Suppose we want a \"FooHandle->new(&FOORDWR, 2)\".\n### We can instead say...\n$FH = wraptie('FooHandle', &FOORDWR, 2);\n### Now we can use...\nprint $FH \"Hello, \"; ### traditional operator syntax...\n$FH->print(\"world!\\n\"); ### ...and OO syntax as well!\nOO interface (preferred). You can inherit from the IO::WrapTie::Slave\nmixin to get a nifty \"newtie()\" constructor...\n#------------------------------\npackage FooHandle; ### a class which can TIEHANDLE\nuse IO::WrapTie;\n@ISA = qw(IO::WrapTie::Slave); ### inherit newtie()\n...\n#------------------------------\npackage main;\n$FH = FooHandle->newtie(&FOORDWR, 2); ### $FH is an IO::WrapTie::Master\nprint $FH \"Hello, \"; ### traditional operator syntax\n$FH->print(\"world!\\n\"); ### OO syntax\nSee IO::Scalar as an example. It also shows you how to create classes\nwhich work both with and without 5.004.\n\n## DESCRIPTION\n\nSuppose you have a class \"FooHandle\", where...\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **HOW IT ALL WORKS**\n- **NOTES**\n- **WARNINGS**\n- **VERSION**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "IO::WrapTie", "section": "", "mode": "info", "summary": "IO::WrapTie - wrap tieable objects in IO::Handle interface This is currently Alpha code, released for comments. Please give me your feedback!", "synopsis": "First of all, you'll need tie(), so:\nrequire 5.004;\nFunction interface (experimental). Use this with any existing class...\nuse IO::WrapTie;\nuse FooHandle; ### implements TIEHANDLE interface\n### Suppose we want a \"FooHandle->new(&FOORDWR, 2)\".\n### We can instead say...\n$FH = wraptie('FooHandle', &FOORDWR, 2);\n### Now we can use...\nprint $FH \"Hello, \"; ### traditional operator syntax...\n$FH->print(\"world!\\n\"); ### ...and OO syntax as well!\nOO interface (preferred). You can inherit from the IO::WrapTie::Slave\nmixin to get a nifty \"newtie()\" constructor...\n#------------------------------\npackage FooHandle; ### a class which can TIEHANDLE\nuse IO::WrapTie;\n@ISA = qw(IO::WrapTie::Slave); ### inherit newtie()\n...\n#------------------------------\npackage main;\n$FH = FooHandle->newtie(&FOORDWR, 2); ### $FH is an IO::WrapTie::Master\nprint $FH \"Hello, \"; ### traditional operator syntax\n$FH->print(\"world!\\n\"); ### OO syntax\nSee IO::Scalar as an example. It also shows you how to create classes\nwhich work both with and without 5.004.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 5, "subsections": [] }, { "name": "SYNOPSIS", "lines": 38, "subsections": [] }, { "name": "DESCRIPTION", "lines": 39, "subsections": [] }, { "name": "HOW IT ALL WORKS", "lines": 112, "subsections": [] }, { "name": "NOTES", "lines": 50, "subsections": [] }, { "name": "WARNINGS", "lines": 15, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "IO::WrapTie - wrap tieable objects in IO::Handle interface\n\nThis is currently Alpha code, released for comments.\nPlease give me your feedback!\n", "subsections": [] }, "SYNOPSIS": { "content": "First of all, you'll need tie(), so:\n\nrequire 5.004;\n\nFunction interface (experimental). Use this with any existing class...\n\nuse IO::WrapTie;\nuse FooHandle; ### implements TIEHANDLE interface\n\n### Suppose we want a \"FooHandle->new(&FOORDWR, 2)\".\n### We can instead say...\n\n$FH = wraptie('FooHandle', &FOORDWR, 2);\n\n### Now we can use...\nprint $FH \"Hello, \"; ### traditional operator syntax...\n$FH->print(\"world!\\n\"); ### ...and OO syntax as well!\n\nOO interface (preferred). You can inherit from the IO::WrapTie::Slave\nmixin to get a nifty \"newtie()\" constructor...\n\n#------------------------------\npackage FooHandle; ### a class which can TIEHANDLE\n\nuse IO::WrapTie;\n@ISA = qw(IO::WrapTie::Slave); ### inherit newtie()\n...\n\n#------------------------------\npackage main;\n\n$FH = FooHandle->newtie(&FOORDWR, 2); ### $FH is an IO::WrapTie::Master\nprint $FH \"Hello, \"; ### traditional operator syntax\n$FH->print(\"world!\\n\"); ### OO syntax\n\nSee IO::Scalar as an example. It also shows you how to create classes\nwhich work both with and without 5.004.\n", "subsections": [] }, "DESCRIPTION": { "content": "Suppose you have a class \"FooHandle\", where...\n\no FooHandle does not inherit from IO::Handle; that is, it performs\nfilehandle-like I/O, but to something other than an underlying file\ndescriptor. Good examples are IO::Scalar (for printing to a\nstring) and IO::Lines (for printing to an array of lines).\n\no FooHandle implements the TIEHANDLE interface (see perltie); that\nis, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, READ, and\nREADLINE.\n\no FooHandle implements the traditional OO interface of FileHandle and\nIO::Handle; i.e., it contains methods like getline(), read(),\nprint(), seek(), tell(), eof(), etc.\n\nNormally, users of your class would have two options:\n\no Use only OO syntax, and forsake named I/O operators like 'print'.\n\no Use with tie, and forsake treating it as a first-class object\n(i.e., class-specific methods can only be invoked through the\nunderlying object via tied()... giving the object a \"split\npersonality\").\n\nBut now with IO::WrapTie, you can say:\n\n$WT = wraptie('FooHandle', &FOORDWR, 2);\n$WT->print(\"Hello, world\\n\"); ### OO syntax\nprint $WT \"Yes!\\n\"; ### Named operator syntax too!\n$WT->weirdstuff; ### Other methods!\n\nAnd if you're authoring a class like FooHandle, just have it inherit\nfrom \"IO::WrapTie::Slave\" and that first line becomes even prettier:\n\n$WT = FooHandle->newtie(&FOORDWR, 2);\n\nThe bottom line: now, almost any class can look and work exactly like\nan IO::Handle... and be used both with OO and non-OO filehandle syntax.\n", "subsections": [] }, "HOW IT ALL WORKS": { "content": "The data structures\nConsider this example code, using classes in this distribution:\n\nuse IO::Scalar;\nuse IO::WrapTie;\n\n$WT = wraptie('IO::Scalar',\\$s);\nprint $WT \"Hello, \";\n$WT->print(\"world!\\n\");\n\nIn it, the wraptie() function creates a data structure as follows:\n\n* $WT is a blessed reference to a tied filehandle\n$WT glob; that glob is tied to the \"Slave\" object.\n| * You would do all your i/o with $WT directly.\n|\n|\n| ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle\nV /\n.-------------.\n| |\n| | * Perl i/o operators work on the tied object,\n| \"Master\" | invoking the TIEHANDLE methods.\n| | * Method invocations are delegated to the tied\n| | slave.\n`-------------'\n|\ntied(*$WT) | .---isa--> IO::WrapTie::Slave\nV /\n.-------------.\n| |\n| \"Slave\" | * Instance of FileHandle-like class which doesn't\n| | actually use file descriptors, like IO::Scalar.\n| IO::Scalar | * The slave can be any kind of object.\n| | * Must implement the TIEHANDLE interface.\n`-------------'\n\nNOTE: just as an IO::Handle is really just a blessed reference to a\ntraditional filehandle glob... so also, an IO::WrapTie::Master is\nreally just a blessed reference to a filehandle glob which has been\ntied to some \"slave\" class.\n\nHow wraptie() works\n1. The call to function \"wraptie(SLAVECLASS, TIEARGS...)\" is passed\nonto \"IO::WrapTie::Master::new()\". Note that class\nIO::WrapTie::Master is a subclass of IO::Handle.\n\n2. The \"IO::WrapTie::Master::new\" method creates a new IO::Handle\nobject, reblessed into class IO::WrapTie::Master. This object is\nthe master, which will be returned from the constructor. At the\nsame time...\n\n3. The \"new\" method also creates the slave: this is an instance of\nSLAVECLASS which is created by tying the master's IO::Handle to\nSLAVECLASS via \"tie(HANDLE, SLAVECLASS, TIEARGS...)\". This call to\n\"tie()\" creates the slave in the following manner:\n\n4. Class SLAVECLASS is sent the message \"TIEHANDLE(TIEARGS...)\"; it\nwill usually delegate this to \"SLAVECLASS::new(TIEARGS...)\",\nresulting in a new instance of SLAVECLASS being created and\nreturned.\n\n5. Once both master and slave have been created, the master is\nreturned to the caller.\n\nHow I/O operators work (on the master)\nConsider using an i/o operator on the master:\n\nprint $WT \"Hello, world!\\n\";\n\nSince the master ($WT) is really a [blessed] reference to a glob, the\nnormal Perl i/o operators like \"print\" may be used on it. They will\njust operate on the symbol part of the glob.\n\nSince the glob is tied to the slave, the slave's PRINT method (part of\nthe TIEHANDLE interface) will be automatically invoked.\n\nIf the slave is an IO::Scalar, that means IO::Scalar::PRINT will be\ninvoked, and that method happens to delegate to the \"print()\" method of\nthe same class. So the real work is ultimately done by\nIO::Scalar::print().\n\nHow methods work (on the master)\nConsider using a method on the master:\n\n$WT->print(\"Hello, world!\\n\");\n\nSince the master ($WT) is blessed into the class IO::WrapTie::Master,\nPerl first attempts to find a \"print()\" method there. Failing that,\nPerl next attempts to find a \"print()\" method in the superclass,\nIO::Handle. It just so happens that there is such a method; that\nmethod merely invokes the \"print\" i/o operator on the self object...\nand for that, see above!\n\nBut let's suppose we're dealing with a method which isn't part of\nIO::Handle... for example:\n\nmy $sref = $WT->sref;\n\nIn this case, the intuitive behavior is to have the master delegate the\nmethod invocation to the slave (now do you see where the designations\ncome from?). This is indeed what happens: IO::WrapTie::Master contains\nan AUTOLOAD method which performs the delegation.\n\nSo: when \"sref()\" can't be found in IO::Handle, the AUTOLOAD method of\nIO::WrapTie::Master is invoked, and the standard behavior of delegating\nthe method to the underlying slave (here, an IO::Scalar) is done.\n\nSometimes, to get this to work properly, you may need to create a\nsubclass of IO::WrapTie::Master which is an effective master for your\nclass, and do the delegation there.\n", "subsections": [] }, "NOTES": { "content": "Why not simply use the object's OO interface?\nBecause that means forsaking the use of named operators like\nprint(), and you may need to pass the object to a subroutine which will\nattempt to use those operators:\n\n$O = FooHandle->new(&FOORDWR, 2);\n$O->print(\"Hello, world\\n\"); ### OO syntax is okay, BUT....\n\nsub nope { print $[0] \"Nope!\\n\" }\nX nope($O); ### ERROR!!! (not a glob ref)\n\nWhy not simply use tie()?\nBecause (1) you have to use tied() to invoke methods in the\nobject's public interface (yuck), and (2) you may need to pass the tied\nsymbol to another subroutine which will attempt to treat it in an OO-\nway... and that will break it:\n\ntie *T, 'FooHandle', &FOORDWR, 2;\nprint T \"Hello, world\\n\"; ### Operator is okay, BUT...\n\ntied(*T)->otherstuff; ### yuck! AND...\n\nsub nope { shift->print(\"Nope!\\n\") }\nX nope(\\*T); ### ERROR!!! (method \"print\" on unblessed ref)\n\nWhy a master and slave?\nWhy not simply write FooHandle to inherit from IO::Handle?\nI tried this, with an implementation similar to that of IO::Socket.\nThe problem is that the whole point is to use this with objects that\ndon't have an underlying file/socket descriptor.. Subclassing\nIO::Handle will work fine for the OO stuff, and fine with named\noperators if you tie()... but if you just attempt to say:\n\n$IO = FooHandle->new(&FOORDWR, 2);\nprint $IO \"Hello!\\n\";\n\nyou get a warning from Perl like:\n\nFilehandle GEN001 never opened\n\nbecause it's trying to do system-level i/o on an (unopened) file\ndescriptor. To avoid this, you apparently have to tie() the handle...\nwhich brings us right back to where we started! At least the\nIO::WrapTie mixin lets us say:\n\n$IO = FooHandle->newtie(&FOORDWR, 2);\nprint $IO \"Hello!\\n\";\n\nand so is not too bad. \":-)\"\n", "subsections": [] }, "WARNINGS": { "content": "Remember: this stuff is for doing FileHandle-like i/o on things without\nunderlying file descriptors. If you have an underlying file\ndescriptor, you're better off just inheriting from IO::Handle.\n\nBe aware that newtie() always returns an instance of a kind of\nIO::WrapTie::Master... it does not return an instance of the i/o class\nyou're tying to!\n\nInvoking some methods on the master object causes AUTOLOAD to delegate\nthem to the slave object... so it looks like you're manipulating a\n\"FooHandle\" object directly, but you're not.\n\nI have not explored all the ramifications of this use of tie(). Here\nthere be dragons.\n", "subsections": [] }, "VERSION": { "content": "$Id: WrapTie.pm,v 1.2 2005/02/10 21:21:53 dfs Exp $\n", "subsections": [] }, "AUTHOR": { "content": "Primary Maintainer\nDianne Skoll (dfs@roaringpenguin.com).\n\nOriginal Author\nEryq (eryq@zeegee.com). President, ZeeGee Software Inc\n(http://www.zeegee.com).\n\nperl v5.28.1 2019-02-28 IO::WrapTie(3pm)", "subsections": [] } } } }