3 <TITLE>IO::Wrap 2.102</TITLE>
6 bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
7 <FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::Wrap 2.102</H1>
9 <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
10 <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
11 <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
12 <LI> <A NAME="menu:NOTES"><A HREF="#NOTES">NOTES</A></A>
13 <LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A>
14 <LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A>
15 <LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
20 <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>
23 <P>IO::Wrap - wrap raw filehandles in IO::Handle interface
28 <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>
30 <FONT SIZE=3 FACE="courier"><PRE>
33 ### Do stuff with any kind of filehandle (including a bare globref), or
34 ### any kind of blessed object that responds to a print() message.
39 ### At this point, we have no idea what the user gave us...
40 ### a globref? a FileHandle? a scalar filehandle name?
42 $fh = wraphandle($fh);
44 ### At this point, we know we have an IO::Handle-like object!
46 $fh->print("Hey there!");
54 <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
57 <P>Let's say you want to write some code which does I/O, but you don't
58 want to force the caller to provide you with a FileHandle or IO::Handle
59 object. You want them to be able to say:
61 <FONT SIZE=3 FACE="courier"><PRE>
64 do_stuff($some_FileHandle_object);
65 do_stuff($some_IO_Handle_object);
70 <FONT SIZE=3 FACE="courier"><PRE>
71 do_stuff($any_object_with_a_print_method);
74 <P>Sure, one way to do it is to force the caller to use tiehandle().
75 But that puts the burden on them. Another way to do it is to
76 use <B>IO::Wrap</B>, which provides you with the following functions:
81 <P><DT><B><A NAME="item:wraphandle"><A NAME="item:wraphandle_SCALAR">wraphandle SCALAR</A></A></B></DT>
83 This function will take a single argument, and "wrap" it based on
84 what it seems to be...
90 <P><B>A raw scalar filehandle name,</B> like <CODE>"STDOUT"</CODE> or <CODE>"Class::HANDLE"</CODE>.
91 In this case, the filehandle name is wrapped in an IO::Wrap object,
95 <P><B>A raw filehandle glob,</B> like <CODE>\*STDOUT</CODE>.
96 In this case, the filehandle glob is wrapped in an IO::Wrap object,
100 <P><B>A blessed FileHandle object.</B>
101 In this case, the FileHandle is wrapped in an IO::Wrap object if and only
102 if your FileHandle class does not support the <CODE>read()</CODE> method.
105 <P><B>Any other kind of blessed object,</B> which is assumed to be already
106 conformant to the IO::Handle interface.
107 In this case, you just get back that object.
114 <P>If you get back an IO::Wrap object, it will obey a basic subset of
115 the IO:: interface. That is, the following methods (note: I said
116 <I>methods</I>, not named operators) should work on the thing you get back:
118 <FONT SIZE=3 FACE="courier"><PRE>
130 <A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A>
133 <P>Clearly, when wrapping a raw external filehandle (like \*STDOUT),
134 I didn't want to close the file descriptor when the "wrapper" object is
135 destroyed... since the user might not appreciate that! Hence,
136 there's no DESTROY method in this class.
139 <P>When wrapping a FileHandle object, however, I believe that Perl will
140 invoke the FileHandle::DESTROY when the last reference goes away,
141 so in that case, the filehandle is closed if the wrapped FileHandle
142 really was the last reference to it.
147 <A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>
150 <P>This module does not allow you to wrap filehandle names which are given
151 as strings that lack the package they were opened in. That is, if a user
152 opens FOO in package Foo, they must pass it to you either as <CODE>\*FOO</CODE>
153 or as <CODE>"Foo::FOO"</CODE>. However, <CODE>"STDIN"</CODE> and friends will work just fine.
158 <A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>
161 <P>$Id: Wrap.pm,v 2.102 2001/08/17 02:06:33 eryq Exp $
167 <A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>
170 <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
171 President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).
174 <ADDRESS><FONT SIZE=-1>
175 Generated Sun Dec 21 13:54:38 2003 by cvu_pod2html