{
    "mode": "perldoc",
    "parameter": "IO::WrapTie",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/IO%3A%3AWrapTie/json",
    "generated": "2026-06-12T06:59:32Z",
    "synopsis": "First of all, you'll need tie(), so:\nrequire 5.004;\n*Function 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!\n*OO interface (preferred).* You can inherit from the IO::WrapTie::Slave mixin to get a nifty\n\"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 which work both with and\nwithout 5.004.",
    "sections": {
        "NAME": {
            "content": "IO::WrapTie - wrap tieable objects in IO::Handle interface\n\n*This is currently Alpha code, released for comments. Please give me your feedback!*\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "First of all, you'll need tie(), so:\n\nrequire 5.004;\n\n*Function 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\n*OO interface (preferred).* You can inherit from the IO::WrapTie::Slave mixin to get a nifty\n\"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\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 which work both with and\nwithout 5.004.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Suppose you have a class \"FooHandle\", where...\n\n*   FooHandle does not inherit from IO::Handle; that is, it performs filehandle-like I/O, but to\nsomething other than an underlying file descriptor. Good examples are IO::Scalar (for\nprinting to a string) and IO::Lines (for printing to an array of lines).\n\n*   FooHandle implements the TIEHANDLE interface (see perltie); that is, it provides methods\nTIEHANDLE, GETC, PRINT, PRINTF, READ, and READLINE.\n\n*   FooHandle implements the traditional OO interface of FileHandle and IO::Handle; i.e., it\ncontains methods like getline(), read(), print(), seek(), tell(), eof(), etc.\n\nNormally, users of your class would have two options:\n\n*   Use only OO syntax, and forsake named I/O operators like 'print'.\n\n*   Use with tie, and forsake treating it as a first-class object (i.e., class-specific methods\ncan only be invoked through the underlying 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 from \"IO::WrapTie::Slave\"\nand 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 an IO::Handle... and be\nused both with OO and non-OO filehandle syntax.\n",
            "subsections": []
        },
        "HOW IT ALL WORKS": {
            "content": "",
            "subsections": [
                {
                    "name": "The data structures",
                    "content": "Consider 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\n*NOTE:* just as an IO::Handle is really just a blessed reference to a *traditional* filehandle\nglob... so also, an IO::WrapTie::Master is really just a blessed reference to a filehandle glob\n*which has been tied to some \"slave\" class.*\n\nHow wraptie() works\n1.  The call to function \"wraptie(SLAVECLASS, TIEARGS...)\" is passed onto\n\"IO::WrapTie::Master::new()\". Note that class IO::WrapTie::Master is a subclass of\nIO::Handle.\n\n2.  The \"IO::WrapTie::Master::new\" method creates a new IO::Handle object, reblessed into class\nIO::WrapTie::Master. This object is the *master*, which will be returned from the\nconstructor. At the same time...\n\n3.  The \"new\" method also creates the *slave*: this is an instance of SLAVECLASS which is\ncreated by tying the master's IO::Handle to SLAVECLASS via \"tie(HANDLE, SLAVECLASS,\nTIEARGS...)\". This call to \"tie()\" creates the slave in the following manner:\n\n4.  Class SLAVECLASS is sent the message \"TIEHANDLE(TIEARGS...)\"; it will usually delegate this\nto \"SLAVECLASS::new(TIEARGS...)\", resulting in a new instance of SLAVECLASS being created\nand returned.\n\n5.  Once both master and slave have been created, the master is returned 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 normal Perl i/o operators\nlike \"print\" may be used on it. They will just operate on the symbol part of the glob.\n\nSince the glob is tied to the slave, the slave's PRINT method (part of the TIEHANDLE interface)\nwill be automatically invoked.\n\nIf the slave is an IO::Scalar, that means IO::Scalar::PRINT will be invoked, and that method\nhappens to delegate to the \"print()\" method of the same class. So the *real* work is ultimately\ndone by IO::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, Perl first attempts to\nfind a \"print()\" method there. Failing that, Perl next attempts to find a \"print()\" method in\nthe superclass, IO::Handle. It just so happens that there *is* such a method; that method merely\ninvokes the \"print\" i/o operator on the self object... and for that, see above!\n\nBut let's suppose we're dealing with a method which *isn't* part of IO::Handle... for example:\n\nmy $sref = $WT->sref;\n\nIn this case, the intuitive behavior is to have the master delegate the method invocation to the\nslave (now do you see where the designations come from?). This is indeed what happens:\nIO::WrapTie::Master contains an AUTOLOAD method which performs the delegation.\n\nSo: when \"sref()\" can't be found in IO::Handle, the AUTOLOAD method of IO::WrapTie::Master is\ninvoked, and the standard behavior of delegating the method to the underlying slave (here, an\nIO::Scalar) is done.\n\nSometimes, to get this to work properly, you may need to create a subclass of\nIO::WrapTie::Master which is an effective master for *your* class, and do the delegation there.\n"
                }
            ]
        },
        "NOTES": {
            "content": "Why not simply use the object's OO interface? Because that means forsaking the use of named\noperators like print(), and you may need to pass the object to a subroutine which will attempt\nto 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()? Because (1) you have to use tied() to invoke methods in the object's\npublic interface (yuck), and (2) you may need to pass the tied symbol to another subroutine\nwhich will attempt to treat it in an OO-way... 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? Why not simply write FooHandle to inherit from IO::Handle? I tried this,\nwith an implementation similar to that of IO::Socket. The problem is that *the whole point is to\nuse this with objects that don't have an underlying file/socket descriptor.*. Subclassing\nIO::Handle will work fine for the OO stuff, and fine with named operators *if* you tie()... but\nif 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 descriptor. To avoid this, you\napparently have to tie() the handle... which brings us right back to where we started! At least\nthe IO::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 underlying file\ndescriptors*. If you have an underlying file descriptor, you're better off just inheriting from\nIO::Handle.\n\nBe aware that newtie() always returns an instance of a kind of IO::WrapTie::Master... it does\nnot return an instance of the i/o class you're tying to!\n\nInvoking some methods on the master object causes AUTOLOAD to delegate them to the slave\nobject... so it *looks* like you're manipulating a \"FooHandle\" object directly, but you're not.\n\nI have not explored all the ramifications of this use of tie(). *Here there 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 (http://www.zeegee.com).\n",
            "subsections": []
        }
    },
    "summary": "IO::WrapTie - wrap tieable objects in IO::Handle interface  *This is currently Alpha code, released for comments. Please give me your feedback!*",
    "flags": [],
    "examples": [],
    "see_also": []
}