/usr/share/doc/libio-stringy-perl/html/Wrap.pm.html

<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-&gt;print(&quot;Hey there!&quot;);
       ...
   }
    
</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 &quot;wrap&quot; it based on
what it seems to be...



<UL>
<P><LI>
<P><B>A raw scalar filehandle name,</B> like <CODE>&quot;STDOUT&quot;</CODE> or <CODE>&quot;Class::HANDLE&quot;</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 &quot;wrapper&quot; 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>&quot;Foo::FOO&quot;</CODE>.  However, <CODE>&quot;STDIN&quot;</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,v 2.102 2001/08/17 02:06:33 eryq 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>
libio-stringy-perl 2.110-5 / usr / share / doc / libio-stringy-perl / html / Wrap.pm.html
