--- /dev/null
+<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,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>
projects / dh-make-perl / blobdiff