<HTML> <HEAD> <TITLE>IO::Wrap 2.102</TITLE> </HEAD> <BODY bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666"> <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> </A><UL> <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A> <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A> <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A> <LI> <A NAME="menu:NOTES"><A HREF="#NOTES">NOTES</A></A> <LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A> <LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A> <LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A> </UL> <P><HR> <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> <P>IO::Wrap - wrap raw filehandles in IO::Handle interface <P><HR> <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> <FONT SIZE=3 FACE="courier"><PRE> use IO::Wrap; ### Do stuff with any kind of filehandle (including a bare globref), or ### any kind of blessed object that responds to a print() message. ### sub do_stuff { my $fh = shift; ### At this point, we have no idea what the user gave us... ### a globref? a FileHandle? a scalar filehandle name? $fh = wraphandle($fh); ### At this point, we know we have an IO::Handle-like object! $fh->print("Hey there!"); ... } </PRE></FONT> <P><HR> <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> <P>Let's say you want to write some code which does I/O, but you don't want to force the caller to provide you with a FileHandle or IO::Handle object. You want them to be able to say: <FONT SIZE=3 FACE="courier"><PRE> do_stuff(\*STDOUT); do_stuff('STDERR'); do_stuff($some_FileHandle_object); do_stuff($some_IO_Handle_object); </PRE></FONT> <P>And even: <FONT SIZE=3 FACE="courier"><PRE> do_stuff($any_object_with_a_print_method); </PRE></FONT> <P>Sure, one way to do it is to force the caller to use tiehandle(). But that puts the burden on them. Another way to do it is to use <B>IO::Wrap</B>, which provides you with the following functions: <DL> <P><DT><B><A NAME="item:wraphandle"><A NAME="item:wraphandle_SCALAR">wraphandle SCALAR</A></A></B></DT> <DD> This function will take a single argument, and "wrap" it based on what it seems to be... <UL> <P><LI> <P><B>A raw scalar filehandle name,</B> like <CODE>"STDOUT"</CODE> or <CODE>"Class::HANDLE"</CODE>. In this case, the filehandle name is wrapped in an IO::Wrap object, which is returned. <P><LI> <P><B>A raw filehandle glob,</B> like <CODE>\*STDOUT</CODE>. In this case, the filehandle glob is wrapped in an IO::Wrap object, which is returned. <P><LI> <P><B>A blessed FileHandle object.</B> In this case, the FileHandle is wrapped in an IO::Wrap object if and only if your FileHandle class does not support the <CODE>read()</CODE> method. <P><LI> <P><B>Any other kind of blessed object,</B> which is assumed to be already conformant to the IO::Handle interface. In this case, you just get back that object. </UL> </DL> <P>If you get back an IO::Wrap object, it will obey a basic subset of the IO:: interface. That is, the following methods (note: I said <I>methods</I>, not named operators) should work on the thing you get back: <FONT SIZE=3 FACE="courier"><PRE> close getline getlines print ARGS... read BUFFER,NBYTES seek POS,WHENCE tell </PRE></FONT> <P><HR> <A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A> <P>Clearly, when wrapping a raw external filehandle (like \*STDOUT), I didn't want to close the file descriptor when the "wrapper" object is destroyed... since the user might not appreciate that! Hence, there's no DESTROY method in this class. <P>When wrapping a FileHandle object, however, I believe that Perl will invoke the FileHandle::DESTROY when the last reference goes away, so in that case, the filehandle is closed if the wrapped FileHandle really was the last reference to it. <P><HR> <A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A> <P>This module does not allow you to wrap filehandle names which are given as strings that lack the package they were opened in. That is, if a user opens FOO in package Foo, they must pass it to you either as <CODE>\*FOO</CODE> or as <CODE>"Foo::FOO"</CODE>. However, <CODE>"STDIN"</CODE> and friends will work just fine. <P><HR> <A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> <P>$Id: Wrap.pm.html,v 1.1.1.1 2004/05/20 17:49:39 jpetri Exp $ <P><HR> <A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). <P><HR> <ADDRESS><FONT SIZE=-1> Generated Sun Dec 21 13:54:38 2003 by cvu_pod2html </FONT></ADDRESS> </FONT></BODY> </HTML>