home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _45e532c87038331027a377cff63c4946 < prev    next >
Text File  |  2000-03-23  |  5KB  |  157 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>IO::Wrap - wrap raw filehandles in IO::Handle interface</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> IO::Wrap - wrap raw filehandles in IO::Handle interface</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#notes">NOTES</A></LI>
  26.     <LI><A HREF="#warnings">WARNINGS</A></LI>
  27.     <LI><A HREF="#author">AUTHOR</A></LI>
  28. </UL>
  29. <!-- INDEX END -->
  30.  
  31. <HR>
  32. <P>
  33. <H1><A NAME="name">NAME</A></H1>
  34. <P>IO::Wrap - wrap raw filehandles in IO::Handle interface</P>
  35. <P>
  36. <HR>
  37. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  38. <UL>
  39. <LI>Linux</LI>
  40. <LI>Solaris</LI>
  41. <LI>Windows</LI>
  42. </UL>
  43. <HR>
  44. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  45. <PRE>
  46.    use IO::Wrap;
  47. </PRE>
  48. <PRE>
  49.  
  50.    # Do stuff with any kind of filehandle (including a bare globref), or 
  51.    # any kind of blessed object that responds to a print() message.
  52.    #
  53.    sub do_stuff {
  54.        my $fh = shift;</PRE>
  55. <PRE>
  56.  
  57.        ### At this point, we have no idea what the user gave us... 
  58.        ### a globref? a FileHandle? a scalar filehandle name?</PRE>
  59. <PRE>
  60.  
  61.        $fh = wraphandle($fh);</PRE>
  62. <PRE>
  63.  
  64.        ### At this point, we know we have an IO::Handle-like object!</PRE>
  65. <PRE>
  66.  
  67.        $fh->print("Hey there!");
  68.        ...
  69.    }</PRE>
  70. <P>
  71. <HR>
  72. <H1><A NAME="description">DESCRIPTION</A></H1>
  73. <P>Let's say you want to write some code which does I/O, but you don't 
  74. want to force the caller to provide you with a FileHandle or IO::Handle
  75. object.  You want them to be able to say:</P>
  76. <PRE>
  77.     do_stuff(\*STDOUT);
  78.     do_stuff('STDERR');
  79.     do_stuff($some_FileHandle_object);
  80.     do_stuff($some_IO_Handle_object);</PRE>
  81. <P>And even:</P>
  82. <PRE>
  83.     do_stuff($any_object_with_a_print_method);</PRE>
  84. <P>Sure, one way to do it is to force the caller to use tiehandle().  
  85. But that puts the burden on them.  Another way to do it is to 
  86. use <STRONG>IO::Wrap</STRONG>, which provides you with the following functions:</P>
  87. <DL>
  88. <DT><STRONG><A NAME="item_wraphandle">wraphandle SCALAR</A></STRONG><BR>
  89. <DD>
  90. This function will take a single argument, and ``wrap'' it based on
  91. what it seems to be...
  92. <UL>
  93. <LI>
  94. <STRONG>A raw scalar filehandle name,</STRONG> like <CODE>"STDOUT"</CODE> or <CODE>"Class::HANDLE"</CODE>.
  95. In this case, the filehandle name is wrapped in an IO::Wrap object, 
  96. which is returned.
  97. <P></P>
  98. <LI>
  99. <STRONG>A raw filehandle glob,</STRONG> like <CODE>\*STDOUT</CODE>.
  100. In this case, the filehandle glob is wrapped in an IO::Wrap object, 
  101. which is returned.
  102. <P></P>
  103. <LI>
  104. <STRONG>A blessed FileHandle object.</STRONG>
  105. In this case, the FileHandle is wrapped in an IO::Wrap object if and only
  106. if your FileHandle class does not support the <A HREF="../../../lib/Pod/perlfunc.html#item_read"><CODE>read()</CODE></A> method.
  107. <P></P>
  108. <LI>
  109. <STRONG>Any other kind of blessed object,</STRONG> which is assumed to be already
  110. conformant to the IO::Handle interface.
  111. In this case, you just get back that object.
  112. <P></P></UL>
  113. </DL>
  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. <EM>methods</EM>, not named operators) should work on the thing you get back:</P>
  117. <PRE>
  118.     close 
  119.     getline 
  120.     getlines 
  121.     print ARGS...
  122.     read BUFFER,NBYTES
  123.     seek POS,WHENCE
  124.     tell</PRE>
  125. <P>
  126. <HR>
  127. <H1><A NAME="notes">NOTES</A></H1>
  128. <P>Clearly, when wrapping a raw external filehandle (like \*STDOUT), 
  129. I didn't want to close the file descriptor when the ``wrapper'' object is
  130. destroyed... since the user might not appreciate that!  Hence,
  131. there's no DESTROY method in this class.</P>
  132. <P>When wrapping a FileHandle object, however, I believe that Perl will 
  133. invoke the FileHandle::DESTROY when the last reference goes away,
  134. so in that case, the filehandle is closed if the wrapped FileHandle
  135. really was the last reference to it.</P>
  136. <P>
  137. <HR>
  138. <H1><A NAME="warnings">WARNINGS</A></H1>
  139. <P>This module does not allow you to wrap filehandle names which are given
  140. as strings that lack the package they were opened in. That is, if a user 
  141. opens FOO in package Foo, they must pass it to you either as <CODE>\*FOO</CODE> 
  142. or as <CODE>"Foo::FOO"</CODE>.  However, <CODE>"STDIN"</CODE> and friends will work just fine.</P>
  143. <P>
  144. <HR>
  145. <H1><A NAME="author">AUTHOR</A></H1>
  146. <P>Eryq (<EM><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></EM>).
  147. President, ZeeGee Software Inc (<EM><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></EM>).</P>
  148. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  149. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  150. <STRONG><P CLASS=block> IO::Wrap - wrap raw filehandles in IO::Handle interface</P></STRONG>
  151. </TD></TR>
  152. </TABLE>
  153.  
  154. </BODY>
  155.  
  156. </HTML>
  157.