diff options
| author | fukachan <fukachan> | 2008-08-20 21:14:33 +0000 |
|---|---|---|
| committer | fukachan <fukachan> | 2008-08-20 21:14:33 +0000 |
| commit | 21d01a22bf71f8faf018530569b3f7a63e83aa06 (patch) | |
| tree | b15adf772e77e58dc764b4ad1d2efa64ef2c909f | |
| parent | b41e282fb4b1daa53d578cc58189ca832f40b195 (diff) | |
| download | fml8-21d01a22bf71f8faf018530569b3f7a63e83aa06.tar.gz fml8-21d01a22bf71f8faf018530569b3f7a63e83aa06.tar.bz2 fml8-21d01a22bf71f8faf018530569b3f7a63e83aa06.zip | |
remove IO::Stringy (not used)
41 files changed, 1 insertions, 8438 deletions
diff --git a/cpan/MANIFEST b/cpan/MANIFEST index fd1b8d5f..88210cb8 100644 --- a/cpan/MANIFEST +++ b/cpan/MANIFEST @@ -13,8 +13,6 @@ HTML-CalendarMonthSimple 1.02 ? (freesoftware, unlimited) HTML-FromText 1.005 perl itself HTML-Template 2.5 perl (GNU or Artistic) -IO-stringy 1.220 ? - Jcode 0.83 perl itself Log-ErrLogger 1.5 perl itself @@ -38,4 +36,4 @@ Text-CSV 0.01 perl itself Unicode-Japanese 0.09 perl itself -$FML: MANIFEST,v 1.14 2006/01/01 14:53:51 fukachan Exp $ +$FML: MANIFEST,v 1.15 2008/05/11 13:11:06 fukachan Exp $ diff --git a/cpan/dist/IO-stringy/MANIFEST b/cpan/dist/IO-stringy/MANIFEST deleted file mode 100644 index 88f05544..00000000 --- a/cpan/dist/IO-stringy/MANIFEST +++ /dev/null @@ -1,32 +0,0 @@ -MANIFEST -Makefile.PL -README -README.system -docs/IO/AtomicFile.pm.html -docs/IO/InnerFile.pm.html -docs/IO/Lines.pm.html -docs/IO/Scalar.pm.html -docs/IO/ScalarArray.pm.html -docs/IO/Stringy.pm.html -docs/IO/Wrap.pm.html -docs/IO/WrapTie.pm.html -docs/IO/icons/h1bullet.gif -docs/IO/icons/h2bullet.gif -docs/IO/icons/zeegee.gif -docs/index-menu.html -docs/index.html -docs/index.menu -lib/IO/AtomicFile.pm -lib/IO/InnerFile.pm -lib/IO/Lines.pm -lib/IO/Scalar.pm -lib/IO/ScalarArray.pm -lib/IO/Stringy.pm -lib/IO/Wrap.pm -lib/IO/WrapTie.pm -t/Common.pm -t/ExtUtils/TBone.pm -t/IO_Lines.t -t/IO_Scalar.t -t/IO_ScalarArray.t -t/IO_WrapTie.t diff --git a/cpan/dist/IO-stringy/Makefile.PL b/cpan/dist/IO-stringy/Makefile.PL deleted file mode 100755 index aeecddc2..00000000 --- a/cpan/dist/IO-stringy/Makefile.PL +++ /dev/null @@ -1,22 +0,0 @@ -#!/usr/bin/perl -use ExtUtils::MakeMaker; - -#------------------------------------------------------------ -# Makefile: -#------------------------------------------------------------ - -# Ensure the test output directory: -(-d "testout") or mkdir "testout", 0755 or die "please make dir ./testout\n"; - -# Write the Makefile: -WriteMakefile( - NAME => "IO-stringy", - VERSION_FROM => "lib/IO/Stringy.pm", - DISTNAME => "IO-stringy", - 'dist' => { - PREOP => "cvu_perl_preop -m IO::Stringy -f", - COMPRESS => 'gzip', - SUFFIX => 'gz', - } - ); - diff --git a/cpan/dist/IO-stringy/README b/cpan/dist/IO-stringy/README deleted file mode 100644 index 26e28f18..00000000 --- a/cpan/dist/IO-stringy/README +++ /dev/null @@ -1,119 +0,0 @@ -NAME - IO-stringy - I/O on in-core objects like strings and arrays - -SYNOPSIS - IO:: - ::AtomicFile adpO Write a file which is updated atomically ERYQ - ::Lines bdpO I/O handle to read/write to array of lines ERYQ - ::Scalar RdpO I/O handle to read/write to a string ERYQ - ::ScalarArray RdpO I/O handle to read/write to array of scalars ERYQ - ::Wrap RdpO Wrap old-style FHs in standard OO interface ERYQ - ::WrapTie adpO Tie your handles & retain full OO interface ERYQ - -DESCRIPTION - This toolkit primarily provides modules for performing both traditional - and object-oriented i/o) on things *other* than normal filehandles; in - particular, IO::Scalar, IO::ScalarArray, and IO::Lines. - - If you have access to tie(), these classes will make use of the - IO::WrapTie module to inherit a convenient new_tie() constructor. It - also exports a nice wraptie() function. - - In the more-traditional IO::Handle front, we have IO::AtomicFile which - may be used to painlessly create files which are updated atomically. - - And in the "this-may-prove-useful" corner, we have IO::Wrap, whose - exported wraphandle() function will clothe anything that's not a blessed - object in an IO::Handle-like wrapper... so you can just use OO syntax - and stop worrying about whether your function's caller handed you a - string, a globref, or a FileHandle. - -INSTALLATION - You know the drill... - - perl Makefile.PL - make test - make install - -VERSION - $Id: Stringy.pm,v 1.216 2000/09/28 06:32:28 eryq Exp $ - -CHANGE LOG - Version 1.216 (2000/09/28) - IO::Scalar and IO::ScalarArray now inherit from IO::Handle. I - thought I'd remembered a problem with this ages ago, related to the - fact that these IO:: modules don't have "real" filehandles, but the - problem apparently isn't surfacing now. If you suddenly encounter - Perl warnings during global destruction (especially if you're using - tied filehandles), then please let me know! *Thanks to B. K. Oxley - (binkley) for this.* - - Nasty bug fixed in IO::Scalar::write(). Apparently, the offset and - the number-of-bytes arguments were, for all practical purposes, - *reversed.* You were okay if you did all your writing with print(), - but boy was *this* a stupid bug! *Thanks to Richard Jones for - finding this one. For you, Rich, a double-length haiku:* - - Newspaper headline - typeset by dyslexic man - loses urgency - - BABY EATS FISH is - simply not equivalent - to FISH EATS BABY - - New sysread and syswrite methods for IO::Scalar. *Thanks again to - Richard Jones for this.* - - Version 1.215 (2000/09/05) - Added 'bool' overload to '""' overload, so object always evaluates - to true. (Whew. Glad I caught this before it went to CPAN.) - - Version 1.214 (2000/09/03) - Evaluating an IO::Scalar in a string context now yields the - underlying string. *Thanks to B. K. Oxley (binkley) for this.* - - Version 1.213 (2000/08/16) - Minor documentation fixes. - - Version 1.212 (2000/06/02) - Fixed IO::InnerFile incompatibility with Perl5.004. *Thanks to many - folks for reporting this.* - - Version 1.210 (2000/04/17) - Added flush() and other no-op methods. *Thanks to Doru Petrescu for - suggesting this.* - - Version 1.209 (2000/03/17) - Small bug fixes. - - Version 1.208 (2000/03/14) - Incorporated a number of contributed patches and extensions, mostly - related to speed hacks, support for "offset", and WRITE/CLOSE - methods. *Thanks to Richard Jones, Doru Petrescu, and many others.* - - Version 1.206 (1999/04/18) - Added creation of ./testout when Makefile.PL is run. - - Version 1.205 (1999/01/15) - Verified for Perl5.005. - - Version 1.202 (1998/04/18) - New IO::WrapTie and IO::AtomicFile added. - - Version 1.110 - Added IO::WrapTie. - - Version 1.107 - Added IO::Lines, and made some bug fixes to IO::ScalarArray. Also, - added getc(). - - Version 1.105 - No real changes; just upgraded IO::Wrap to have a $VERSION string. - -AUTHOR - Eryq (eryq@zeegee.com). President, ZeeGee Software Inc - (http://www.zeegee.com). - - Enjoy. Yell if it breaks. - diff --git a/cpan/dist/IO-stringy/README.system b/cpan/dist/IO-stringy/README.system deleted file mode 100644 index f108bff0..00000000 --- a/cpan/dist/IO-stringy/README.system +++ /dev/null @@ -1,8 +0,0 @@ -DEVELOPMENT SYSTEM: -Linux eryq 2.0.34 #1 Fri May 8 16:05:57 EDT 1998 i586 unknown - -DEVELOPMENT PERL: -This is perl, version 5.005_56 built for i586-linux - -DEVELOPMENT DATE: -Thu Sep 28 02:36:05 EDT 2000 diff --git a/cpan/dist/IO-stringy/docs/IO/AtomicFile.pm.html b/cpan/dist/IO-stringy/docs/IO/AtomicFile.pm.html deleted file mode 100644 index 8907c02b..00000000 --- a/cpan/dist/IO-stringy/docs/IO/AtomicFile.pm.html +++ /dev/null @@ -1,101 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::AtomicFile</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::AtomicFile</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -<LI> <A HREF="#REVISION">REVISION</A> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::AtomicFile - write a file which is updated atomically - - - -<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::AtomicFile; - - # Write a temp file, and have it install itself when closed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->close || die "couldn't install atomic file: $!"; - - # Write a temp file, but delete it before it gets installed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->delete; - - # Write a temp file, but neither install it nor delete it: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->detach; -</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>This module is intended for people who need to update files -reliably in the face of unexpected program termination. - - -<P>For example, you generally don't want to be halfway in the middle of -writing <I>/etc/passwd</I> and have your program terminate! Even -the act of writing a single scalar to a filehandle is <I>not</I> atomic. - - -<P>But this module gives you true atomic updates, via rename(). -When you open a file <I>/foo/bar.dat</I> via this module, you are <I>actually</I> -opening a temporary file <I>/foo/bar.dat..TMP</I>, and writing your -output there. The act of closing this file (either explicitly -via close(), or implicitly via the destruction of the object) -will cause rename() to be called... therefore, from the point -of view of the outside world, the file's contents are updated -in a single time quantum. - - -<P>To ensure that problems do not go undetected, the "close" method -done by the destructor will raise a fatal exception if the rename() -fails. The explicit close() just returns undef. - - -<P>You can also decide at any point to trash the file you've been -building. - - - -<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> -<A NAME="REVISION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> REVISION</H2></A> - - -<P>$Revision: 1.105 $ - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:44 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html b/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html deleted file mode 100644 index b0f3a5b6..00000000 --- a/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html +++ /dev/null @@ -1,126 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::InnerFile</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::InnerFile</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::InnerFile - define a file inside another file - - - -<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> - ### Read a subset of a file: - $inner = IO::InnerFile->new($fh, $start, $length); - while (<$inner>) { - ... - } -</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>If you have a filehandle that can seek() and tell(), then you -can open an IO::InnerFile on a range of the underlying file. - - - -<P><HR> -<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> - - - -<DL> -<P><DT><B><A NAME="item:new">new FILEHANDLE, [START, [LENGTH]]</A></B></DT> -<DD> -<I>Class method, constructor.</I> -Create a new inner-file opened on the given FILEHANDLE, -from bytes START to START+LENGTH. Both START and LENGTH -default to 0; negative values are silently coerced to zero. - - -<P>Note that FILEHANDLE must be able to seek() and tell(), in addition -to whatever other methods you may desire for reading it. - -<P><DT><B><A NAME="item:set_length">set_length LENGTH</A></B></DT> -<DD> -<P><DT><B><A NAME="item:get_length">get_length</A></B></DT> -<DD> -<P><DT><B><A NAME="item:add_length">add_length NBYTES</A></B></DT> -<DD> -<I>Instance methods.</I> -Get/set the virtual length of the inner file. - -<P><DT><B><A NAME="item:set_start">set_start START</A></B></DT> -<DD> -<P><DT><B><A NAME="item:get_start">get_start</A></B></DT> -<DD> -<P><DT><B><A NAME="item:add_start">add_start NBYTES</A></B></DT> -<DD> -<I>Instance methods.</I> -Get/set the virtual start position of the inner file. - -<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> -<DD> -<P><DT><B><A NAME="item:close">close</A></B></DT> -<DD> -<P><DT><B><A NAME="item:flush">flush</A></B></DT> -<DD> -<P><DT><B><A NAME="item:getc">getc</A></B></DT> -<DD> -<P><DT><B><A NAME="item:getline">getline</A></B></DT> -<DD> -<P><DT><B><A NAME="item:print">print LIST</A></B></DT> -<DD> -<P><DT><B><A NAME="item:printf">printf LIST</A></B></DT> -<DD> -<P><DT><B><A NAME="item:read">read BUF, NBYTES</A></B></DT> -<DD> -<P><DT><B><A NAME="item:readline">readline</A></B></DT> -<DD> -<P><DT><B><A NAME="item:seek">seek OFFFSET, WHENCE</A></B></DT> -<DD> -<P><DT><B><A NAME="item:tell">tell</A></B></DT> -<DD> -<P><DT><B><A NAME="item:write">write ARGS...</A></B></DT> -<DD> -<I>Instance methods.</I> -Standard filehandle methods. - -</DL> - - - -<P><HR> -<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> - - -<P>Original version by Doru Petrescu (pdoru@kappa.ro). - - -<P>Documentation and current maintenance by Eryq (eryq@zeegee.com). - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:46 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Lines.pm.html b/cpan/dist/IO-stringy/docs/IO/Lines.pm.html deleted file mode 100644 index a95a3695..00000000 --- a/cpan/dist/IO-stringy/docs/IO/Lines.pm.html +++ /dev/null @@ -1,103 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::Lines</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::Lines</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#VERSION">VERSION</A> -<LI> <A HREF="#AUTHORS">AUTHORS</A> -<UL> -<LI> <A HREF="#Principal_author">Principal author</A> -<LI> <A HREF="#Other_contributors">Other contributors</A> -</UL> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::Lines - IO:: interface for reading/writing an array of lines - - - -<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::Lines; - - # See IO::ScalarArray for details -</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>This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) an array of lines. They can be tiehandle'd as well. - - -<P>This is a subclass of <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A> -in which the underlying -array has its data stored in a line-oriented-format: that is, -every element ends in a <CODE>"\n"</CODE>, with the possible exception of the -final element. This makes <CODE>getline()</CODE> <I>much</I> more efficient; -if you plan to do line-oriented reading/printing, you want this class. - - -<P>The <CODE>print()</CODE> method will enforce this rule, so you can print -arbitrary data to the line-array: it will break the data at -newlines appropriately. - - -<P>See <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A> for full usage. - - - -<P><HR> -<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> - - -<P>$Id: Lines.pm,v 1.110 2000/08/16 04:59:02 eryq Exp $ - - - -<P><HR> -<A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A> - - - -<P><HR> -<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></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> -<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> - - -<P>Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - - -<P><I>Morris M. Siegel,</I> -for his $/ patch and the new <CODE>getlines()</CODE>. - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:48 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html b/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html deleted file mode 100644 index 015bfa5e..00000000 --- a/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html +++ /dev/null @@ -1,361 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::Scalar</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::Scalar</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A> -<UL> -<LI> <A HREF="#Construction">Construction</A> -<LI> <A HREF="#Input_and_output">Input and output</A> -<LI> <A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A> -</UL> -<LI> <A HREF="#VERSION">VERSION</A> -<LI> <A HREF="#AUTHORS">AUTHORS</A> -<UL> -<LI> <A HREF="#Principal_author">Principal author</A> -<LI> <A HREF="#Other_contributors">Other contributors</A> -</UL> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::Scalar - IO:: interface for reading/writing a scalar - - - -<P><HR> -<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> - - -<P>If you have any Perl5, you can use the basic OO interface... - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::Scalar; - - ### Open a handle on a string: - $SH = new IO::Scalar; - $SH->open(\$somestring); - - ### Open a handle on a string, read it line-by-line, then close it: - $SH = new IO::Scalar \$somestring; - while ($_ = $SH->getline) { print "Line: $_" } - $SH->close; - - ### Open a handle on a string, and slurp in all the lines: - $SH = new IO::Scalar \$somestring; - print $SH->getlines; - - ### Open a handle on a string, and append to it: - $SH = new IO::Scalar \$somestring - $SH->print("bar\n"); ### will add "bar\n" to the end - - ### Get the current position: - $pos = $SH->getpos; ### $SH->tell() also works - - ### Set the current position: - $SH->setpos($pos); ### $SH->seek(POS,WHENCE) also works - - ### Open an anonymous temporary scalar: - $SH = new IO::Scalar; - $SH->print("Hi there!"); - print "I got: ", ${$SH->sref}, "\n"; ### get at value -</PRE></FONT> - -<P>If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write scalars just like files: - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::Scalar; -</PRE></FONT> -<FONT SIZE=3 FACE="courier"><PRE> - ### Writing to a scalar... - my $s; - tie *OUT, 'IO::Scalar', \$s; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... $s\n" - - ### Reading and writing an anonymous scalar... - tie *OUT, 'IO::Scalar'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } -</PRE></FONT> - -<P>Stringification now works, too! - -<FONT SIZE=3 FACE="courier"><PRE> - my $SH = new IO::Scalar \$somestring; - $SH->print("Hello, "); - $SH->print("world!"); - print "I've got: <$SH>\n"; -</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>This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - - -<P>Basically, this: - -<FONT SIZE=3 FACE="courier"><PRE> - my $s; - $SH = new IO::Scalar \$s; - $SH->print("Hel", "lo, "); # OO style - $SH->print("world!\n"); # ditto -</PRE></FONT> - -<P>Or this (if you have 5.004 or later): - -<FONT SIZE=3 FACE="courier"><PRE> - my $s; - $SH = tie *OUT, 'IO::Scalar', \$s; - print OUT "Hel", "lo, "; # non-OO style - print OUT "world!\n"; # ditto -</PRE></FONT> - -<P>Or this (if you have 5.004 or later): - -<FONT SIZE=3 FACE="courier"><PRE> - my $s; - $SH = IO::Scalar->new_tie(\$s); - $SH->print("Hel", "lo, "); # OO style... - print $SH "world!\n"; # ...or non-OO style! -</PRE></FONT> - -<P>Causes $s to be set to: - -<FONT SIZE=3 FACE="courier"><PRE> - "Hello, world!\n" -</PRE></FONT> - - -<P><HR> -<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> - - - -<P><HR> -<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:new">new [ARGS...]</A></B></DT> -<DD> -<I>Class method.</I> -Return a new, unattached scalar handle. -If any arguments are given, they're sent to open(). - -<P><DT><B><A NAME="item:open">open [SCALARREF]</A></B></DT> -<DD> -<I>Instance method.</I> -Open the scalar handle on a new scalar, pointed to by SCALARREF. -If no SCALARREF is given, a "private" scalar is created to hold -the file data. - - -<P>Returns the self object on success, undefined on error. - -<P><DT><B><A NAME="item:opened">opened</A></B></DT> -<DD> -<I>Instance method.</I> -Is the scalar handle opened on something? - -<P><DT><B><A NAME="item:close">close</A></B></DT> -<DD> -<I>Instance method.</I> -Disassociate the scalar handle from its underlying scalar. -Done automatically on destroy. - -</DL> - - - -<P><HR> -<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:flush">flush</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:getc">getc</A></B></DT> -<DD> -<I>Instance method.</I> -Return the next character, or undef if none remain. - -<P><DT><B><A NAME="item:getline">getline</A></B></DT> -<DD> -<I>Instance method.</I> -Return the next line, or undef on end of string. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -<P><DT><B><A NAME="item:getlines">getlines</A></B></DT> -<DD> -<I>Instance method.</I> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -<P><DT><B><A NAME="item:print">print ARGS...</A></B></DT> -<DD> -<I>Instance method.</I> -Print ARGS to the underlying scalar. - - -<P><B>Warning:</B> Currently, this always causes a "seek to the end of the string"; -this may change in the future. - -<P><DT><B><A NAME="item:read">read BUF, NBYTES, [OFFSET]</A></B></DT> -<DD> -<I>Instance method.</I> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -<P><DT><B><A NAME="item:write">write BUF, NBYTES, [OFFSET]</A></B></DT> -<DD> -<I>Instance method.</I> -Write some bytes to the scalar. - -<P><DT><B><A NAME="item:sysread">sysread BUF, LEN, [OFFSET]</A></B></DT> -<DD> -<I>Instance method.</I> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -<P><DT><B><A NAME="item:syswrite">syswrite BUF, NBYTES, [OFFSET]</A></B></DT> -<DD> -<I>Instance method.</I> -Write some bytes to the scalar. - -</DL> - - - -<P><HR> -<A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:autoflush">autoflush</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:clearerr">clearerr</A></B></DT> -<DD> -<I>Instance method.</I> Clear the error and EOF flags. A no-op. - -<P><DT><B><A NAME="item:eof">eof</A></B></DT> -<DD> -<I>Instance method.</I> Are we at end of file? - -<P><DT><B><A NAME="item:seek">seek OFFSET, WHENCE</A></B></DT> -<DD> -<I>Instance method.</I> Seek to a given position in the stream. - -<P><DT><B><A NAME="item:tell">tell</A></B></DT> -<DD> -<I>Instance method.</I> -Return the current position in the stream, as a numeric offset. - -<P><DT><B><A NAME="item:setpos">setpos POS</A></B></DT> -<DD> -<I>Instance method.</I> -Set the current position, using the opaque value returned by <CODE>getpos()</CODE>. - -<P><DT><B><A NAME="item:getpos">getpos</A></B></DT> -<DD> -<I>Instance method.</I> -Return the current position in the string, as an opaque object. - -<P><DT><B><A NAME="item:sref">sref</A></B></DT> -<DD> -<I>Instance method.</I> -Return a reference to the underlying scalar. - -</DL> - - - -<P><HR> -<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> - - -<P>$Id: Scalar.pm,v 1.122 2000/09/28 06:32:28 eryq Exp $ - - - -<P><HR> -<A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A> - - - -<P><HR> -<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></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> -<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> - - -<P>The full set of contributors always includes the folks mentioned -in <A HREF="../IO/Stringy.pm.html#CHANGE_LOG">CHANGE LOG</A>. But just the same, special -thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - - -<P><I>Andy Glew,</I> -for contributing <CODE>getc()</CODE>. - - -<P><I>Brandon Browning,</I> -for suggesting <CODE>opened()</CODE>. - - -<P><I>David Richter,</I> -for finding and fixing the bug in <CODE>PRINTF()</CODE>. - - -<P><I>Eric L. Brine,</I> -for his offset-using read() and write() implementations. - - -<P><I>Richard Jones</I> (<I><FILE><A HREF="mailto:rich@annexia.org">rich@annexia.org</A></FILE></I>), -for his patches to massively improve the performance of <CODE>getline()</CODE> -and add <CODE>sysread</CODE> and <CODE>syswrite</CODE>. - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:51 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html b/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html deleted file mode 100644 index 908a814b..00000000 --- a/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html +++ /dev/null @@ -1,338 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::ScalarArray</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::ScalarArray</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A> -<UL> -<LI> <A HREF="#Construction">Construction</A> -<LI> <A HREF="#Input_and_output">Input and output</A> -<LI> <A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A> -</UL> -<LI> <A HREF="#VERSION">VERSION</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -<UL> -<LI> <A HREF="#Principal_author">Principal author</A> -<LI> <A HREF="#Other_contributors">Other contributors</A> -</UL> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::ScalarArray - IO:: interface for reading/writing an array of scalars - - - -<P><HR> -<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> - - -<P>If you have any Perl5, you can use the basic OO interface... - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::ScalarArray; - - # Open a handle on an array-of-scalars: - $AH = new IO::ScalarArray; - $AH->open(\@a); - - # Open a handle on an array-of-scalars, read it line-by-line, - # then close it: - $AH = new IO::ScalarArray \@a; - while ($_ = $AH->getline) { print "Line: $_" } - $AH->close; - - # Open a handle on an array-of-scalars, and slurp in all the lines: - $AH = new IO::ScalarArray \@a; - print $AH->getlines; - - # Open a handle on an array-of-scalars, and append to it: - $AH = new IO::ScalarArray \@a; - $AH->print("bar\n"); - print "some string is now: ", $somestring, "\n"; - - # Get the current position: - $pos = $AH->getpos; ### $AH->tell() also works - - # Set the current position: - $AH->setpos($pos); ### $AH->seek(POS,WHENCE) also works - - # Open an anonymous temporary scalar array: - $AH = new IO::ScalarArray; - $AH->print("Hi there!\nHey there!\n"); - $AH->print("Ho there!\n"); - print "I got: ", @{$AH->aref}, "\n"; ### get at value -</PRE></FONT> - -<P>If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write as array-of-scalars just like files: - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::ScalarArray; -</PRE></FONT> -<FONT SIZE=3 FACE="courier"><PRE> - # Writing to a scalar array... - my @a; - tie *OUT, 'IO::ScalarArray', \@a; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... [", join('', @a), "]\n"; - - # Reading and writing an anonymous scalar array... - tie *OUT, 'IO::ScalarArray'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } -</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>This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - - -<P>For writing large amounts of data with individual print() statements, -this is likely to be more efficient than IO::Scalar. - - -<P>Basically, this: - -<FONT SIZE=3 FACE="courier"><PRE> - my @a; - $AH = new IO::ScalarArray \@a; - $AH->print("Hel", "lo, "); - $AH->print("world!\n"); -</PRE></FONT> - -<P>Or this (if you have 5.004 or later): - -<FONT SIZE=3 FACE="courier"><PRE> - my @a; - $AH = tie *OUT, 'IO::ScalarArray', \@a; - print OUT "Hel", "lo, "; - print OUT "world!\n"; -</PRE></FONT> - -<P>Causes @a to be set to the following arrayt of 3 strings: - -<FONT SIZE=3 FACE="courier"><PRE> - ( "Hel" , - "lo, " , - "world!\n" ) -</PRE></FONT> - -<P>Compare this with IO::Scalar. - - - -<P><HR> -<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> - - - -<P><HR> -<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:new">new [ARGS...]</A></B></DT> -<DD> -<I>Class method.</I> -Return a new, unattached array handle. -If any arguments are given, they're sent to open(). - -<P><DT><B><A NAME="item:open">open [ARRAYREF]</A></B></DT> -<DD> -<I>Instance method.</I> -Open the array handle on a new array, pointed to by ARRAYREF. -If no ARRAYREF is given, a "private" array is created to hold -the file data. - - -<P>Returns the self object on success, undefined on error. - -<P><DT><B><A NAME="item:opened">opened</A></B></DT> -<DD> -<I>Instance method.</I> -Is the array handle opened on something? - -<P><DT><B><A NAME="item:close">close</A></B></DT> -<DD> -<I>Instance method.</I> -Disassociate the array handle from its underlying array. -Done automatically on destroy. - -</DL> - - - -<P><HR> -<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:flush">flush</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:getc">getc</A></B></DT> -<DD> -<I>Instance method.</I> -Return the next character, or undef if none remain. -This does a read(1), which is somewhat costly. - -<P><DT><B><A NAME="item:getline">getline</A></B></DT> -<DD> -<I>Instance method.</I> -Return the next line, or undef on end of data. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -<P><DT><B><A NAME="item:getlines">getlines</A></B></DT> -<DD> -<I>Instance method.</I> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -<P><DT><B><A NAME="item:print">print ARGS...</A></B></DT> -<DD> -<I>Instance method.</I> -Print ARGS to the underlying array. - - -<P>Currently, this always causes a "seek to the end of the array" -and generates a new array entry. This may change in the future. - -<P><DT><B><A NAME="item:read">read BUF, NBYTES, [OFFSET];</A></B></DT> -<DD> -<I>Instance method.</I> -Read some bytes from the array. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -<P><DT><B><A NAME="item:write">write BUF, NBYTES, [OFFSET];</A></B></DT> -<DD> -<I>Instance method.</I> -Write some bytes into the array. - -</DL> - - - -<P><HR> -<A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A> - - - -<DL> -<P><DT><B><A NAME="item:autoflush">autoflush</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> -<DD> -<I>Instance method.</I> -No-op, provided for OO compatibility. - -<P><DT><B><A NAME="item:clearerr">clearerr</A></B></DT> -<DD> -<I>Instance method.</I> Clear the error and EOF flags. A no-op. - -<P><DT><B><A NAME="item:eof">eof</A></B></DT> -<DD> -<I>Instance method.</I> Are we at end of file? - -<P><DT><B><A NAME="item:seek">seek POS,WHENCE</A></B></DT> -<DD> -<I>Instance method.</I> -Seek to a given position in the stream. -Only a WHENCE of 0 (SEEK_SET) is supported. - -<P><DT><B><A NAME="item:tell">tell</A></B></DT> -<DD> -<I>Instance method.</I> -Return the current position in the stream, as a numeric offset. - -<P><DT><B><A NAME="item:setpos">setpos POS</A></B></DT> -<DD> -<I>Instance method.</I> -Seek to a given position in the array, using the opaque getpos() value. -Don't expect this to be a number. - -<P><DT><B><A NAME="item:getpos">getpos</A></B></DT> -<DD> -<I>Instance method.</I> -Return the current position in the array, as an opaque value. -Don't expect this to be a number. - -<P><DT><B><A NAME="item:aref">aref</A></B></DT> -<DD> -<I>Instance method.</I> -Return a reference to the underlying array. - -</DL> - - - -<P><HR> -<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> - - -<P>$Id: ScalarArray.pm,v 1.117 2000/09/28 06:32:28 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><HR> -<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></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> -<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> - - -<P>Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - - -<P><I>Andy Glew,</I> -for suggesting <CODE>getc()</CODE>. - - -<P><I>Brandon Browning,</I> -for suggesting <CODE>opened()</CODE>. - - -<P><I>Eric L. Brine,</I> -for his offset-using read() and write() implementations. - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:53 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html b/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html deleted file mode 100644 index ded5f7d2..00000000 --- a/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html +++ /dev/null @@ -1,208 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO-stringy</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-stringy</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#INSTALLATION">INSTALLATION</A> -<LI> <A HREF="#VERSION">VERSION</A> -<LI> <A HREF="#CHANGE_LOG">CHANGE LOG</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO-stringy - I/O on in-core objects like strings and arrays - - - -<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> - IO:: - ::AtomicFile adpO Write a file which is updated atomically ERYQ - ::Lines bdpO I/O handle to read/write to array of lines ERYQ - ::Scalar RdpO I/O handle to read/write to a string ERYQ - ::ScalarArray RdpO I/O handle to read/write to array of scalars ERYQ - ::Wrap RdpO Wrap old-style FHs in standard OO interface ERYQ - ::WrapTie adpO Tie your handles & retain full OO interface ERYQ -</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>This toolkit primarily provides modules for performing both traditional -and object-oriented i/o) on things <I>other</I> than normal filehandles; -in particular, <A HREF="../IO/Scalar.pm.html">IO::Scalar</A>, <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A>, -and <A HREF="../IO/Lines.pm.html">IO::Lines</A>. - - -<P>If you have access to tie(), these classes will make use of the -<A HREF="../IO/WrapTie.pm.html">IO::WrapTie</A> module to inherit a convenient new_tie() -constructor. It also exports a nice wraptie() function. - - -<P>In the more-traditional IO::Handle front, we -have <A HREF="../IO/AtomicFile.pm.html">IO::AtomicFile</A> -which may be used to painlessly create files which are updated -atomically. - - -<P>And in the "this-may-prove-useful" corner, we have <A HREF="../IO/Wrap.pm.html">IO::Wrap</A>, -whose exported wraphandle() function will clothe anything that's not -a blessed object in an IO::Handle-like wrapper... so you can just -use OO syntax and stop worrying about whether your function's caller -handed you a string, a globref, or a FileHandle. - - - -<P><HR> -<A NAME="INSTALLATION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> INSTALLATION</H2></A> - - -<P>You know the drill... - -<FONT SIZE=3 FACE="courier"><PRE> - perl Makefile.PL - make test - make install -</PRE></FONT> - - -<P><HR> -<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> - - -<P>$Id: Stringy.pm,v 1.216 2000/09/28 06:32:28 eryq Exp $ - - - -<P><HR> -<A NAME="CHANGE_LOG"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> CHANGE LOG</H2></A> - - - -<DL> -<P><DT><B><A NAME="item:Version">Version 1.216 (2000/09/28)</A></B></DT> -<DD> -<B>IO::Scalar and IO::ScalarArray now inherit from IO::Handle.</B> -I thought I'd remembered a problem with this ages ago, related to -the fact that these IO:: modules don't have "real" filehandles, -but the problem apparently isn't surfacing now. -If you suddenly encounter Perl warnings during global destruction -(especially if you're using tied filehandles), then please let me know! -<I>Thanks to B. K. Oxley (binkley) for this.</I> - - -<P><B>Nasty bug fixed in IO::Scalar::write().</B> -Apparently, the offset and the number-of-bytes arguments were, -for all practical purposes, <I>reversed.</I> You were okay if -you did all your writing with print(), but boy was <I>this</I> a stupid bug! -<I>Thanks to Richard Jones for finding this one. -For you, Rich, a double-length haiku:</I> - -<FONT SIZE=3 FACE="courier"><PRE> - Newspaper headline - typeset by dyslexic man - loses urgency - - BABY EATS FISH is - simply not equivalent - to FISH EATS BABY -</PRE></FONT> - -<P><B>New sysread and syswrite methods for IO::Scalar.</B> -<I>Thanks again to Richard Jones for this.</I> - -<P><DT><B><A NAME="item:Version">Version 1.215 (2000/09/05)</A></B></DT> -<DD> -Added 'bool' overload to '""' overload, so object always evaluates -to true. (Whew. Glad I caught this before it went to CPAN.) - -<P><DT><B><A NAME="item:Version">Version 1.214 (2000/09/03)</A></B></DT> -<DD> -Evaluating an IO::Scalar in a string context now yields -the underlying string. -<I>Thanks to B. K. Oxley (binkley) for this.</I> - -<P><DT><B><A NAME="item:Version">Version 1.213 (2000/08/16)</A></B></DT> -<DD> -Minor documentation fixes. - -<P><DT><B><A NAME="item:Version">Version 1.212 (2000/06/02)</A></B></DT> -<DD> -Fixed IO::InnerFile incompatibility with Perl5.004. -<I>Thanks to many folks for reporting this.</I> - -<P><DT><B><A NAME="item:Version">Version 1.210 (2000/04/17)</A></B></DT> -<DD> -Added flush() and other no-op methods. -<I>Thanks to Doru Petrescu for suggesting this.</I> - -<P><DT><B><A NAME="item:Version">Version 1.209 (2000/03/17)</A></B></DT> -<DD> -Small bug fixes. - -<P><DT><B><A NAME="item:Version">Version 1.208 (2000/03/14)</A></B></DT> -<DD> -Incorporated a number of contributed patches and extensions, -mostly related to speed hacks, support for "offset", and -WRITE/CLOSE methods. -<I>Thanks to Richard Jones, Doru Petrescu, and many others.</I> - -<P><DT><B><A NAME="item:Version">Version 1.206 (1999/04/18)</A></B></DT> -<DD> -Added creation of ./testout when Makefile.PL is run. - -<P><DT><B><A NAME="item:Version">Version 1.205 (1999/01/15)</A></B></DT> -<DD> -Verified for Perl5.005. - -<P><DT><B><A NAME="item:Version">Version 1.202 (1998/04/18)</A></B></DT> -<DD> -New IO::WrapTie and IO::AtomicFile added. - -<P><DT><B><A NAME="item:Version">Version 1.110</A></B></DT> -<DD> -Added IO::WrapTie. - -<P><DT><B><A NAME="item:Version">Version 1.107</A></B></DT> -<DD> -Added IO::Lines, and made some bug fixes to IO::ScalarArray. -Also, added getc(). - -<P><DT><B><A NAME="item:Version">Version 1.105</A></B></DT> -<DD> -No real changes; just upgraded IO::Wrap to have a $VERSION string. - -</DL> - - - -<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>Enjoy. Yell if it breaks. - -<P><HR> -<ADDRESS><FONT SIZE=-1> -Generated Thu Sep 28 02:35:55 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html b/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html deleted file mode 100644 index c7269929..00000000 --- a/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html +++ /dev/null @@ -1,169 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::Wrap</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</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#NOTES">NOTES</A> -<LI> <A HREF="#WARNINGS">WARNINGS</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -</UL> -</A> - -<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">wraphandle SCALAR</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="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 Thu Sep 28 02:36:00 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html b/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html deleted file mode 100644 index 129f47f5..00000000 --- a/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html +++ /dev/null @@ -1,418 +0,0 @@ -<HTML> -<HEAD> - <TITLE>IO::WrapTie</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::WrapTie</H1> -</A><UL> -<LI> <A HREF="#NAME">NAME</A> -<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A> -<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A> -<LI> <A HREF="#HOW_IT_ALL_WORKS">HOW IT ALL WORKS</A> -<UL> -<LI> <A HREF="#The_data_structures">The data structures</A> -<LI> <A HREF="#How_wraptie_works">How wraptie() works</A> -<LI> <A HREF="#How_I_O_operators_work_on_the_master">How I/O operators work (on the master)</A> -<LI> <A HREF="#How_methods_work_on_the_master">How methods work (on the master)</A> -</UL> -<LI> <A HREF="#NOTES">NOTES</A> -<LI> <A HREF="#WARNINGS">WARNINGS</A> -<LI> <A HREF="#AUTHOR">AUTHOR</A> -</UL> -</A> - -<P><HR> -<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> - - -<P>IO::WrapTie - wrap tieable objects in IO::Handle interface - - -<P><I>This is currently Alpha code, released for comments. - Please give me your feedback!</I> - - - -<P><HR> -<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> - - -<P>First of all, you'll need tie(), so: - -<FONT SIZE=3 FACE="courier"><PRE> - require 5.004; -</PRE></FONT> - -<P><I>Function interface (experimental).</I> -Use this with any existing class... - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::WrapTie; - use FooHandle; # implements TIEHANDLE interface - - # Suppose we want a "FooHandle->new(&FOO_RDWR, 2)". - # We can instead say... - - $FH = wraptie('FooHandle', &FOO_RDWR, 2); - - # Now we can use... - print $FH "Hello, "; # traditional operator syntax... - $FH->print("world!\n"); # ...and OO syntax as well! -</PRE></FONT> - -<P><I>OO interface (preferred).</I> -You can inherit from the IO::WrapTie::Slave mixin to get a -nifty <CODE>new_tie()</CODE> constructor... - -<FONT SIZE=3 FACE="courier"><PRE> - #------------------------------ - package FooHandle; # a class which can TIEHANDLE - - use IO::WrapTie; - @ISA = qw(IO::WrapTie::Slave); # inherit new_tie() - ... - - - #------------------------------ - package main; - - $FH = FooHandle->new_tie(&FOO_RDWR, 2); # $FH is an IO::WrapTie::Master - print $FH "Hello, "; # traditional operator syntax - $FH->print("world!\n"); # OO syntax -</PRE></FONT> - -<P>See IO::Scalar as an example. It also shows you how to create classes -which work both with and without 5.004. - - - -<P><HR> -<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> - - -<P>Suppose you have a class <CODE>FooHandle</CODE>, where... - - - -<UL> -<P><LI> -<P><B>FooHandle does not inherit from IO::Handle;</B> that is, it performs -filehandle-like I/O, but to something other than an underlying -file descriptor. Good examples are IO::Scalar (for printing to a -string) and IO::Lines (for printing to an array of lines). - -<P><LI> -<P><B>FooHandle implements the TIEHANDLE interface</B> (see <A HREF="perltie.pm.html">perltie</A>); -that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, -READ, and READLINE. - -<P><LI> -<P><B>FooHandle implements the traditional OO interface</B> of -FileHandle and IO::Handle; i.e., it contains methods like getline(), -read(), print(), seek(), tell(), eof(), etc. - -</UL> - - -<P>Normally, users of your class would have two options: - - - -<UL> -<P><LI> -<P><B>Use only OO syntax,</B> and forsake named I/O operators like 'print'. - -<P><LI> -<P><B>Use with tie,</B> and forsake treating it as a first-class object -(i.e., class-specific methods can only be invoked through the underlying -object via tied()... giving the object a "split personality"). - -</UL> - - -<P>But now with IO::WrapTie, you can say: - -<FONT SIZE=3 FACE="courier"><PRE> - $WT = wraptie('FooHandle', &FOO_RDWR, 2); - $WT->print("Hello, world\n"); # OO syntax - print $WT "Yes!\n"; # Named operator syntax too! - $WT->weird_stuff; # Other methods! -</PRE></FONT> - -<P>And if you're authoring a class like FooHandle, just have it inherit -from <CODE>IO::WrapTie::Slave</CODE> and that first line becomes even prettier: - -<FONT SIZE=3 FACE="courier"><PRE> - $WT = FooHandle->new_tie(&FOO_RDWR, 2); -</PRE></FONT> - -<P><B>The bottom line:</B> now, almost any class can look and work exactly like -an IO::Handle... and be used both with OO and non-OO filehandle syntax. - - - -<P><HR> -<A NAME="HOW_IT_ALL_WORKS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> HOW IT ALL WORKS</H2></A> - - - -<P><HR> -<A NAME="The_data_structures"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> The data structures</H3></A> - - -<P>Consider this example code, using classes in this distribution: - -<FONT SIZE=3 FACE="courier"><PRE> - use IO::Scalar; - use IO::WrapTie; - - $WT = wraptie('IO::Scalar',\$s); - print $WT "Hello, "; - $WT->print("world!\n"); -</PRE></FONT> - -<P>In it, the wraptie() function creates a data structure as follows: - -<FONT SIZE=3 FACE="courier"><PRE> - * $WT is a blessed reference to a tied filehandle - $WT glob; that glob is tied to the "Slave" object. - | * You would do all your i/o with $WT directly. - | - | - | ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle - V / - .-------------. - | | - | | * Perl i/o operators work on the tied object, - | "Master" | invoking the TIEHANDLE methods. - | | * Method invocations are delegated to the tied - | | slave. - `-------------' - | - tied(*$WT) | .---isa--> IO::WrapTie::Slave - V / - .-------------. - | | - | "Slave" | * Instance of FileHandle-like class which doesn't - | | actually use file descriptors, like IO::Scalar. - | IO::Scalar | * The slave can be any kind of object. - | | * Must implement the TIEHANDLE interface. - `-------------' -</PRE></FONT> - -<P><I>NOTE:</I> just as an IO::Handle is really just a blessed reference to a -<I>traditional</I> filehandle glob... so also, an IO::WrapTie::Master -is really just a blessed reference to a filehandle -glob <I>which has been tied to some "slave" class.</I> - - - -<P><HR> -<A NAME="How_wraptie_works"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How wraptie() works</H3></A> - - - -<OL> -<P><LI> -<P>The call to function <CODE>wraptie(SLAVECLASS, TIEARGS...)</CODE> is -passed onto <CODE>IO::WrapTie::Master::new()</CODE>. -Note that class IO::WrapTie::Master is a subclass of IO::Handle. - -<P><LI> -<P>The <CODE>IO::WrapTie::Master::new</CODE> method creates a new IO::Handle object, -reblessed into class IO::WrapTie::Master. This object is the <I>master</I>, -which will be returned from the constructor. At the same time... - -<P><LI> -<P>The <CODE>new</CODE> method also creates the <I>slave</I>: this is an instance -of SLAVECLASS which is created by tying the master's IO::Handle -to SLAVECLASS via <CODE>tie(HANDLE, SLAVECLASS, TIEARGS...)</CODE>. -This call to <CODE>tie()</CODE> creates the slave in the following manner: - -<P><LI> -<P>Class SLAVECLASS is sent the message <CODE>TIEHANDLE(TIEARGS...)</CODE>; it -will usually delegate this to <CODE>SLAVECLASS::new(TIEARGS...)</CODE>, resulting -in a new instance of SLAVECLASS being created and returned. - -<P><LI> -<P>Once both master and slave have been created, the master is returned -to the caller. - -</OL> - - - -<P><HR> -<A NAME="How_I_O_operators_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How I/O operators work (on the master)</H3></A> - - -<P>Consider using an i/o operator on the master: - -<FONT SIZE=3 FACE="courier"><PRE> - print $WT "Hello, world!\n"; -</PRE></FONT> - -<P>Since the master ($WT) is really a [blessed] reference to a glob, -the normal Perl i/o operators like <CODE>print</CODE> may be used on it. -They will just operate on the symbol part of the glob. - - -<P>Since the glob is tied to the slave, the slave's PRINT method -(part of the TIEHANDLE interface) will be automatically invoked. - - -<P>If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be -invoked, and that method happens to delegate to the <CODE>print()</CODE> method -of the same class. So the <I>real</I> work is ultimately done by -IO::Scalar::print(). - - - -<P><HR> -<A NAME="How_methods_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How methods work (on the master)</H3></A> - - -<P>Consider using a method on the master: - -<FONT SIZE=3 FACE="courier"><PRE> - $WT->print("Hello, world!\n"); -</PRE></FONT> - -<P>Since the master ($WT) is blessed into the class IO::WrapTie::Master, -Perl first attempts to find a <CODE>print()</CODE> method there. Failing that, -Perl next attempts to find a <CODE>print()</CODE> method in the superclass, -IO::Handle. It just so happens that there <I>is</I> such a method; -that method merely invokes the <CODE>print</CODE> i/o operator on the self object... -and for that, see above! - - -<P>But let's suppose we're dealing with a method which <I>isn't</I> part -of IO::Handle... for example: - -<FONT SIZE=3 FACE="courier"><PRE> - my $sref = $WT->sref; -</PRE></FONT> - -<P>In this case, the intuitive behavior is to have the master delegate the -method invocation to the slave (now do you see where the designations -come from?). This is indeed what happens: IO::WrapTie::Master contains -an AUTOLOAD method which performs the delegation. - - -<P>So: when <CODE>sref()</CODE> can't be found in IO::Handle, the AUTOLOAD method -of IO::WrapTie::Master is invoked, and the standard behavior of -delegating the method to the underlying slave (here, an IO::Scalar) -is done. - - -<P>Sometimes, to get this to work properly, you may need to create -a subclass of IO::WrapTie::Master which is an effective master for -<I>your</I> class, and do the delegation there. - - - -<P><HR> -<A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A> - - -<P><B>Why not simply use the object's OO interface?</B> - Because that means forsaking the use of named operators -like print(), and you may need to pass the object to a subroutine -which will attempt to use those operators: - -<FONT SIZE=3 FACE="courier"><PRE> - $O = FooHandle->new(&FOO_RDWR, 2); - $O->print("Hello, world\n"); # OO syntax is okay, BUT.... - - sub nope { print $_[0] "Nope!\n" } - X nope($O); # ERROR!!! (not a glob ref) - -</PRE></FONT> - -<P><B>Why not simply use tie()?</B> - Because (1) you have to use tied() to invoke methods in the -object's public interface (yuck), and (2) you may need to pass -the tied symbol to another subroutine which will attempt to treat -it in an OO-way... and that will break it: - -<FONT SIZE=3 FACE="courier"><PRE> - tie *T, 'FooHandle', &FOO_RDWR, 2; - print T "Hello, world\n"; # Operator is okay, BUT... - - tied(*T)->other_stuff; # yuck! AND... - - sub nope { shift->print("Nope!\n") } - X nope(\*T); # ERROR!!! (method "print" on unblessed ref) -</PRE></FONT> - -<P><B>Why a master and slave? - Why not simply write FooHandle to inherit from IO::Handle?</B> - I tried this, with an implementation similar to that of IO::Socket. -The problem is that <I>the whole point is to use this with objects -that don't have an underlying file/socket descriptor.</I>. -Subclassing IO::Handle will work fine for the OO stuff, and fine with -named operators <I>if</I> you tie()... but if you just attempt to say: - -<FONT SIZE=3 FACE="courier"><PRE> - $IO = FooHandle->new(&FOO_RDWR, 2); - print $IO "Hello!\n"; -</PRE></FONT> - -<P>you get a warning from Perl like: - -<FONT SIZE=3 FACE="courier"><PRE> - Filehandle GEN001 never opened -</PRE></FONT> - -<P>because it's trying to do system-level i/o on an (unopened) file -descriptor. To avoid this, you apparently have to tie() the handle... -which brings us right back to where we started! At least the -IO::WrapTie mixin lets us say: - -<FONT SIZE=3 FACE="courier"><PRE> - $IO = FooHandle->new_tie(&FOO_RDWR, 2); - print $IO "Hello!\n"; -</PRE></FONT> - -<P>and so is not <I>too</I> bad. <CODE>:-)</CODE> - - - -<P><HR> -<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A> - - -<P>Remember: this stuff is for doing FileHandle-like i/o on things -<I>without underlying file descriptors</I>. If you have an underlying -file descriptor, you're better off just inheriting from IO::Handle. - - -<P><B>Be aware that new_tie() always returns an instance of a -kind of IO::WrapTie::Master...</B> it does <B>not</B> return an instance -of the i/o class you're tying to! - - -<P>Invoking some methods on the master object causes AUTOLOAD to delegate -them to the slave object... so it <I>looks</I> like you're manipulating a -"FooHandle" object directly, but you're not. - - -<P>I have not explored all the ramifications of this use of tie(). -<I>Here there be dragons</I>. - - - -<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 Thu Sep 28 02:36:03 2000 by cvu_pod2html -</FONT></ADDRESS> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif b/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif Binary files differdeleted file mode 100644 index 86986436..00000000 --- a/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif +++ /dev/null diff --git a/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif b/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif Binary files differdeleted file mode 100644 index d26510cd..00000000 --- a/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif +++ /dev/null diff --git a/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif b/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif Binary files differdeleted file mode 100644 index f6001a5f..00000000 --- a/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif +++ /dev/null diff --git a/cpan/dist/IO-stringy/docs/index-menu.html b/cpan/dist/IO-stringy/docs/index-menu.html deleted file mode 100644 index 890a1f6a..00000000 --- a/cpan/dist/IO-stringy/docs/index-menu.html +++ /dev/null @@ -1,31 +0,0 @@ -<HTML> -<HEAD> -<TITLE>perlmod</TITLE> -</HEAD> -<BODY BGCOLOR="#FFFFFF" LINK="#CC3366" ALINK="#FF6666" VLINK="#993366"> -<FONT FACE="sans-serif"><TABLE> - -<TR VALIGN="TOP"><TH ALIGN="LEFT"><FONT FACE="sans-serif"><B>Overview</B></FONT></TH> -<TR VALIGN="TOP"><TD><A HREF="IO/Stringy.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::Stringy</FONT></A></TD></TR> -</TABLE> -<HR> -<TABLE> - -<TR VALIGN="TOP"><TH ALIGN="LEFT"><FONT FACE="sans-serif"><B>Modules</B></FONT></TH> -<TR VALIGN="TOP"><TD><A HREF="IO/AtomicFile.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::AtomicFile</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/InnerFile.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::InnerFile</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/Lines.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::Lines</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/Scalar.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::Scalar</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/ScalarArray.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::ScalarArray</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/Wrap.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::Wrap</FONT></A></TD></TR> - -<TR VALIGN="TOP"><TD><A HREF="IO/WrapTie.pm.html" TARGET="perlmod.content"><FONT SIZE="-1" FACE="sans-serif">IO::WrapTie</FONT></A></TD></TR> -</TABLE> -<HR> -</FONT></BODY> -</HTML> diff --git a/cpan/dist/IO-stringy/docs/index.html b/cpan/dist/IO-stringy/docs/index.html deleted file mode 100644 index bac53b82..00000000 --- a/cpan/dist/IO-stringy/docs/index.html +++ /dev/null @@ -1,13 +0,0 @@ -<HEAD> -<TITLE>perlmod</TITLE> -</HEAD> -<FRAMESET COLS="20%,*" BORDER=1 FRAMEBORDER=1 FRAMESPACING=10> - <FRAME NAME="perlmod.menu" SRC="index-menu.html"> - <FRAME NAME="perlmod.content" SRC="IO/Stringy.pm.html"> -</FRAMESET> - -<NOFRAMES> - <BODY> - Go <A HREF="menu.html">here</A> - </BODY> -</NOFRAMES> diff --git a/cpan/dist/IO-stringy/docs/index.menu b/cpan/dist/IO-stringy/docs/index.menu deleted file mode 100644 index 92466a8e..00000000 --- a/cpan/dist/IO-stringy/docs/index.menu +++ /dev/null @@ -1,30 +0,0 @@ -MENU perlmod - -SECTION Overview - -ITEM IO::Stringy -HREF IO/Stringy.pm.html - -SECTION Modules - -ITEM IO::AtomicFile -HREF IO/AtomicFile.pm.html - -ITEM IO::InnerFile -HREF IO/InnerFile.pm.html - -ITEM IO::Lines -HREF IO/Lines.pm.html - -ITEM IO::Scalar -HREF IO/Scalar.pm.html - -ITEM IO::ScalarArray -HREF IO/ScalarArray.pm.html - -ITEM IO::Wrap -HREF IO/Wrap.pm.html - -ITEM IO::WrapTie -HREF IO/WrapTie.pm.html - diff --git a/cpan/dist/IO-stringy/lib/IO/AtomicFile.pm b/cpan/dist/IO-stringy/lib/IO/AtomicFile.pm deleted file mode 100644 index 90bfce39..00000000 --- a/cpan/dist/IO-stringy/lib/IO/AtomicFile.pm +++ /dev/null @@ -1,190 +0,0 @@ -package IO::AtomicFile; - -### DOCUMENTATION AT BOTTOM OF FILE - -# Be strict: -use strict; - -# External modules: -use IO::File; - - -#------------------------------ -# -# GLOBALS... -# -#------------------------------ -use vars qw($VERSION @ISA); - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.105 $, 10; - -# Inheritance: -@ISA = qw(IO::File); - - -#------------------------------ -# new ARGS... -#------------------------------ -# Class method, constructor. -# Any arguments are sent to open(). -# -sub new { - my $class = shift; - my $self = $class->SUPER::new(); - ${*$self}{'io_atomicfile_suffix'} = ''; - $self->open(@_) if @_; - $self; -} - -#------------------------------ -# DESTROY -#------------------------------ -# Destructor. -# -sub DESTROY { - shift->close(1); # like close, but raises fatal exception on failure -} - -#------------------------------ -# open PATH, MODE -#------------------------------ -# Class/instance method. -# -sub open { - my ($self, $path, $mode) = @_; - ref($self) or $self = $self->new; # now we have an instance! - - # Create tmp path, and remember this info: - my $temp = "${path}..TMP" . ${*$self}{'io_atomicfile_suffix'}; - ${*$self}{'io_atomicfile_temp'} = $temp; - ${*$self}{'io_atomicfile_path'} = $path; - - # Open the file! Returns filehandle on success, for use as a constructor: - $self->SUPER::open($temp, $mode) ? $self : undef; -} - -#------------------------------ -# _closed [YESNO] -#------------------------------ -# Instance method, private. -# Are we already closed? Argument sets new value, returns previous one. -# -sub _closed { - my $self = shift; - my $oldval = ${*$self}{'io_atomicfile_closed'}; - ${*$self}{'io_atomicfile_closed'} = shift if @_; - $oldval; -} - -#------------------------------ -# close -#------------------------------ -# Instance method. -# Close the handle, and rename the temp file to its final name. -# -sub close { - my ($self, $die) = @_; - unless ($self->_closed(1)) { # sentinel... - $self->SUPER::close(); - rename(${*$self}{'io_atomicfile_temp'}, - ${*$self}{'io_atomicfile_path'}) - or ($die ? die "close atomic file: $!\n" : return undef); - } - 1; -} - -#------------------------------ -# delete -#------------------------------ -# Instance method. -# Close the handle, and delete the temp file. -# -sub delete { - my $self = shift; - unless ($self->_closed(1)) { # sentinel... - $self->SUPER::close(); - return unlink(${*$self}{'io_atomicfile_temp'}); - } - 1; -} - -#------------------------------ -# detach -#------------------------------ -# Instance method. -# Close the handle, but DO NOT delete the temp file. -# -sub detach { - my $self = shift; - $self->SUPER::close() unless ($self->_closed(1)); - 1; -} - -#------------------------------ -1; -__END__ - - -=head1 NAME - -IO::AtomicFile - write a file which is updated atomically - - -=head1 SYNOPSIS - - use IO::AtomicFile; - - # Write a temp file, and have it install itself when closed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->close || die "couldn't install atomic file: $!"; - - # Write a temp file, but delete it before it gets installed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->delete; - - # Write a temp file, but neither install it nor delete it: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->detach; - - -=head1 DESCRIPTION - -This module is intended for people who need to update files -reliably in the face of unexpected program termination. - -For example, you generally don't want to be halfway in the middle of -writing I</etc/passwd> and have your program terminate! Even -the act of writing a single scalar to a filehandle is I<not> atomic. - -But this module gives you true atomic updates, via rename(). -When you open a file I</foo/bar.dat> via this module, you are I<actually> -opening a temporary file I</foo/bar.dat..TMP>, and writing your -output there. The act of closing this file (either explicitly -via close(), or implicitly via the destruction of the object) -will cause rename() to be called... therefore, from the point -of view of the outside world, the file's contents are updated -in a single time quantum. - -To ensure that problems do not go undetected, the "close" method -done by the destructor will raise a fatal exception if the rename() -fails. The explicit close() just returns undef. - -You can also decide at any point to trash the file you've been -building. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head1 REVISION - -$Revision: 1.105 $ - -=cut diff --git a/cpan/dist/IO-stringy/lib/IO/InnerFile.pm b/cpan/dist/IO-stringy/lib/IO/InnerFile.pm deleted file mode 100644 index 4eca6d44..00000000 --- a/cpan/dist/IO-stringy/lib/IO/InnerFile.pm +++ /dev/null @@ -1,274 +0,0 @@ -package IO::InnerFile; - -=head1 NAME - -IO::InnerFile - define a file inside another file - - -=head1 SYNOPSIS - - - ### Read a subset of a file: - $inner = IO::InnerFile->new($fh, $start, $length); - while (<$inner>) { - ... - } - - -=head1 DESCRIPTION - -If you have a filehandle that can seek() and tell(), then you -can open an IO::InnerFile on a range of the underlying file. - - -=head1 PUBLIC INTERFACE - -=over - -=cut - -use Symbol; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.103 $, 10; - -#------------------------------ - -=item new FILEHANDLE, [START, [LENGTH]] - -I<Class method, constructor.> -Create a new inner-file opened on the given FILEHANDLE, -from bytes START to START+LENGTH. Both START and LENGTH -default to 0; negative values are silently coerced to zero. - -Note that FILEHANDLE must be able to seek() and tell(), in addition -to whatever other methods you may desire for reading it. - -=cut - -sub new { - my ($class, $fh, $start, $lg) = @_; - $start = 0 if (!$start or ($start < 0)); - $lg = 0 if (!$lg or ($lg < 0)); - - ### Create the underlying "object": - my $a = { - FH => $fh, - CRPOS => 0, - START => $start, - LG => $lg, - }; - - ### Create a new filehandle tied to this object: - $fh = gensym; - tie(*$fh, $class, $a); - return bless($fh, $class); -} - -sub TIEHANDLE { - my ($class, $data) = @_; - return bless($data, $class); -} - -sub DESTROY { - my ($self) = @_; - $self->close() if (ref($self) eq 'SCALAR'); -} - -#------------------------------ - -=item set_length LENGTH - -=item get_length - -=item add_length NBYTES - -I<Instance methods.> -Get/set the virtual length of the inner file. - -=cut - -sub set_length { tied(${$_[0]})->{LG} = $_[1]; } -sub get_length { tied(${$_[0]})->{LG}; } -sub add_length { tied(${$_[0]})->{LG} += $_[1]; } - -#------------------------------ - -=item set_start START - -=item get_start - -=item add_start NBYTES - -I<Instance methods.> -Get/set the virtual start position of the inner file. - -=cut - -sub set_start { tied(${$_[0]})->{START} = $_[1]; } -sub get_start { tied(${$_[0]})->{START}; } -sub set_end { tied(${$_[0]})->{LG} = $_[1] - tied(${$_[0]})->{START}; } -sub get_end { tied(${$_[0]})->{LG} + tied(${$_[0]})->{START}; } - - -#------------------------------ - -=item binmode - -=item close - -=item flush - -=item getc - -=item getline - -=item print LIST - -=item printf LIST - -=item read BUF, NBYTES - -=item readline - -=item seek OFFFSET, WHENCE - -=item tell - -=item write ARGS... - -I<Instance methods.> -Standard filehandle methods. - -=cut - -sub write { shift->WRITE(@_) } -sub print { shift->PRINT(@_) } -sub printf { shift->PRINTF(@_) } -sub flush { 1; } -sub binmode { 1; } -sub getc { return GETC(tied(${$_[0]}) ); } -sub read { return READ( tied(${$_[0]}), @_[1,2,3] ); } -sub readline { return READLINE( tied(${$_[0]}) ); } -sub getline { return READLINE( tied(${$_[0]}) ); } -sub close { return CLOSE(tied(${$_[0]}) ); } - -sub seek { - my ($self, $ofs, $whence) = @_; - $self = tied( $$self ); - - $self->{CRPOS} = $ofs if ($whence == 0); - $self->{CRPOS}+= $ofs if ($whence == 1); - $self->{CRPOS} = $self->{LG} + $ofs if ($whence == 2); - - $self->{CRPOS} = 0 if ($self->{CRPOS} < 0); - $self->{CRPOS} = $self->{LG} if ($self->{CRPOS} > $self->{LG}); -} - -sub tell { - return tied(${$_[0]})->{CRPOS}; -} - -sub WRITE { - die "inner files can only open for reading\n"; -} - -sub PRINT { - die "inner files can only open for reading\n"; -} - -sub PRINTF { - die "inner files can only open for reading\n"; -} - -sub GETC { - my ($self) = @_; - return 0 if ($self->{CRPOS} >= $self->{LG}); - - my $data; - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - my $lg = $self->{FH}->read($data, 1); - $self->{CRPOS} += $lg; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - $self->{LG} = $self->{CRPOS} unless ($lg); - return ($lg ? $data : undef); -} - -sub READ { - my ($self, $undefined, $lg, $ofs) = @_; - $undefined = undef; - - return 0 if ($self->{CRPOS} >= $self->{LG}); - $lg = $self->{LG} - $self->{CRPOS} if ($self->{CRPOS} + $lg > $self->{LG}); - return 0 unless ($lg); - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - $lg = $self->{FH}->read($_[1], $lg, $_[3] ); - $self->{CRPOS} += $lg; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - $self->{LG} = $self->{CRPOS} unless ($lg); - return $lg; -} - -sub READLINE { - my ($self) = @_; - return undef if ($self->{CRPOS} >= $self->{LG}); - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - my $text = $self->{FH}->getline; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - #### If we detected a new EOF ... - unless (defined $text) { - $self->{LG} = $self->{CRPOS}; - return undef; - } - - my $lg=length($text); - - $lg = $self->{LG} - $self->{CRPOS} if ($self->{CRPOS} + $lg > $self->{LG}); - $self->{CRPOS} += $lg; - - return substr($text, 0,$lg); -} - -sub CLOSE { %{$_[0]}=(); } - - - -1; -__END__ - -=back - - -=head1 AUTHOR - -Original version by Doru Petrescu (pdoru@kappa.ro). - -Documentation and current maintenance by Eryq (eryq@zeegee.com). - -=cut - - diff --git a/cpan/dist/IO-stringy/lib/IO/Lines.pm b/cpan/dist/IO-stringy/lib/IO/Lines.pm deleted file mode 100644 index 50b67304..00000000 --- a/cpan/dist/IO-stringy/lib/IO/Lines.pm +++ /dev/null @@ -1,148 +0,0 @@ -package IO::Lines; - - -=head1 NAME - -IO::Lines - IO:: interface for reading/writing an array of lines - - -=head1 SYNOPSIS - - use IO::Lines; - - # See IO::ScalarArray for details - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) an array of lines. They can be tiehandle'd as well. - -This is a subclass of L<IO::ScalarArray|IO::ScalarArray> -in which the underlying -array has its data stored in a line-oriented-format: that is, -every element ends in a C<"\n">, with the possible exception of the -final element. This makes C<getline()> I<much> more efficient; -if you plan to do line-oriented reading/printing, you want this class. - -The C<print()> method will enforce this rule, so you can print -arbitrary data to the line-array: it will break the data at -newlines appropriately. - -See L<IO::ScalarArray> for full usage. - -=cut - -use Carp; -use strict; -use IO::ScalarArray; -use vars qw($VERSION @ISA); - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.110 $, 10; - -# Inheritance: -@ISA = qw(IO::ScalarArray); # also gets us new_tie :-) - - -#------------------------------ -# getline -#------------------------------ -# Instance method, override. -# Return the next line, or undef on end of data. -# Can safely be called in an array context. -# Currently, lines are delimited by "\n". -# -sub getline { - my $self = shift; - if (!defined $/) { - return join( '' => $self->getlines ); - } - ($/ eq "\n") - or croak '$/ must be "\n" or undef, not ', "'$/'."; - - if (!$self->{Pos}) { # full line... - return $self->{AR}[$self->{Str}++]; - } - else { # partial line... - my $partial = substr($self->{AR}[$self->{Str}++], $self->{Pos}); - $self->{Pos} = 0; - return $partial; - } -} - -#------------------------------ -# getlines -#------------------------------ -# Instance method, override. -# Return an array comprised of the remaining lines, or () on end of data. -# Must be called in an array context. -# Currently, lines are delimited by "\n". -# -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - - my ($rArray, $Str, $Pos) = @$self{ qw( AR Str Pos ) }; - my @partial = (); - - if ($Pos) { # partial line... - @partial = (substr( $rArray->[ $Str++ ], $Pos )); - $self->{Pos} = 0; - } - $self->{Str} = scalar @$rArray; # about to exhaust @$rArray - return (@partial, - @$rArray[ $Str .. $#$rArray ]); # remaining full lines... -} - -#------------------------------ -# print ARGS... -#------------------------------ -# Instance method, override. -# Print ARGS to the underlying line array. -# -sub print { - my $self = shift; - ### print STDERR "\n[[ARRAY WAS...\n", @{$self->{AR}}, "<<EOF>>\n"; - my @lines = split /^/, join('', @_); @lines or return 1; - - # Did the previous print not end with a newline? If so, append first line: - if (@{$self->{AR}} and ($self->{AR}[-1] !~ /\n\Z/)) { - $self->{AR}[-1] .= shift @lines; - } - push @{$self->{AR}}, @lines; # add the remainder - ### print STDERR "\n[[ARRAY IS NOW...\n", @{$self->{AR}}, "<<EOF>>\n"; - 1; -} - -#------------------------------ -1; - -__END__ - - -=head1 VERSION - -$Id: Lines.pm,v 1.110 2000/08/16 04:59:02 eryq Exp $ - - -=head1 AUTHORS - - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Morris M. Siegel,> -for his $/ patch and the new C<getlines()>. - -=cut - diff --git a/cpan/dist/IO-stringy/lib/IO/Scalar.pm b/cpan/dist/IO-stringy/lib/IO/Scalar.pm deleted file mode 100644 index 6287b5fb..00000000 --- a/cpan/dist/IO-stringy/lib/IO/Scalar.pm +++ /dev/null @@ -1,585 +0,0 @@ -package IO::Scalar; - - -=head1 NAME - -IO::Scalar - IO:: interface for reading/writing a scalar - - -=head1 SYNOPSIS - -If you have any Perl5, you can use the basic OO interface... - - use IO::Scalar; - - ### Open a handle on a string: - $SH = new IO::Scalar; - $SH->open(\$somestring); - - ### Open a handle on a string, read it line-by-line, then close it: - $SH = new IO::Scalar \$somestring; - while ($_ = $SH->getline) { print "Line: $_" } - $SH->close; - - ### Open a handle on a string, and slurp in all the lines: - $SH = new IO::Scalar \$somestring; - print $SH->getlines; - - ### Open a handle on a string, and append to it: - $SH = new IO::Scalar \$somestring - $SH->print("bar\n"); ### will add "bar\n" to the end - - ### Get the current position: - $pos = $SH->getpos; ### $SH->tell() also works - - ### Set the current position: - $SH->setpos($pos); ### $SH->seek(POS,WHENCE) also works - - ### Open an anonymous temporary scalar: - $SH = new IO::Scalar; - $SH->print("Hi there!"); - print "I got: ", ${$SH->sref}, "\n"; ### get at value - -If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write scalars just like files: - - use IO::Scalar; - - ### Writing to a scalar... - my $s; - tie *OUT, 'IO::Scalar', \$s; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... $s\n" - - ### Reading and writing an anonymous scalar... - tie *OUT, 'IO::Scalar'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } - -Stringification now works, too! - - my $SH = new IO::Scalar \$somestring; - $SH->print("Hello, "); - $SH->print("world!"); - print "I've got: <$SH>\n"; - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - -Basically, this: - - my $s; - $SH = new IO::Scalar \$s; - $SH->print("Hel", "lo, "); # OO style - $SH->print("world!\n"); # ditto - -Or this (if you have 5.004 or later): - - my $s; - $SH = tie *OUT, 'IO::Scalar', \$s; - print OUT "Hel", "lo, "; # non-OO style - print OUT "world!\n"; # ditto - -Or this (if you have 5.004 or later): - - my $s; - $SH = IO::Scalar->new_tie(\$s); - $SH->print("Hel", "lo, "); # OO style... - print $SH "world!\n"; # ...or non-OO style! - -Causes $s to be set to: - - "Hello, world!\n" - - -=head1 PUBLIC INTERFACE - -=cut - -use Carp; -use strict; -use vars qw($VERSION @ISA); -use IO::Handle; - -### Stringification, courtesy of B. K. Oxley (binkley): :-) -use overload '""' => sub { ${$_[0]->{SR}} }; -use overload 'bool' => sub { 1 }; ### have to do this, so object is true! - -### The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.122 $, 10; - -### Inheritance: -@ISA = qw(IO::Handle); -require IO::WrapTie and push @ISA, 'IO::WrapTie::Slave' if ($] >= 5.004); - - -#============================== - -=head2 Construction - -=over 4 - -=cut - -#------------------------------ - -=item new [ARGS...] - -I<Class method.> -Return a new, unattached scalar handle. -If any arguments are given, they're sent to open(). - -=cut - -sub new { - my $self = bless {}, shift; - $self->open(@_) if @_; - $self; -} -sub DESTROY { - shift->close; -} - -#------------------------------ - -=item open [SCALARREF] - -I<Instance method.> -Open the scalar handle on a new scalar, pointed to by SCALARREF. -If no SCALARREF is given, a "private" scalar is created to hold -the file data. - -Returns the self object on success, undefined on error. - -=cut - -sub open { - my ($self, $sref) = @_; - - # Sanity: - defined($sref) or do {my $s = ''; $sref = \$s}; - (ref($sref) eq "SCALAR") or croak "open() needs a ref to a scalar"; - - # Setup: - $self->{Pos} = 0; - $self->{SR} = $sref; - $self; -} - -#------------------------------ - -=item opened - -I<Instance method.> -Is the scalar handle opened on something? - -=cut - -sub opened { - shift->{SR}; -} - -#------------------------------ - -=item close - -I<Instance method.> -Disassociate the scalar handle from its underlying scalar. -Done automatically on destroy. - -=cut - -sub close { - my $self = shift; - %$self = (); - 1; -} - -=back - -=cut - - - -#============================== - -=head2 Input and output - -=over 4 - -=cut - - -#------------------------------ - -=item flush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub flush {} - -#------------------------------ - -=item getc - -I<Instance method.> -Return the next character, or undef if none remain. - -=cut - -sub getc { - my $self = shift; - - # Return undef right away if at EOF; else, move pos forward: - return undef if $self->eof; - substr(${$self->{SR}}, $self->{Pos}++, 1); -} - -#------------------------------ - -=item getline - -I<Instance method.> -Return the next line, or undef on end of string. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -=cut - -sub getline { - my $self = shift; - - # Return undef right away if at EOF: - return undef if $self->eof; - - # Get next line: - my $sr = $self->{SR}; - my $i = $self->{Pos}; # Start matching at this point. - my $len = length(${$sr}); - for (; $i < $len; ++$i) { - last if ord (substr (${$sr}, $i, 1)) == 10; - } - - # Extract the line: - my $line; - if ($i < $len) { - $line = substr (${$sr}, $self->{Pos}, $i - $self->{Pos} + 1); - $self->{Pos} = $i+1; # Remember where we finished up. - } - else { - $line = substr (${$sr}, $self->{Pos}, $i - $self->{Pos}); - $self->{Pos} = $len; - } - return $line; -} - -#------------------------------ - -=item getlines - -I<Instance method.> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -=cut - -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my ($line, @lines); - push @lines, $line while (defined($line = $self->getline)); - @lines; -} - -#------------------------------ - -=item print ARGS... - -I<Instance method.> -Print ARGS to the underlying scalar. - -B<Warning:> Currently, this always causes a "seek to the end of the string"; -this may change in the future. - -=cut - -sub print { - my $self = shift; - ${$self->{SR}} .= join('', @_); - $self->{Pos} = length(${$self->{SR}}); - 1; -} - -#------------------------------ - -=item read BUF, NBYTES, [OFFSET] - -I<Instance method.> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub read { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $read = substr(${$self->{SR}}, $self->{Pos}, $n); - $n = length($read); - $self->{Pos} += $n; - ($off ? substr($_[1], $off) : $_[1]) = $read; - return $n; -} - -#------------------------------ - -=item write BUF, NBYTES, [OFFSET] - -I<Instance method.> -Write some bytes to the scalar. - -=cut - -sub write { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $data = substr($_[1], $off, $n); - $n = length($data); - $self->print($data); - return $n; -} - -#------------------------------ - -=item sysread BUF, LEN, [OFFSET] - -I<Instance method.> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub sysread { - my $self = shift; - $self->read (@_); -} - -#------------------------------ - -=item syswrite BUF, NBYTES, [OFFSET] - -I<Instance method.> -Write some bytes to the scalar. - -=cut - -sub syswrite { - my $self = shift; - $self->write (@_); -} - -=back - -=cut - - -#============================== - -=head2 Seeking/telling and other attributes - -=over 4 - -=cut - - -#------------------------------ - -=item autoflush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub autoflush {} - -#------------------------------ - -=item binmode - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub binmode {} - -#------------------------------ - -=item clearerr - -I<Instance method.> Clear the error and EOF flags. A no-op. - -=cut - -sub clearerr { 1 } - -#------------------------------ - -=item eof - -I<Instance method.> Are we at end of file? - -=cut - -sub eof { - my $self = shift; - ($self->{Pos} >= length(${$self->{SR}})); -} - -#------------------------------ - -=item seek OFFSET, WHENCE - -I<Instance method.> Seek to a given position in the stream. - -=cut - -sub seek { - my ($self, $pos, $whence) = @_; - my $eofpos = length(${$self->{SR}}); - - # Seek: - if ($whence == 0) { $self->{Pos} = $pos } # SEEK_SET - elsif ($whence == 1) { $self->{Pos} += $pos } # SEEK_CUR - elsif ($whence == 2) { $self->{Pos} = $eofpos + $pos} # SEEK_END - else { croak "bad seek whence ($whence)" } - - # Fixup: - if ($self->{Pos} < 0) { $self->{Pos} = 0 } - if ($self->{Pos} > $eofpos) { $self->{Pos} = $eofpos } - 1; -} - -#------------------------------ - -=item tell - -I<Instance method.> -Return the current position in the stream, as a numeric offset. - -=cut - -sub tell { shift->{Pos} } - -#------------------------------ - -=item setpos POS - -I<Instance method.> -Set the current position, using the opaque value returned by C<getpos()>. - -=cut - -sub setpos { shift->seek($_[0],0) } - -#------------------------------ - -=item getpos - -I<Instance method.> -Return the current position in the string, as an opaque object. - -=cut - -*getpos = \&tell; - - -#------------------------------ - -=item sref - -I<Instance method.> -Return a reference to the underlying scalar. - -=cut - -sub sref { shift->{SR} } - - -#------------------------------ -# Tied handle methods... -#------------------------------ - -# Conventional tiehandle interface: -sub TIEHANDLE { shift->new(@_) } -sub GETC { shift->getc(@_) } -sub PRINT { shift->print(@_) } -sub PRINTF { shift->print(sprintf(shift, @_)) } -sub READ { shift->read(@_) } -sub READLINE { wantarray ? shift->getlines(@_) : shift->getline(@_) } -sub WRITE { shift->write(@_); } -sub CLOSE { shift->close(@_); } - -#------------------------------------------------------------ - -1; - -__END__ - - - -=back - -=cut - -=head1 VERSION - -$Id: Scalar.pm,v 1.122 2000/09/28 06:32:28 eryq Exp $ - - -=head1 AUTHORS - - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -The full set of contributors always includes the folks mentioned -in L<IO::Stringy/"CHANGE LOG">. But just the same, special -thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Andy Glew,> -for contributing C<getc()>. - -I<Brandon Browning,> -for suggesting C<opened()>. - -I<David Richter,> -for finding and fixing the bug in C<PRINTF()>. - -I<Eric L. Brine,> -for his offset-using read() and write() implementations. - -I<Richard Jones> (F<rich@annexia.org>), -for his patches to massively improve the performance of C<getline()> -and add C<sysread> and C<syswrite>. - - -=cut diff --git a/cpan/dist/IO-stringy/lib/IO/ScalarArray.pm b/cpan/dist/IO-stringy/lib/IO/ScalarArray.pm deleted file mode 100644 index 7dec117b..00000000 --- a/cpan/dist/IO-stringy/lib/IO/ScalarArray.pm +++ /dev/null @@ -1,598 +0,0 @@ -package IO::ScalarArray; - - -=head1 NAME - -IO::ScalarArray - IO:: interface for reading/writing an array of scalars - - -=head1 SYNOPSIS - -If you have any Perl5, you can use the basic OO interface... - - use IO::ScalarArray; - - # Open a handle on an array-of-scalars: - $AH = new IO::ScalarArray; - $AH->open(\@a); - - # Open a handle on an array-of-scalars, read it line-by-line, - # then close it: - $AH = new IO::ScalarArray \@a; - while ($_ = $AH->getline) { print "Line: $_" } - $AH->close; - - # Open a handle on an array-of-scalars, and slurp in all the lines: - $AH = new IO::ScalarArray \@a; - print $AH->getlines; - - # Open a handle on an array-of-scalars, and append to it: - $AH = new IO::ScalarArray \@a; - $AH->print("bar\n"); - print "some string is now: ", $somestring, "\n"; - - # Get the current position: - $pos = $AH->getpos; ### $AH->tell() also works - - # Set the current position: - $AH->setpos($pos); ### $AH->seek(POS,WHENCE) also works - - # Open an anonymous temporary scalar array: - $AH = new IO::ScalarArray; - $AH->print("Hi there!\nHey there!\n"); - $AH->print("Ho there!\n"); - print "I got: ", @{$AH->aref}, "\n"; ### get at value - -If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write as array-of-scalars just like files: - - use IO::ScalarArray; - - # Writing to a scalar array... - my @a; - tie *OUT, 'IO::ScalarArray', \@a; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... [", join('', @a), "]\n"; - - # Reading and writing an anonymous scalar array... - tie *OUT, 'IO::ScalarArray'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - -For writing large amounts of data with individual print() statements, -this is likely to be more efficient than IO::Scalar. - -Basically, this: - - my @a; - $AH = new IO::ScalarArray \@a; - $AH->print("Hel", "lo, "); - $AH->print("world!\n"); - -Or this (if you have 5.004 or later): - - my @a; - $AH = tie *OUT, 'IO::ScalarArray', \@a; - print OUT "Hel", "lo, "; - print OUT "world!\n"; - -Causes @a to be set to the following arrayt of 3 strings: - - ( "Hel" , - "lo, " , - "world!\n" ) - -Compare this with IO::Scalar. - - -=head1 PUBLIC INTERFACE - -=cut - -use Carp; -use strict; -use vars qw($VERSION @ISA); -use IO::Handle; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.117 $, 10; - -# Inheritance: -@ISA = qw(IO::Handle); -require IO::WrapTie and push @ISA, 'IO::WrapTie::Slave' if ($] >= 5.004); - - -#============================== - -=head2 Construction - -=over 4 - -=cut - -#------------------------------ - -=item new [ARGS...] - -I<Class method.> -Return a new, unattached array handle. -If any arguments are given, they're sent to open(). - -=cut - -sub new { - my $self = bless {}, shift; - $self->open(@_) if @_; - $self; -} -sub DESTROY { - shift->close; -} - - -#------------------------------ - -=item open [ARRAYREF] - -I<Instance method.> -Open the array handle on a new array, pointed to by ARRAYREF. -If no ARRAYREF is given, a "private" array is created to hold -the file data. - -Returns the self object on success, undefined on error. - -=cut - -sub open { - my ($self, $aref) = @_; - - # Sanity: - defined($aref) or do {my @a; $aref = \@a}; - (ref($aref) eq "ARRAY") or croak "open needs a ref to a array"; - - # Setup: - $self->setpos([0,0]); - $self->{AR} = $aref; - $self; -} - -#------------------------------ - -=item opened - -I<Instance method.> -Is the array handle opened on something? - -=cut - -sub opened { - shift->{AR}; -} - -#------------------------------ - -=item close - -I<Instance method.> -Disassociate the array handle from its underlying array. -Done automatically on destroy. - -=cut - -sub close { - my $self = shift; - %$self = (); - 1; -} - -=back - -=cut - - - -#============================== - -=head2 Input and output - -=over 4 - -=cut - -#------------------------------ - -=item flush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub flush {} - -#------------------------------ - -=item getc - -I<Instance method.> -Return the next character, or undef if none remain. -This does a read(1), which is somewhat costly. - -=cut - -sub getc { - my $buf = ''; - ($_[0]->read($buf, 1) ? $buf : undef); -} - -#------------------------------ - -=item getline - -I<Instance method.> -Return the next line, or undef on end of data. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -=cut - -sub getline { - my $self = shift; - my ($str, $line) = (undef, ''); - - # Until we hit EOF (or exitted because of a found line): - until ($self->eof) { - # If at end of current string, go forward to next one (won't be EOF): - if ($self->_eos) {++$self->{Str}, $self->{Pos}=0}; - - # Get ref to current string in array, and set internal pos marker: - $str = \($self->{AR}[$self->{Str}]); # get current string - pos($$str) = $self->{Pos}; # start matching at this point - - # Get from here to either newline or end of string, and add to line: - $$str =~ m/\G(.*?)((\n)|\Z)/g; # match to 1st newline or EOS - $line .= $1.$2; # add it - $self->{Pos} += length($1.$2); # move forward by amount matched - return $line if $3; # done, got a line with "\n" - } - return ($line eq '') ? undef : $line; # return undef if EOF -} - -#------------------------------ - -=item getlines - -I<Instance method.> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -=cut - -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my ($line, @lines); - push @lines, $line while (defined($line = $self->getline)); - @lines; -} - -#------------------------------ - -=item print ARGS... - -I<Instance method.> -Print ARGS to the underlying array. - -Currently, this always causes a "seek to the end of the array" -and generates a new array entry. This may change in the future. - -=cut - -sub print { - my $self = shift; - push @{$self->{AR}}, join('', @_); # add the data - $self->setpos([scalar(@{$self->{AR}}), 0]); - 1; -} - -#------------------------------ - -=item read BUF, NBYTES, [OFFSET]; - -I<Instance method.> -Read some bytes from the array. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub read { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - ### print "getline\n"; - my $justread; - my $len; - ($off ? substr($_[1], $off) : $_[1]) = ''; - - # Stop when we have zero bytes to go, or when we hit EOF: - until (!$n or $self->eof) { - # If at end of current string, go forward to next one (won't be EOF): - if ($self->_eos) { - ++$self->{Str}; - $self->{Pos} = 0; - } - - # Get longest possible desired substring of current string: - $justread = substr($self->{AR}[$self->{Str}], $self->{Pos}, $n); - $len = length($justread); - $_[1] .= $justread; - $n -= $len; - $self->{Pos} += $len; - } - return length($_[1])-$off; -} - -#------------------------------ - -=item write BUF, NBYTES, [OFFSET]; - -I<Instance method.> -Write some bytes into the array. - -=cut - -sub write { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $data = substr($_[1], $n, $off); - $n = length($data); - $self->print($data); - return $n; -} - - -=back - -=cut - - - -#============================== - -=head2 Seeking/telling and other attributes - -=over 4 - -=cut - -#------------------------------ - -=item autoflush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub autoflush {} - -#------------------------------ - -=item binmode - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub binmode {} - -#------------------------------ - -=item clearerr - -I<Instance method.> Clear the error and EOF flags. A no-op. - -=cut - -sub clearerr { 1 } - -#------------------------------ - -=item eof - -I<Instance method.> Are we at end of file? - -=cut - -sub eof { - ### print "checking EOF [$self->{Str}, $self->{Pos}]\n"; - ### print "SR = ", $#{$self->{AR}}, "\n"; - return 0 if ($_[0]->{Str} < $#{$_[0]->{AR}}); # before EOA - return 1 if ($_[0]->{Str} > $#{$_[0]->{AR}}); # after EOA - (($_[0]->{Str} == $#{$_[0]->{AR}}) && ($_[0]->_eos)); # at EOA, past EOS -} - -#------------------------------ -# -# _eos -# -# I<Instance method, private.> Are we at end of the CURRENT string? -# - -sub _eos { - ($_[0]->{Pos} >= length($_[0]->{AR}[$_[0]->{Str}])); # past last char -} - -#------------------------------ - -=item seek POS,WHENCE - -I<Instance method.> -Seek to a given position in the stream. -Only a WHENCE of 0 (SEEK_SET) is supported. - -=cut - -sub seek { - my ($self, $pos, $whence) = @_; - die "IO::ScalarArray::seek: whence of $whence not supported\n" if $whence; - - # Advance through array until done: - my $istr = 0; - while (($pos >= 0) && ($istr < scalar(@{$self->{AR}}))) { - if (length($self->{AR}[$istr]) > $pos) { # it's in this string! - return $self->setpos([$istr, $pos]); - } - else { # it's in next string - $pos -= length($self->{AR}[$istr++]); # move forward one string - } - } - # If we reached this point, pos is at or past end; zoom to EOF: - return $self->setpos([scalar(@{$self->{AR}}), 0]); -} - -#------------------------------ - -=item tell - -I<Instance method.> -Return the current position in the stream, as a numeric offset. - -=cut - -sub tell { - my $self = shift; - my $off = 0; - my ($s, $str_s); - for ($s = 0; $s < $self->{Str}; $s++) { # count all "whole" scalars - defined($str_s = $self->{AR}[$s]) or $str_s = ''; - ###print STDERR "COUNTING STRING $s (". length($str_s) . ")\n"; - $off += length($str_s); - } - ###print STDERR "COUNTING POS ($self->{Pos})\n"; - return ($off += $self->{Pos}); # plus the final, partial one -} - -#------------------------------ - -=item setpos POS - -I<Instance method.> -Seek to a given position in the array, using the opaque getpos() value. -Don't expect this to be a number. - -=cut - -sub setpos { - my ($self, $pos) = @_; - (ref($pos) eq 'ARRAY') or - die "setpos: only use a value returned by getpos!\n"; - ($self->{Str}, $self->{Pos}) = @$pos; -} - -#------------------------------ - -=item getpos - -I<Instance method.> -Return the current position in the array, as an opaque value. -Don't expect this to be a number. - -=cut - -sub getpos { - [$_[0]->{Str}, $_[0]->{Pos}]; -} - -#------------------------------ - -=item aref - -I<Instance method.> -Return a reference to the underlying array. - -=cut - -sub aref { - shift->{AR}; -} - -=back - -=cut - -#------------------------------ -# Tied handle methods... -#------------------------------ - -# Conventional tiehandle interface: -sub TIEHANDLE { shift->new(@_) } -sub GETC { shift->getc(@_) } -sub PRINT { shift->print(@_) } -sub PRINTF { shift->print(sprintf(shift, @_)) } -sub READ { shift->read(@_) } -sub READLINE { wantarray ? shift->getlines(@_) : shift->getline(@_) } -sub WRITE { shift->write(@_); } -sub CLOSE { shift->close(@_); } - -#------------------------------------------------------------ - -1; -__END__ - -# SOME PRIVATE NOTES: -# -# * The "current position" is the position before the next -# character to be read/written. -# -# * Str gives the string index of the current position, 0-based -# -# * Pos gives the offset within AR[Str], 0-based. -# -# * Inital pos is [0,0]. After print("Hello"), it is [1,0]. - - -=head1 VERSION - -$Id: ScalarArray.pm,v 1.117 2000/09/28 06:32:28 eryq Exp $ - - -=head1 AUTHOR - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Andy Glew,> -for suggesting C<getc()>. - -I<Brandon Browning,> -for suggesting C<opened()>. - -I<Eric L. Brine,> -for his offset-using read() and write() implementations. - -=cut - -#------------------------------ -1; - diff --git a/cpan/dist/IO-stringy/lib/IO/Stringy.pm b/cpan/dist/IO-stringy/lib/IO/Stringy.pm deleted file mode 100644 index c7b5d369..00000000 --- a/cpan/dist/IO-stringy/lib/IO/Stringy.pm +++ /dev/null @@ -1,193 +0,0 @@ -package IO::Stringy; - -use vars qw($VERSION); -$VERSION = substr q$Revision: 1.216 $, 10; - -1; -__END__ - - -=head1 NAME - -IO-stringy - I/O on in-core objects like strings and arrays - - -=head1 SYNOPSIS - - IO:: - ::AtomicFile adpO Write a file which is updated atomically ERYQ - ::Lines bdpO I/O handle to read/write to array of lines ERYQ - ::Scalar RdpO I/O handle to read/write to a string ERYQ - ::ScalarArray RdpO I/O handle to read/write to array of scalars ERYQ - ::Wrap RdpO Wrap old-style FHs in standard OO interface ERYQ - ::WrapTie adpO Tie your handles & retain full OO interface ERYQ - - -=head1 DESCRIPTION - -This toolkit primarily provides modules for performing both traditional -and object-oriented i/o) on things I<other> than normal filehandles; -in particular, L<IO::Scalar|IO::Scalar>, L<IO::ScalarArray|IO::ScalarArray>, -and L<IO::Lines|IO::Lines>. - -If you have access to tie(), these classes will make use of the -L<IO::WrapTie|IO::WrapTie> module to inherit a convenient new_tie() -constructor. It also exports a nice wraptie() function. - -In the more-traditional IO::Handle front, we -have L<IO::AtomicFile|IO::AtomicFile> -which may be used to painlessly create files which are updated -atomically. - -And in the "this-may-prove-useful" corner, we have L<IO::Wrap|IO::Wrap>, -whose exported wraphandle() function will clothe anything that's not -a blessed object in an IO::Handle-like wrapper... so you can just -use OO syntax and stop worrying about whether your function's caller -handed you a string, a globref, or a FileHandle. - - -=head1 INSTALLATION - -You know the drill... - - perl Makefile.PL - make test - make install - - - -=head1 VERSION - -$Id: Stringy.pm,v 1.216 2000/09/28 06:32:28 eryq Exp $ - - - -=head1 CHANGE LOG - -=over 4 - -=item Version 1.216 (2000/09/28) - -B<IO::Scalar and IO::ScalarArray now inherit from IO::Handle.> -I thought I'd remembered a problem with this ages ago, related to -the fact that these IO:: modules don't have "real" filehandles, -but the problem apparently isn't surfacing now. -If you suddenly encounter Perl warnings during global destruction -(especially if you're using tied filehandles), then please let me know! -I<Thanks to B. K. Oxley (binkley) for this.> - -B<Nasty bug fixed in IO::Scalar::write().> -Apparently, the offset and the number-of-bytes arguments were, -for all practical purposes, I<reversed.> You were okay if -you did all your writing with print(), but boy was I<this> a stupid bug! -I<Thanks to Richard Jones for finding this one. -For you, Rich, a double-length haiku:> - - Newspaper headline - typeset by dyslexic man - loses urgency - - BABY EATS FISH is - simply not equivalent - to FISH EATS BABY - -B<New sysread and syswrite methods for IO::Scalar.> -I<Thanks again to Richard Jones for this.> - - -=item Version 1.215 (2000/09/05) - -Added 'bool' overload to '""' overload, so object always evaluates -to true. (Whew. Glad I caught this before it went to CPAN.) - - -=item Version 1.214 (2000/09/03) - -Evaluating an IO::Scalar in a string context now yields -the underlying string. -I<Thanks to B. K. Oxley (binkley) for this.> - - -=item Version 1.213 (2000/08/16) - -Minor documentation fixes. - - -=item Version 1.212 (2000/06/02) - -Fixed IO::InnerFile incompatibility with Perl5.004. -I<Thanks to many folks for reporting this.> - - -=item Version 1.210 (2000/04/17) - -Added flush() and other no-op methods. -I<Thanks to Doru Petrescu for suggesting this.> - - -=item Version 1.209 (2000/03/17) - -Small bug fixes. - - -=item Version 1.208 (2000/03/14) - -Incorporated a number of contributed patches and extensions, -mostly related to speed hacks, support for "offset", and -WRITE/CLOSE methods. -I<Thanks to Richard Jones, Doru Petrescu, and many others.> - - - -=item Version 1.206 (1999/04/18) - -Added creation of ./testout when Makefile.PL is run. - - -=item Version 1.205 (1999/01/15) - -Verified for Perl5.005. - - -=item Version 1.202 (1998/04/18) - -New IO::WrapTie and IO::AtomicFile added. - - -=item Version 1.110 - -Added IO::WrapTie. - - -=item Version 1.107 - -Added IO::Lines, and made some bug fixes to IO::ScalarArray. -Also, added getc(). - - -=item Version 1.105 - -No real changes; just upgraded IO::Wrap to have a $VERSION string. - -=back - - - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -Enjoy. Yell if it breaks. - - -=cut - - - - - - - - diff --git a/cpan/dist/IO-stringy/lib/IO/Wrap.pm b/cpan/dist/IO-stringy/lib/IO/Wrap.pm deleted file mode 100644 index 6eae65b3..00000000 --- a/cpan/dist/IO-stringy/lib/IO/Wrap.pm +++ /dev/null @@ -1,211 +0,0 @@ -package IO::Wrap; - -# SEE DOCUMENTATION AT BOTTOM OF FILE - -require 5.002; - -use strict; -use vars qw(@ISA @EXPORT $VERSION); -@ISA = qw(Exporter); -@EXPORT = qw(wraphandle); - -use FileHandle; -use Carp; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.104 $, 10; - - -#------------------------------ -# wraphandle RAW -#------------------------------ -sub wraphandle { - my $raw = shift; - new IO::Wrap $raw; -} - -#------------------------------ -# new STREAM -#------------------------------ -sub new { - my ($class, $stream) = @_; - no strict 'refs'; - - # Convert raw scalar to globref: - ref($stream) or $stream = \*$stream; - - # Wrap globref and incomplete objects: - if ((ref($stream) eq 'GLOB') or # globref - (ref($stream) eq 'FileHandle') && !defined(&FileHandle::read)) { - return bless \$stream, $class; - } - $stream; # already okay! -} - -#------------------------------ -# I/O methods... -#------------------------------ -sub close { - my $self = shift; - return close($$self); -} -sub getline { - my $self = shift; - my $fh = $$self; - return scalar(<$fh>); -} -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my $fh = $$self; - <$fh>; -} -sub print { - my $self = shift; - print { $$self } @_; -} -sub read { - my $self = shift; - return read($$self, $_[0], $_[1]); -} -sub seek { - my $self = shift; - return seek($$self, $_[0], $_[1]); -} -sub tell { - my $self = shift; - return tell($$self); -} - -#------------------------------ -1; -__END__ - - -=head1 NAME - -IO::Wrap - wrap raw filehandles in IO::Handle interface - - -=head1 SYNOPSIS - - 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!"); - ... - } - - -=head1 DESCRIPTION - -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: - - do_stuff(\*STDOUT); - do_stuff('STDERR'); - do_stuff($some_FileHandle_object); - do_stuff($some_IO_Handle_object); - -And even: - - do_stuff($any_object_with_a_print_method); - -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>, which provides you with the following functions: - - -=over 4 - -=item wraphandle SCALAR - -This function will take a single argument, and "wrap" it based on -what it seems to be... - -=over 4 - -=item * - -B<A raw scalar filehandle name,> like C<"STDOUT"> or C<"Class::HANDLE">. -In this case, the filehandle name is wrapped in an IO::Wrap object, -which is returned. - -=item * - -B<A raw filehandle glob,> like C<\*STDOUT>. -In this case, the filehandle glob is wrapped in an IO::Wrap object, -which is returned. - -=item * - -B<A blessed FileHandle object.> -In this case, the FileHandle is wrapped in an IO::Wrap object if and only -if your FileHandle class does not support the C<read()> method. - -=item * - -B<Any other kind of blessed object,> which is assumed to be already -conformant to the IO::Handle interface. -In this case, you just get back that object. - -=back - -=back - - -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>, not named operators) should work on the thing you get back: - - close - getline - getlines - print ARGS... - read BUFFER,NBYTES - seek POS,WHENCE - tell - - - -=head1 NOTES - -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. - -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. - - -=head1 WARNINGS - -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 C<\*FOO> -or as C<"Foo::FOO">. However, C<"STDIN"> and friends will work just fine. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -=cut - diff --git a/cpan/dist/IO-stringy/lib/IO/WrapTie.pm b/cpan/dist/IO-stringy/lib/IO/WrapTie.pm deleted file mode 100644 index 2535e74b..00000000 --- a/cpan/dist/IO-stringy/lib/IO/WrapTie.pm +++ /dev/null @@ -1,480 +0,0 @@ -# SEE DOCUMENTATION AT BOTTOM OF FILE - - -#------------------------------------------------------------ -package IO::WrapTie; -#------------------------------------------------------------ -require 5.004; # for tie -use strict; -use vars qw(@ISA @EXPORT $VERSION); -use Exporter; - -# Inheritance, exporting, and package version: -@ISA = qw(Exporter); -@EXPORT = qw(wraptie); -$VERSION = substr q$Revision: 1.108 $, 10; - -# Function, exported. -sub wraptie { - IO::WrapTie::Master->new(@_); -} - -# Class method; BACKWARDS-COMPATIBILITY ONLY! -sub new { - shift; - IO::WrapTie::Master->new(@_); -} - - - -#------------------------------------------------------------ -package IO::WrapTie::Master; -#------------------------------------------------------------ - -use strict; -use vars qw(@ISA $AUTOLOAD); -use IO::Handle; - -# We inherit from IO::Handle to get methods which invoke i/o operators, -# like print(), on our tied handle: -@ISA = qw(IO::Handle); - -#------------------------------ -# new SLAVE, TIEARGS... -#------------------------------ -# Create a new subclass of IO::Handle which... -# -# (1) Handles i/o OPERATORS because it is tied to an instance of -# an i/o-like class, like IO::Scalar. -# -# (2) Handles i/o METHODS by delegating them to that same tied object!. -# -# Arguments are the slave class (e.g., IO::Scalar), followed by all -# the arguments normally sent into that class's TIEHANDLE method. -# In other words, much like the arguments to tie(). :-) -# -# NOTE: -# The thing $x we return must be a BLESSED REF, for ($x->print()). -# The underlying symbol must be a FILEHANDLE, for (print $x "foo"). -# It has to have a way of getting to the "real" back-end object... -# -sub new { - my $master = shift; - my $io = IO::Handle->new; # create a new handle - my $slave = shift; - tie *$io, $slave, @_; # tie: will invoke slave's TIEHANDLE - bless $io, $master; # return a master -} - -#------------------------------ -# AUTOLOAD -#------------------------------ -# Delegate method invocations on the master to the underlying slave. -# -sub AUTOLOAD { - my $method = $AUTOLOAD; - $method =~ s/.*:://; - my $self = shift; tied(*$self)->$method(\@_); -} - -#------------------------------ -# PRELOAD -#------------------------------ -# Utility. -# -# Most methods like print(), getline(), etc. which work on the tied object -# via Perl's i/o operators (like 'print') are inherited from IO::Handle. -# -# Other methods, like seek() and sref(), we must delegate ourselves. -# AUTOLOAD takes care of these. -# -# However, it may be necessary to preload delegators into your -# own class. PRELOAD will do this. -# -sub PRELOAD { - my $class = shift; - foreach (@_) { - eval "sub ${class}::$_ { my \$s = shift; tied(*\$s)->$_(\@_) }"; - } -} - -# Preload delegators for some standard methods which we can't simply -# inherit from IO::Handle... for example, some IO::Handle methods -# assume that there is an underlying file descriptor. -# -PRELOAD IO::WrapTie::Master - qw(open opened close read clearerr eof seek tell setpos getpos); - - - -#------------------------------------------------------------ -package IO::WrapTie::Slave; -#------------------------------------------------------------ -# Teeny private class providing a new_tie constructor... -# -# HOW IT ALL WORKS: -# -# Slaves inherit from this class. -# -# When you send a new_tie() message to a tie-slave class (like IO::Scalar), -# it first determines what class should provide its master, via TIE_MASTER. -# In this case, IO::Scalar->TIE_MASTER would return IO::Scalar::Master. -# Then, we create a new master (an IO::Scalar::Master) with the same args -# sent to new_tie. -# -# In general, the new() method of the master is inherited directly -# from IO::WrapTie::Master. -# -sub new_tie { - my $self = shift; - $self->TIE_MASTER->new($self,@_); # e.g., IO::Scalar::Master->new(@_) -} - -# Default class method for new_tie(). -# All your tie-slave class (like IO::Scalar) has to do is override this -# method with a method that returns the name of an appropriate "master" -# class for tying that slave. -# -sub TIE_MASTER { 'IO::WrapTie::Master' } - -#------------------------------ -1; -__END__ - - -package IO::WrapTie; # for doc generator - - -=head1 NAME - -IO::WrapTie - wrap tieable objects in IO::Handle interface - -I<This is currently Alpha code, released for comments. - Please give me your feedback!> - - -=head1 SYNOPSIS - -First of all, you'll need tie(), so: - - require 5.004; - -I<Function interface (experimental).> -Use this with any existing class... - - use IO::WrapTie; - use FooHandle; # implements TIEHANDLE interface - - # Suppose we want a "FooHandle->new(&FOO_RDWR, 2)". - # We can instead say... - - $FH = wraptie('FooHandle', &FOO_RDWR, 2); - - # Now we can use... - print $FH "Hello, "; # traditional operator syntax... - $FH->print("world!\n"); # ...and OO syntax as well! - -I<OO interface (preferred).> -You can inherit from the IO::WrapTie::Slave mixin to get a -nifty C<new_tie()> constructor... - - #------------------------------ - package FooHandle; # a class which can TIEHANDLE - - use IO::WrapTie; - @ISA = qw(IO::WrapTie::Slave); # inherit new_tie() - ... - - - #------------------------------ - package main; - - $FH = FooHandle->new_tie(&FOO_RDWR, 2); # $FH is an IO::WrapTie::Master - print $FH "Hello, "; # traditional operator syntax - $FH->print("world!\n"); # OO syntax - -See IO::Scalar as an example. It also shows you how to create classes -which work both with and without 5.004. - - -=head1 DESCRIPTION - -Suppose you have a class C<FooHandle>, where... - -=over 4 - -=item * - -B<FooHandle does not inherit from IO::Handle;> that is, it performs -filehandle-like I/O, but to something other than an underlying -file descriptor. Good examples are IO::Scalar (for printing to a -string) and IO::Lines (for printing to an array of lines). - -=item * - -B<FooHandle implements the TIEHANDLE interface> (see L<perltie>); -that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, -READ, and READLINE. - -=item * - -B<FooHandle implements the traditional OO interface> of -FileHandle and IO::Handle; i.e., it contains methods like getline(), -read(), print(), seek(), tell(), eof(), etc. - -=back - - -Normally, users of your class would have two options: - - -=over 4 - -=item * - -B<Use only OO syntax,> and forsake named I/O operators like 'print'. - -=item * - -B<Use with tie,> and forsake treating it as a first-class object -(i.e., class-specific methods can only be invoked through the underlying -object via tied()... giving the object a "split personality"). - -=back - - -But now with IO::WrapTie, you can say: - - $WT = wraptie('FooHandle', &FOO_RDWR, 2); - $WT->print("Hello, world\n"); # OO syntax - print $WT "Yes!\n"; # Named operator syntax too! - $WT->weird_stuff; # Other methods! - -And if you're authoring a class like FooHandle, just have it inherit -from C<IO::WrapTie::Slave> and that first line becomes even prettier: - - $WT = FooHandle->new_tie(&FOO_RDWR, 2); - -B<The bottom line:> now, almost any class can look and work exactly like -an IO::Handle... and be used both with OO and non-OO filehandle syntax. - - -=head1 HOW IT ALL WORKS - - -=head2 The data structures - -Consider this example code, using classes in this distribution: - - use IO::Scalar; - use IO::WrapTie; - - $WT = wraptie('IO::Scalar',\$s); - print $WT "Hello, "; - $WT->print("world!\n"); - -In it, the wraptie() function creates a data structure as follows: - - * $WT is a blessed reference to a tied filehandle - $WT glob; that glob is tied to the "Slave" object. - | * You would do all your i/o with $WT directly. - | - | - | ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle - V / - .-------------. - | | - | | * Perl i/o operators work on the tied object, - | "Master" | invoking the TIEHANDLE methods. - | | * Method invocations are delegated to the tied - | | slave. - `-------------' - | - tied(*$WT) | .---isa--> IO::WrapTie::Slave - V / - .-------------. - | | - | "Slave" | * Instance of FileHandle-like class which doesn't - | | actually use file descriptors, like IO::Scalar. - | IO::Scalar | * The slave can be any kind of object. - | | * Must implement the TIEHANDLE interface. - `-------------' - - -I<NOTE:> just as an IO::Handle is really just a blessed reference to a -I<traditional> filehandle glob... so also, an IO::WrapTie::Master -is really just a blessed reference to a filehandle -glob I<which has been tied to some "slave" class.> - - -=head2 How wraptie() works - -=over 4 - -=item 1. - -The call to function C<wraptie(SLAVECLASS, TIEARGS...)> is -passed onto C<IO::WrapTie::Master::new()>. -Note that class IO::WrapTie::Master is a subclass of IO::Handle. - -=item 2. - -The C<IO::WrapTie::Master::new> method creates a new IO::Handle object, -reblessed into class IO::WrapTie::Master. This object is the I<master>, -which will be returned from the constructor. At the same time... - -=item 3. - -The C<new> method also creates the I<slave>: this is an instance -of SLAVECLASS which is created by tying the master's IO::Handle -to SLAVECLASS via C<tie(HANDLE, SLAVECLASS, TIEARGS...)>. -This call to C<tie()> creates the slave in the following manner: - -=item 4. - -Class SLAVECLASS is sent the message C<TIEHANDLE(TIEARGS...)>; it -will usually delegate this to C<SLAVECLASS::new(TIEARGS...)>, resulting -in a new instance of SLAVECLASS being created and returned. - -=item 5. - -Once both master and slave have been created, the master is returned -to the caller. - -=back - - -=head2 How I/O operators work (on the master) - -Consider using an i/o operator on the master: - - print $WT "Hello, world!\n"; - -Since the master ($WT) is really a [blessed] reference to a glob, -the normal Perl i/o operators like C<print> may be used on it. -They will just operate on the symbol part of the glob. - -Since the glob is tied to the slave, the slave's PRINT method -(part of the TIEHANDLE interface) will be automatically invoked. - -If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be -invoked, and that method happens to delegate to the C<print()> method -of the same class. So the I<real> work is ultimately done by -IO::Scalar::print(). - - -=head2 How methods work (on the master) - -Consider using a method on the master: - - $WT->print("Hello, world!\n"); - -Since the master ($WT) is blessed into the class IO::WrapTie::Master, -Perl first attempts to find a C<print()> method there. Failing that, -Perl next attempts to find a C<print()> method in the superclass, -IO::Handle. It just so happens that there I<is> such a method; -that method merely invokes the C<print> i/o operator on the self object... -and for that, see above! - -But let's suppose we're dealing with a method which I<isn't> part -of IO::Handle... for example: - - my $sref = $WT->sref; - -In this case, the intuitive behavior is to have the master delegate the -method invocation to the slave (now do you see where the designations -come from?). This is indeed what happens: IO::WrapTie::Master contains -an AUTOLOAD method which performs the delegation. - -So: when C<sref()> can't be found in IO::Handle, the AUTOLOAD method -of IO::WrapTie::Master is invoked, and the standard behavior of -delegating the method to the underlying slave (here, an IO::Scalar) -is done. - -Sometimes, to get this to work properly, you may need to create -a subclass of IO::WrapTie::Master which is an effective master for -I<your> class, and do the delegation there. - - - - -=head1 NOTES - -B<Why not simply use the object's OO interface?> - Because that means forsaking the use of named operators -like print(), and you may need to pass the object to a subroutine -which will attempt to use those operators: - - $O = FooHandle->new(&FOO_RDWR, 2); - $O->print("Hello, world\n"); # OO syntax is okay, BUT.... - - sub nope { print $_[0] "Nope!\n" } - X nope($O); # ERROR!!! (not a glob ref) - - -B<Why not simply use tie()?> - Because (1) you have to use tied() to invoke methods in the -object's public interface (yuck), and (2) you may need to pass -the tied symbol to another subroutine which will attempt to treat -it in an OO-way... and that will break it: - - tie *T, 'FooHandle', &FOO_RDWR, 2; - print T "Hello, world\n"; # Operator is okay, BUT... - - tied(*T)->other_stuff; # yuck! AND... - - sub nope { shift->print("Nope!\n") } - X nope(\*T); # ERROR!!! (method "print" on unblessed ref) - - -B<Why a master and slave? - Why not simply write FooHandle to inherit from IO::Handle?> - I tried this, with an implementation similar to that of IO::Socket. -The problem is that I<the whole point is to use this with objects -that don't have an underlying file/socket descriptor.>. -Subclassing IO::Handle will work fine for the OO stuff, and fine with -named operators I<if> you tie()... but if you just attempt to say: - - $IO = FooHandle->new(&FOO_RDWR, 2); - print $IO "Hello!\n"; - -you get a warning from Perl like: - - Filehandle GEN001 never opened - -because it's trying to do system-level i/o on an (unopened) file -descriptor. To avoid this, you apparently have to tie() the handle... -which brings us right back to where we started! At least the -IO::WrapTie mixin lets us say: - - $IO = FooHandle->new_tie(&FOO_RDWR, 2); - print $IO "Hello!\n"; - -and so is not I<too> bad. C<:-)> - - -=head1 WARNINGS - -Remember: this stuff is for doing FileHandle-like i/o on things -I<without underlying file descriptors>. If you have an underlying -file descriptor, you're better off just inheriting from IO::Handle. - -B<Be aware that new_tie() always returns an instance of a -kind of IO::WrapTie::Master...> it does B<not> return an instance -of the i/o class you're tying to! - -Invoking some methods on the master object causes AUTOLOAD to delegate -them to the slave object... so it I<looks> like you're manipulating a -"FooHandle" object directly, but you're not. - -I have not explored all the ramifications of this use of tie(). -I<Here there be dragons>. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -=cut - diff --git a/cpan/dist/IO-stringy/t/Common.pm b/cpan/dist/IO-stringy/t/Common.pm deleted file mode 100644 index 6787a7f2..00000000 --- a/cpan/dist/IO-stringy/t/Common.pm +++ /dev/null @@ -1,255 +0,0 @@ -package Common; - -#-------------------- -# -# GLOBALS... -# -#-------------------- - -use vars qw(@DATA_SA - @DATA_LA - $DATA_S - - @ADATA_SA - $ADATA_S - - $FDATA_S - @FDATA_LA - ); - -#------------------------------ - -# Data... -# ...as a scalar-array: -@DATA_SA = ( -"A diner while ", -"dining at Crewe\n", -"Found a rather large ", -"mouse in his stew\n Said the waiter, \"Don't shout,\n", -" And ", -"wave it about..." -); -# ...as a string: -$DATA_S = join '', @DATA_SA; -# ...as a line-array: -@DATA_LA = lines($DATA_S); - -# Additional data... -# ...as a scalar-array: -@ADATA_SA = ( -"\nor the rest", -" will be wanting one ", -"too.\"\n", -); -# ...as a string: -$ADATA_S = join '', @ADATA_SA; - - -# Full data... -# ...as a string: -$FDATA_S = $DATA_S . $ADATA_S; -# ...as a line-array: -@FDATA_LA = lines($FDATA_S); - - - - -# Tester: -my $T; - -# Scratch... -my $BUF = ''; # buffer -my $M; # message - - -#------------------------------ -# lines STR -#------------------------------ -sub lines { - my $s = shift; - split /^/, $s; -} - -#------------------------------ -# test_init PARAMHASH -#------------------------------ -# Init common tests. -# -sub test_init { - my ($self, %p) = @_; - $T = $p{TBone}; -} - -#------------------------------ -# test_print HANDLE, TEST -#------------------------------ -# Test printing to handle. -# -sub test_print { - my ($self, $GH, $all) = @_; - local($_); - - # Append with print: - $M = "PRINT: able to print to $GH"; - $GH->print($ADATA_SA[0]); - $GH->print(@ADATA_SA[1..2]); - $T->ok(1, $M); -} - -#------------------------------ -# test_getc HANDLE -#------------------------------ -# Test getc(). -# -sub test_getc { - my ($self, $GH) = @_; - local($_); - my @c; - - $M = "GETC: seek(0,0) and getc()"; - $GH->seek(0,0); - for (0..2) { $c[$_] = $GH->getc }; - $T->ok((($c[0] eq 'A') && - ($c[1] eq ' ') && - ($c[2] eq 'd')), $M); -} - -#------------------------------ -# test_getline HANDLE -#------------------------------ -# Test getline() and getlines(). -# -sub test_getline { - my ($self, $GH) = @_; - local($_); - - $M = "GETLINE/SEEK3: seek(3,START) and getline() gets part of 1st line"; - $GH->seek(3,0); - my $got = $GH->getline; - my $want = "iner while dining at Crewe\n"; - $T->ok(($got eq $want), $M, - GH => $GH, - Got => $got, - Want => $want); - - $M = "GETLINE/NEXT: next getline() gets subsequent line"; - $_ = $GH->getline; - $T->ok(($_ eq "Found a rather large mouse in his stew\n"), $M, - Got => $_); - - $M = "GETLINE/EOF: repeated getline() finds end of stream"; - my $last; - for (1..6) { $last = $GH->getline } - $T->ok(!$last, $M, - Last => (defined($last) ? $last : 'undef')); - - $M = "GETLINE/GETLINES: seek(0,0) and getlines() slurps in string"; - $GH->seek(0,0); - my @got = $GH->getlines; - my $gots = join '', @got; - $T->ok(($gots eq $FDATA_S), $M, - GotAll => $gots, - WantAll => $FDATA_S, - Got => \@got); -} - -#------------------------------ -# test_read HANDLE -#------------------------------ -# Test read(). -# -sub test_read { - my ($self, $GH) = @_; - local($_); - - $M = "READ/FIRST10: reading first 10 bytes with seek(0,START) + read(10)"; - $GH->seek(0,0); - $GH->read($BUF,10); - $T->ok(($BUF eq "A diner wh"), $M); - - $M = "READ/NEXT10: reading next 10 bytes with read(10)"; - $GH->read($BUF,10); - $T->ok(($BUF eq "ile dining"), $M); - - $M = "READ/TELL20: tell() the current location as 20"; - $T->ok(($GH->tell == 20), $M); - - $M = "READ/SLURP: seek(0,START) + read(1000) reads in whole handle"; - $GH->seek(0,0); - $GH->read($BUF,1000); - $T->ok(($BUF eq $FDATA_S), $M); -} - -#------------------------------ -# test_seek HANDLE -#------------------------------ -# Test seeks other than (0,0). -# -sub test_seek { - my ($self, $GH) = @_; - local($_); - - $M = "SEEK/END: seek(-6,END) + read(3) returns 'too'"; - $GH->seek(-6,2); - $GH->read($BUF,3); - $T->ok(($BUF eq 'too'), $M); - - $M = "SEEK/CUR: seek(-3,CUR) + read(3) returns 'too' again"; - $GH->seek(-3,1); - $GH->read($BUF,3); - $T->ok(($BUF eq 'too'), $M); -} - -#------------------------------ -# test_tie PARAMHASH -#------------------------------ -# Test tiehandle getline() interface. -# -sub test_tie { - my ($self, %p) = @_; - my ($tieclass, @tieargs) = @{$p{TieArgs}}; - local($_); - my @lines; - my $i; - my $nmatched; - - $M = "TIE/TIE: able to tie"; - tie(*OUT, $tieclass, @tieargs); - $T->ok(1, $M); - - $M = "TIE/PRINT: printing data"; - print OUT @DATA_SA; - print OUT $ADATA_SA[0]; - print OUT @ADATA_SA[1..2]; - $T->ok(1, $M); - - $M = "TIE/GETLINE: seek(0,0) and scalar <> get expected lines"; - tied(*OUT)->seek(0,0); # rewind - @lines = (); push @lines, $_ while <OUT>; # get lines one at a time - $nmatched = 0; # total up matches... - for (0..$#lines) { ++$nmatched if ($lines[$_] eq $FDATA_LA[$_]) }; - $T->ok(($nmatched == int(@FDATA_LA)), $M, - Want => \@FDATA_LA, - Gotl => \@lines, - Lines=> "0..$#lines", - Match=> $nmatched, - FDatl=> int(@FDATA_LA), - FData=> \@FDATA_LA); - - $M = "TIE/GETLINES: seek(0,0) and array <> slurps in lines"; - tied(*OUT)->seek(0,0); # rewind - @lines = <OUT>; # get lines all at once - $nmatched = 0; # total up matches... - for (0..$#lines) { ++$nmatched if ($lines[$_] eq $FDATA_LA[$_]) }; - $T->ok(($nmatched == int(@FDATA_LA)), $M, - Want => \@FDATA_LA, - Gotl => \@lines, - Lines=> "0..$#lines", - Match=> $nmatched); - -} - -#------------------------------ -1; - - diff --git a/cpan/dist/IO-stringy/t/ExtUtils/TBone.pm b/cpan/dist/IO-stringy/t/ExtUtils/TBone.pm deleted file mode 100644 index 88dbe29c..00000000 --- a/cpan/dist/IO-stringy/t/ExtUtils/TBone.pm +++ /dev/null @@ -1,534 +0,0 @@ -package ExtUtils::TBone; - - -=head1 NAME - -ExtUtils::TBone - a "skeleton" for writing "t/*.t" test files. - - -=head1 SYNOPSIS - -Include a copy of this module in your t directory (as t/ExtUtils/TBone.pm), -and then write your t/*.t files like this: - - use lib "./t"; # to pick up a ExtUtils::TBone - use ExtUtils::TBone; - - # Make a tester... here are 3 different alternatives: - my $T = typical ExtUtils::TBone; # standard log - my $T = new ExtUtils::TBone; # no log - my $T = new ExtUtils::TBone "testout/Foo.tlog"; # explicit log - - # Begin testing, and expect 3 tests in all: - $T->begin(3); # expect 3 tests - $T->msg("Something for the log file"); # message for the log - - # Run some tests: - $T->ok($this); # test 1: no real info logged - $T->ok($that, # test 2: logs a comment - "Is that ok, or isn't it?"); - $T->ok(($this eq $that), # test 3: logs comment + vars - "Do they match?", - This => $this, - That => $that); - - # That last one could have also been written... - $T->ok_eq($this, $that); # does 'eq' and logs operands - $T->ok_eqnum($this, $that); # does '==' and logs operands - - # End testing: - $T->end; - - -=head1 DESCRIPTION - -This module is intended for folks who release CPAN modules with -"t/*.t" tests. It makes it easy for you to output syntactically -correct test-output while at the same time logging all test -activity to a log file. Hopefully, bug reports which include -the contents of this file will be easier for you to investigate. - - -=head1 LOG FILE - -A typical log file output by this module looks like this: - - 1..3 - - ** A message logged with msg(). - ** Another one. - 1: My first test, using test(): how'd I do? - 1: ok 1 - - ** Yet another message. - 2: My second test, using test_eq()... - 2: A: The first string - 2: B: The second string - 2: not ok 2 - - 3: My third test. - 3: ok 3 - - END - -Each test() is logged with the test name and results, and -the test-number prefixes each line. -This allows you to scan a large file easily with "grep" (or, ahem, "perl"). -A blank line follows each test's record, for clarity. - - -=head1 PUBLIC INTERFACE - -=cut - -# Globals: -use strict; -use vars qw($VERSION); -use FileHandle; -use File::Basename; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.117 $, 10; - - - -#------------------------------ - -=head2 Construction - -=over 4 - -=cut - -#------------------------------ - -=item new [ARGS...] - -I<Class method, constructor.> -Create a new tester. Any arguments are sent to log_open(). - -=cut - -sub new { - my $self = bless { - OUT =>\*STDOUT, - Begin=>0, - End =>0, - Count=>0, - }, shift; - $self->log_open(@_) if @_; - $self; -} - -#------------------------------ - -=item typical - -I<Class method, constructor.> -Create a typical tester. Use this instead of new() for most applicaitons. -The directory "testout" is created for you automatically, to hold -the output log file. - -=cut - -sub typical { - my $class = shift; - my ($tfile) = basename $0; - unless (-d "testout") { - mkdir "testout", 0755 - or die "Couldn't create a 'testout' subdirectory: $!\n"; - ### warn "$class: created 'testout' directory\n"; - } - $class->new($class->catfile('.', 'testout', "${tfile}log")); -} - -#------------------------------ -# DESTROY -#------------------------------ -# Class method, destructor. -# Automatically closes the log. -# -sub DESTROY { - $_[0]->log_close; -} - - -#------------------------------ - -=back - -=head2 Doing tests - -=over 4 - -=cut - -#------------------------------ - -=item begin NUMTESTS - -I<Instance method.> -Start testing. - -=cut - -sub begin { - my ($self, $n) = @_; - return if $self->{Begin}++; - $self->l_print("1..$n\n\n"); - print {$self->{OUT}} "1..$n\n"; -} - -#------------------------------ - -=item end - -I<Instance method.> -End testing. - -=cut - -sub end { - my ($self) = @_; - return if $self->{End}++; - $self->l_print("END\n"); - print {$self->{OUT}} "END\n"; -} - -#------------------------------ - -=item ok BOOL, [TESTNAME], [PARAMHASH...] - -I<Instance method.> -Do a test, and log some information connected with it. -Use it like this: - - $T->ok(-e $dotforward); - -Or better yet, like this: - - $T->ok((-e $dotforward), - "Does the user have a .forward file?"); - -Or even better, like this: - - $T->ok((-e $dotforward), - "Does the user have a .forward file?", - User => $ENV{USER}, - Path => $dotforward, - Fwd => $ENV{FWD}); - -That last one, if it were test #3, would be logged as: - - 3: Does the user have a .forward file? - 3: User: "alice" - 3: Path: "/home/alice/.forward" - 3: Fwd: undef - 3: ok - -You get the idea. Note that defined quantities are logged with delimiters -and with all nongraphical characters suitably escaped, so you can see -evidence of unexpected whitespace and other badnasties. -Had "Fwd" been the string "this\nand\nthat", you'd have seen: - - 3: Fwd: "this\nand\nthat" - -And unblessed array refs like ["this", "and", "that"] are -treated as multiple values: - - 3: Fwd: "this" - 3: Fwd: "and" - 3: Fwd: "that" - -=cut - -sub ok { - my ($self, $ok, $test, @ps) = @_; - ++($self->{Count}); # next test - - # Report to harness: - my $status = ($ok ? "ok " : "not ok ") . $self->{Count}; - print {$self->{OUT}} $status, "\n"; - - # Log: - $self->ln_print($test, "\n") if $test; - while (@ps) { - my ($k, $v) = (shift @ps, shift @ps); - my @vs = ((ref($v) and (ref($v) eq 'ARRAY'))? @$v : ($v)); - foreach (@vs) { - if (!defined($_)) { # value not defined: output keyword - $self->ln_print(qq{ $k: undef\n}); - } - else { # value defined: output quoted, encoded form - s{([\n\t\x00-\x1F\x7F-\xFF\\\"])} - {'\\'.sprintf("%02X",ord($1)) }exg; - s{\\0A}{\\n}g; - $self->ln_print(qq{ $k: "$_"\n}); - } - } - } - $self->ln_print($status, "\n"); - $self->l_print("\n"); - 1; -} - - -#------------------------------ - -=item ok_eq ASTRING, BSTRING, [TESTNAME], [PARAMHASH...] - -I<Instance method.> -Convenience front end to ok(): test whether C<ASTRING eq BSTRING>, and -logs the operands as 'A' and 'B'. - -=cut - -sub ok_eq { - my ($self, $this, $that, $test, @ps) = @_; - $self->ok(($this eq $that), - ($test || "(Is 'A' string-equal to 'B'?)"), - A => $this, - B => $that, - @ps); -} - - -#------------------------------ - -=item ok_eqnum ANUM, BNUM, [TESTNAME], [PARAMHASH...] - -I<Instance method.> -Convenience front end to ok(): test whether C<ANUM == BNUM>, and -logs the operands as 'A' and 'B'. - -=cut - -sub ok_eqnum { - my ($self, $this, $that, $test, @ps) = @_; - $self->ok(($this == $that), - ($test || "(Is 'A' numerically-equal to 'B'?)"), - A => $this, - B => $that, - @ps); -} - -#------------------------------ - -=back - -=head2 Logging messages - -=over 4 - -=cut - -#------------------------------ - -=item log_open PATH - -I<Instance method.> -Open a log file for messages to be output to. This is invoked -for you automatically by C<new(PATH)> and C<typical()>. - -=cut - -sub log_open { - my ($self, $path) = @_; - $self->{LogPath} = $path; - $self->{LOG} = FileHandle->new(">$path") || die "open $path: $!"; - $self; -} - -#------------------------------ - -=item log_close - -I<Instance method.> -Close the log file and stop logging. -You shouldn't need to invoke this directly; the destructor does it. - -=cut - -sub log_close { - my $self = shift; - close(delete $self->{LOG}) if $self->{LOG}; -} - -#------------------------------ - -=item log MESSAGE... - -I<Instance method.> -Log a message to the log file. No alterations are made on the -text of the message. See msg() for an alternative. - -=cut - -sub log { - my $self = shift; - print {$self->{LOG}} @_ if $self->{LOG}; -} - -#------------------------------ - -=item msg MESSAGE... - -I<Instance method.> -Log a message to the log file. Lines are prefixed with "** " for clarity, -and a terminating newline is forced. - -=cut - -sub msg { - my $self = shift; - my $text = join '', @_; - chomp $text; - $text =~ s{^}{** }gm; - $self->l_print($text, "\n"); -} - -#------------------------------ -# -# l_print MESSAGE... -# -# Instance method, private. -# Print to the log file if there is one. -# -sub l_print { - my $self = shift; - print { $self->{LOG} } @_ if $self->{LOG}; -} - -#------------------------------ -# -# ln_print MESSAGE... -# -# Instance method, private. -# Print to the log file, prefixed by message number. -# -sub ln_print { - my $self = shift; - foreach (split /\n/, join('', @_)) { - $self->l_print("$self->{Count}: $_\n"); - } -} - -#------------------------------ - -=back - -=head2 Utilities - -=over 4 - -=cut - -#------------------------------ - -=item catdir DIR, ..., DIR - -I<Class/instance method.> -Concatenate several directories into a path ending in a directory. -Lightweight version of the one in the (very new) File::Spec. - -Paths are assumed to be absolute. -To signify a relative path, the first DIR must be ".", -which is processed specially. - -On Mac, the path I<does> end in a ':'. -On Unix, the path I<does not> end in a '/'. - -=cut - -sub catdir { - my $self = shift; - my $relative = shift @_ if ($_[0] eq '.'); - if ($^O eq 'Mac') { - return ($relative ? ':' : '') . (join ':', @_) . ':'; - } - else { - return ($relative ? './' : '/') . join '/', @_; - } -} - -#------------------------------ - -=item catfile DIR, ..., DIR, FILE - -I<Class/instance method.> -Like catdir(), but last element is assumed to be a file. -Note that, at a minimum, you must supply at least a single DIR. - -=cut - -sub catfile { - my $self = shift; - my $file = pop; - if ($^O eq 'Mac') { - return $self->catdir(@_) . $file; - } - else { - return $self->catdir(@_) . "/$file"; - } -} - -#------------------------------ - -=back - - -=head1 CHANGE LOG - -B<Current version:> -$Id: TBone.pm,v 1.117 2000/08/16 05:08:09 eryq Exp $ - -=over 4 - -=item Version 1.116 - -Cosmetic improvements only. - - -=item Version 1.112 - -Added lightweight catdir() and catfile() (a la File::Spec) -to enhance portability to Mac environment. - - -=item Version 1.111 - -Now uses File::Basename to create "typical" logfile name, -for portability. - - -=item Version 1.110 - -Fixed bug in constructor that surfaced if no log was being used. - -=back - -Created: Friday-the-13th of February, 1998. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc. (F<http://www.zeegee.com>) - -=cut - -#------------------------------ - -1; -__END__ - -my $T = new ExtUtils::TBone "testout/foo.tlog"; -$T->begin(3); -$T->msg("before 1\nor 2"); -$T->ok(1, "one"); -$T->ok(2, "Two"); -$T->ok(3, "Three", Roman=>'III', Arabic=>[3, '03'], Misc=>"3\nor 3"); -$T->end; - -1; - diff --git a/cpan/dist/IO-stringy/t/IO_Lines.t b/cpan/dist/IO-stringy/t/IO_Lines.t deleted file mode 100644 index 13fc13c0..00000000 --- a/cpan/dist/IO-stringy/t/IO_Lines.t +++ /dev/null @@ -1,43 +0,0 @@ -#!/usr/bin/perl -w #-*-Perl-*- - -use lib "./t", "./lib"; -use IO::Lines; -use ExtUtils::TBone; -use Common; - - -#-------------------- -# -# TEST... -# -#-------------------- - -# Make a tester: -my $T = typical ExtUtils::TBone; -Common->test_init(TBone=>$T); - -# Set the counter: -my $tie_tests = (($] >= 5.004) ? 4 : 0); -$T->begin(11 + $tie_tests); - -# Open a scalar on a string, containing initial data: -my @la = @Common::DATA_LA; -my $LAH = IO::Lines->new(\@la); -$T->ok($LAH, "OPEN: open a scalar on a ref to an array"); - -# Run standard tests: -Common->test_print($LAH); -Common->test_getc($LAH); -Common->test_getline($LAH); -Common->test_read($LAH); -#Common->test_seek($LAH); - -# Run tie tests: -if ($tie_tests) { - Common->test_tie(TieArgs => ['IO::Lines', []]); -} - -# So we know everything went well... -$T->end; - - diff --git a/cpan/dist/IO-stringy/t/IO_Scalar.t b/cpan/dist/IO-stringy/t/IO_Scalar.t deleted file mode 100644 index ce275004..00000000 --- a/cpan/dist/IO-stringy/t/IO_Scalar.t +++ /dev/null @@ -1,51 +0,0 @@ -#!/usr/bin/perl -w #-*-Perl-*- - -use lib "./t", "./lib"; -use IO::Scalar; -use ExtUtils::TBone; -use Common; - - -#-------------------- -# -# TEST... -# -#-------------------- - -# Make a tester: -my $T = typical ExtUtils::TBone; -Common->test_init(TBone=>$T); - -# Set the counter: -my $tie_tests = (($] >= 5.004) ? 4 : 0); -$T->begin(14 + $tie_tests); - -# Open a scalar on a string, containing initial data: -my $s = $Common::DATA_S; -my $SH = IO::Scalar->new(\$s); -$T->ok($SH, "OPEN: open a scalar on a ref to a string"); - -# Run standard tests: -Common->test_print($SH); -$T->ok(($s eq $Common::FDATA_S), "FULL", - S=>$s, F=>$Common::FDATA_S); -Common->test_getc($SH); -Common->test_getline($SH); -Common->test_read($SH); -Common->test_seek($SH); - -# Run tie tests: -if ($tie_tests) { - Common->test_tie(TieArgs => ['IO::Scalar']); -} - -# So we know everything went well... -$T->end; - - - - - - - - diff --git a/cpan/dist/IO-stringy/t/IO_ScalarArray.t b/cpan/dist/IO-stringy/t/IO_ScalarArray.t deleted file mode 100644 index 29955911..00000000 --- a/cpan/dist/IO-stringy/t/IO_ScalarArray.t +++ /dev/null @@ -1,49 +0,0 @@ -#!/usr/bin/perl -w #-*-Perl-*- - -use lib "./t", "./lib"; -use IO::ScalarArray; -use ExtUtils::TBone; -use Common; - - -#-------------------- -# -# TEST... -# -#-------------------- - -# Make a tester: -my $T = typical ExtUtils::TBone; -Common->test_init(TBone=>$T); - -# Set the counter: -my $tie_tests = (($] >= 5.004) ? 4 : 0); -$T->begin(11 + $tie_tests); - -# Open a scalar on a string, containing initial data: -my @sa = @Common::DATA_SA; -my $SAH = IO::ScalarArray->new(\@sa); -$T->ok($SAH, "OPEN: open a scalar on a ref to an array"); - -# Run standard tests: -Common->test_print($SAH); -Common->test_getc($SAH); -Common->test_getline($SAH); -Common->test_read($SAH); -#Common->test_seek($SAH); - -# Run tie tests: -if ($tie_tests) { - Common->test_tie(TieArgs => ['IO::ScalarArray', []]); -} - -# So we know everything went well... -$T->end; - - - - - - - - diff --git a/cpan/dist/IO-stringy/t/IO_WrapTie.t b/cpan/dist/IO-stringy/t/IO_WrapTie.t deleted file mode 100644 index 2817ca47..00000000 --- a/cpan/dist/IO-stringy/t/IO_WrapTie.t +++ /dev/null @@ -1,66 +0,0 @@ -#!/usr/bin/perl -w #-*-Perl-*- - -use lib "./t"; -use IO::Handle; -use IO::Scalar; -use ExtUtils::TBone; -use IO::WrapTie; - -#-------------------- -# -# TEST... -# -#-------------------- - -# Make a tester: -my $T = typical ExtUtils::TBone; - -# Set the counter: -unless ($] >= 5.004) { - $T->begin(1); - $T->ok(1); - $T->end; - exit 0; -} -$T->begin(6); - -my $hello = 'Hello, '; -my $world = "world!\n"; - -#### test -my $s = ''; -my $SH = new IO::WrapTie 'IO::Scalar', \$s; -$T->ok(1, "Construction"); - -#### test -print $SH $hello, $world; -$T->ok($s eq "$hello$world", - "print FH ARGS", - S => $s); - -#### test -$SH->print($hello, $world); -$T->ok($s eq "$hello$world$hello$world", - "FH->print(ARGS)", - S => $s); - -#### test -$SH->seek(0,0); -$T->ok(1, "FH->seek(0,0)"); - -#### test -@x = <$SH>; -$T->ok((($x[0] eq "$hello$world") && - ($x[1] eq "$hello$world") && - !$x[2]), - "array = <FH>"); - -#### test -my $sref = $SH->sref; -$T->ok($sref eq \$s, "FH->sref"); - - -# So we know everything went well... -$T->end; - - diff --git a/cpan/lib/IO/AtomicFile.pm b/cpan/lib/IO/AtomicFile.pm deleted file mode 100644 index 90bfce39..00000000 --- a/cpan/lib/IO/AtomicFile.pm +++ /dev/null @@ -1,190 +0,0 @@ -package IO::AtomicFile; - -### DOCUMENTATION AT BOTTOM OF FILE - -# Be strict: -use strict; - -# External modules: -use IO::File; - - -#------------------------------ -# -# GLOBALS... -# -#------------------------------ -use vars qw($VERSION @ISA); - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.105 $, 10; - -# Inheritance: -@ISA = qw(IO::File); - - -#------------------------------ -# new ARGS... -#------------------------------ -# Class method, constructor. -# Any arguments are sent to open(). -# -sub new { - my $class = shift; - my $self = $class->SUPER::new(); - ${*$self}{'io_atomicfile_suffix'} = ''; - $self->open(@_) if @_; - $self; -} - -#------------------------------ -# DESTROY -#------------------------------ -# Destructor. -# -sub DESTROY { - shift->close(1); # like close, but raises fatal exception on failure -} - -#------------------------------ -# open PATH, MODE -#------------------------------ -# Class/instance method. -# -sub open { - my ($self, $path, $mode) = @_; - ref($self) or $self = $self->new; # now we have an instance! - - # Create tmp path, and remember this info: - my $temp = "${path}..TMP" . ${*$self}{'io_atomicfile_suffix'}; - ${*$self}{'io_atomicfile_temp'} = $temp; - ${*$self}{'io_atomicfile_path'} = $path; - - # Open the file! Returns filehandle on success, for use as a constructor: - $self->SUPER::open($temp, $mode) ? $self : undef; -} - -#------------------------------ -# _closed [YESNO] -#------------------------------ -# Instance method, private. -# Are we already closed? Argument sets new value, returns previous one. -# -sub _closed { - my $self = shift; - my $oldval = ${*$self}{'io_atomicfile_closed'}; - ${*$self}{'io_atomicfile_closed'} = shift if @_; - $oldval; -} - -#------------------------------ -# close -#------------------------------ -# Instance method. -# Close the handle, and rename the temp file to its final name. -# -sub close { - my ($self, $die) = @_; - unless ($self->_closed(1)) { # sentinel... - $self->SUPER::close(); - rename(${*$self}{'io_atomicfile_temp'}, - ${*$self}{'io_atomicfile_path'}) - or ($die ? die "close atomic file: $!\n" : return undef); - } - 1; -} - -#------------------------------ -# delete -#------------------------------ -# Instance method. -# Close the handle, and delete the temp file. -# -sub delete { - my $self = shift; - unless ($self->_closed(1)) { # sentinel... - $self->SUPER::close(); - return unlink(${*$self}{'io_atomicfile_temp'}); - } - 1; -} - -#------------------------------ -# detach -#------------------------------ -# Instance method. -# Close the handle, but DO NOT delete the temp file. -# -sub detach { - my $self = shift; - $self->SUPER::close() unless ($self->_closed(1)); - 1; -} - -#------------------------------ -1; -__END__ - - -=head1 NAME - -IO::AtomicFile - write a file which is updated atomically - - -=head1 SYNOPSIS - - use IO::AtomicFile; - - # Write a temp file, and have it install itself when closed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->close || die "couldn't install atomic file: $!"; - - # Write a temp file, but delete it before it gets installed: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->delete; - - # Write a temp file, but neither install it nor delete it: - my $FH = IO::AtomicFile->open("bar.dat", "w"); - print $FH "Hello!\n"; - $FH->detach; - - -=head1 DESCRIPTION - -This module is intended for people who need to update files -reliably in the face of unexpected program termination. - -For example, you generally don't want to be halfway in the middle of -writing I</etc/passwd> and have your program terminate! Even -the act of writing a single scalar to a filehandle is I<not> atomic. - -But this module gives you true atomic updates, via rename(). -When you open a file I</foo/bar.dat> via this module, you are I<actually> -opening a temporary file I</foo/bar.dat..TMP>, and writing your -output there. The act of closing this file (either explicitly -via close(), or implicitly via the destruction of the object) -will cause rename() to be called... therefore, from the point -of view of the outside world, the file's contents are updated -in a single time quantum. - -To ensure that problems do not go undetected, the "close" method -done by the destructor will raise a fatal exception if the rename() -fails. The explicit close() just returns undef. - -You can also decide at any point to trash the file you've been -building. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head1 REVISION - -$Revision: 1.105 $ - -=cut diff --git a/cpan/lib/IO/InnerFile.pm b/cpan/lib/IO/InnerFile.pm deleted file mode 100644 index 4eca6d44..00000000 --- a/cpan/lib/IO/InnerFile.pm +++ /dev/null @@ -1,274 +0,0 @@ -package IO::InnerFile; - -=head1 NAME - -IO::InnerFile - define a file inside another file - - -=head1 SYNOPSIS - - - ### Read a subset of a file: - $inner = IO::InnerFile->new($fh, $start, $length); - while (<$inner>) { - ... - } - - -=head1 DESCRIPTION - -If you have a filehandle that can seek() and tell(), then you -can open an IO::InnerFile on a range of the underlying file. - - -=head1 PUBLIC INTERFACE - -=over - -=cut - -use Symbol; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.103 $, 10; - -#------------------------------ - -=item new FILEHANDLE, [START, [LENGTH]] - -I<Class method, constructor.> -Create a new inner-file opened on the given FILEHANDLE, -from bytes START to START+LENGTH. Both START and LENGTH -default to 0; negative values are silently coerced to zero. - -Note that FILEHANDLE must be able to seek() and tell(), in addition -to whatever other methods you may desire for reading it. - -=cut - -sub new { - my ($class, $fh, $start, $lg) = @_; - $start = 0 if (!$start or ($start < 0)); - $lg = 0 if (!$lg or ($lg < 0)); - - ### Create the underlying "object": - my $a = { - FH => $fh, - CRPOS => 0, - START => $start, - LG => $lg, - }; - - ### Create a new filehandle tied to this object: - $fh = gensym; - tie(*$fh, $class, $a); - return bless($fh, $class); -} - -sub TIEHANDLE { - my ($class, $data) = @_; - return bless($data, $class); -} - -sub DESTROY { - my ($self) = @_; - $self->close() if (ref($self) eq 'SCALAR'); -} - -#------------------------------ - -=item set_length LENGTH - -=item get_length - -=item add_length NBYTES - -I<Instance methods.> -Get/set the virtual length of the inner file. - -=cut - -sub set_length { tied(${$_[0]})->{LG} = $_[1]; } -sub get_length { tied(${$_[0]})->{LG}; } -sub add_length { tied(${$_[0]})->{LG} += $_[1]; } - -#------------------------------ - -=item set_start START - -=item get_start - -=item add_start NBYTES - -I<Instance methods.> -Get/set the virtual start position of the inner file. - -=cut - -sub set_start { tied(${$_[0]})->{START} = $_[1]; } -sub get_start { tied(${$_[0]})->{START}; } -sub set_end { tied(${$_[0]})->{LG} = $_[1] - tied(${$_[0]})->{START}; } -sub get_end { tied(${$_[0]})->{LG} + tied(${$_[0]})->{START}; } - - -#------------------------------ - -=item binmode - -=item close - -=item flush - -=item getc - -=item getline - -=item print LIST - -=item printf LIST - -=item read BUF, NBYTES - -=item readline - -=item seek OFFFSET, WHENCE - -=item tell - -=item write ARGS... - -I<Instance methods.> -Standard filehandle methods. - -=cut - -sub write { shift->WRITE(@_) } -sub print { shift->PRINT(@_) } -sub printf { shift->PRINTF(@_) } -sub flush { 1; } -sub binmode { 1; } -sub getc { return GETC(tied(${$_[0]}) ); } -sub read { return READ( tied(${$_[0]}), @_[1,2,3] ); } -sub readline { return READLINE( tied(${$_[0]}) ); } -sub getline { return READLINE( tied(${$_[0]}) ); } -sub close { return CLOSE(tied(${$_[0]}) ); } - -sub seek { - my ($self, $ofs, $whence) = @_; - $self = tied( $$self ); - - $self->{CRPOS} = $ofs if ($whence == 0); - $self->{CRPOS}+= $ofs if ($whence == 1); - $self->{CRPOS} = $self->{LG} + $ofs if ($whence == 2); - - $self->{CRPOS} = 0 if ($self->{CRPOS} < 0); - $self->{CRPOS} = $self->{LG} if ($self->{CRPOS} > $self->{LG}); -} - -sub tell { - return tied(${$_[0]})->{CRPOS}; -} - -sub WRITE { - die "inner files can only open for reading\n"; -} - -sub PRINT { - die "inner files can only open for reading\n"; -} - -sub PRINTF { - die "inner files can only open for reading\n"; -} - -sub GETC { - my ($self) = @_; - return 0 if ($self->{CRPOS} >= $self->{LG}); - - my $data; - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - my $lg = $self->{FH}->read($data, 1); - $self->{CRPOS} += $lg; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - $self->{LG} = $self->{CRPOS} unless ($lg); - return ($lg ? $data : undef); -} - -sub READ { - my ($self, $undefined, $lg, $ofs) = @_; - $undefined = undef; - - return 0 if ($self->{CRPOS} >= $self->{LG}); - $lg = $self->{LG} - $self->{CRPOS} if ($self->{CRPOS} + $lg > $self->{LG}); - return 0 unless ($lg); - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - $lg = $self->{FH}->read($_[1], $lg, $_[3] ); - $self->{CRPOS} += $lg; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - $self->{LG} = $self->{CRPOS} unless ($lg); - return $lg; -} - -sub READLINE { - my ($self) = @_; - return undef if ($self->{CRPOS} >= $self->{LG}); - - ### Save and seek... - my $old_pos = $self->{FH}->tell; - $self->{FH}->seek($self->{CRPOS}+$self->{START}, 0); - - ### ...read... - my $text = $self->{FH}->getline; - - ### ...and restore: - $self->{FH}->seek($old_pos, 0); - - #### If we detected a new EOF ... - unless (defined $text) { - $self->{LG} = $self->{CRPOS}; - return undef; - } - - my $lg=length($text); - - $lg = $self->{LG} - $self->{CRPOS} if ($self->{CRPOS} + $lg > $self->{LG}); - $self->{CRPOS} += $lg; - - return substr($text, 0,$lg); -} - -sub CLOSE { %{$_[0]}=(); } - - - -1; -__END__ - -=back - - -=head1 AUTHOR - -Original version by Doru Petrescu (pdoru@kappa.ro). - -Documentation and current maintenance by Eryq (eryq@zeegee.com). - -=cut - - diff --git a/cpan/lib/IO/Lines.pm b/cpan/lib/IO/Lines.pm deleted file mode 100644 index 50b67304..00000000 --- a/cpan/lib/IO/Lines.pm +++ /dev/null @@ -1,148 +0,0 @@ -package IO::Lines; - - -=head1 NAME - -IO::Lines - IO:: interface for reading/writing an array of lines - - -=head1 SYNOPSIS - - use IO::Lines; - - # See IO::ScalarArray for details - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) an array of lines. They can be tiehandle'd as well. - -This is a subclass of L<IO::ScalarArray|IO::ScalarArray> -in which the underlying -array has its data stored in a line-oriented-format: that is, -every element ends in a C<"\n">, with the possible exception of the -final element. This makes C<getline()> I<much> more efficient; -if you plan to do line-oriented reading/printing, you want this class. - -The C<print()> method will enforce this rule, so you can print -arbitrary data to the line-array: it will break the data at -newlines appropriately. - -See L<IO::ScalarArray> for full usage. - -=cut - -use Carp; -use strict; -use IO::ScalarArray; -use vars qw($VERSION @ISA); - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.110 $, 10; - -# Inheritance: -@ISA = qw(IO::ScalarArray); # also gets us new_tie :-) - - -#------------------------------ -# getline -#------------------------------ -# Instance method, override. -# Return the next line, or undef on end of data. -# Can safely be called in an array context. -# Currently, lines are delimited by "\n". -# -sub getline { - my $self = shift; - if (!defined $/) { - return join( '' => $self->getlines ); - } - ($/ eq "\n") - or croak '$/ must be "\n" or undef, not ', "'$/'."; - - if (!$self->{Pos}) { # full line... - return $self->{AR}[$self->{Str}++]; - } - else { # partial line... - my $partial = substr($self->{AR}[$self->{Str}++], $self->{Pos}); - $self->{Pos} = 0; - return $partial; - } -} - -#------------------------------ -# getlines -#------------------------------ -# Instance method, override. -# Return an array comprised of the remaining lines, or () on end of data. -# Must be called in an array context. -# Currently, lines are delimited by "\n". -# -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - - my ($rArray, $Str, $Pos) = @$self{ qw( AR Str Pos ) }; - my @partial = (); - - if ($Pos) { # partial line... - @partial = (substr( $rArray->[ $Str++ ], $Pos )); - $self->{Pos} = 0; - } - $self->{Str} = scalar @$rArray; # about to exhaust @$rArray - return (@partial, - @$rArray[ $Str .. $#$rArray ]); # remaining full lines... -} - -#------------------------------ -# print ARGS... -#------------------------------ -# Instance method, override. -# Print ARGS to the underlying line array. -# -sub print { - my $self = shift; - ### print STDERR "\n[[ARRAY WAS...\n", @{$self->{AR}}, "<<EOF>>\n"; - my @lines = split /^/, join('', @_); @lines or return 1; - - # Did the previous print not end with a newline? If so, append first line: - if (@{$self->{AR}} and ($self->{AR}[-1] !~ /\n\Z/)) { - $self->{AR}[-1] .= shift @lines; - } - push @{$self->{AR}}, @lines; # add the remainder - ### print STDERR "\n[[ARRAY IS NOW...\n", @{$self->{AR}}, "<<EOF>>\n"; - 1; -} - -#------------------------------ -1; - -__END__ - - -=head1 VERSION - -$Id: Lines.pm,v 1.110 2000/08/16 04:59:02 eryq Exp $ - - -=head1 AUTHORS - - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Morris M. Siegel,> -for his $/ patch and the new C<getlines()>. - -=cut - diff --git a/cpan/lib/IO/Scalar.pm b/cpan/lib/IO/Scalar.pm deleted file mode 100644 index 6287b5fb..00000000 --- a/cpan/lib/IO/Scalar.pm +++ /dev/null @@ -1,585 +0,0 @@ -package IO::Scalar; - - -=head1 NAME - -IO::Scalar - IO:: interface for reading/writing a scalar - - -=head1 SYNOPSIS - -If you have any Perl5, you can use the basic OO interface... - - use IO::Scalar; - - ### Open a handle on a string: - $SH = new IO::Scalar; - $SH->open(\$somestring); - - ### Open a handle on a string, read it line-by-line, then close it: - $SH = new IO::Scalar \$somestring; - while ($_ = $SH->getline) { print "Line: $_" } - $SH->close; - - ### Open a handle on a string, and slurp in all the lines: - $SH = new IO::Scalar \$somestring; - print $SH->getlines; - - ### Open a handle on a string, and append to it: - $SH = new IO::Scalar \$somestring - $SH->print("bar\n"); ### will add "bar\n" to the end - - ### Get the current position: - $pos = $SH->getpos; ### $SH->tell() also works - - ### Set the current position: - $SH->setpos($pos); ### $SH->seek(POS,WHENCE) also works - - ### Open an anonymous temporary scalar: - $SH = new IO::Scalar; - $SH->print("Hi there!"); - print "I got: ", ${$SH->sref}, "\n"; ### get at value - -If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write scalars just like files: - - use IO::Scalar; - - ### Writing to a scalar... - my $s; - tie *OUT, 'IO::Scalar', \$s; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... $s\n" - - ### Reading and writing an anonymous scalar... - tie *OUT, 'IO::Scalar'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } - -Stringification now works, too! - - my $SH = new IO::Scalar \$somestring; - $SH->print("Hello, "); - $SH->print("world!"); - print "I've got: <$SH>\n"; - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - -Basically, this: - - my $s; - $SH = new IO::Scalar \$s; - $SH->print("Hel", "lo, "); # OO style - $SH->print("world!\n"); # ditto - -Or this (if you have 5.004 or later): - - my $s; - $SH = tie *OUT, 'IO::Scalar', \$s; - print OUT "Hel", "lo, "; # non-OO style - print OUT "world!\n"; # ditto - -Or this (if you have 5.004 or later): - - my $s; - $SH = IO::Scalar->new_tie(\$s); - $SH->print("Hel", "lo, "); # OO style... - print $SH "world!\n"; # ...or non-OO style! - -Causes $s to be set to: - - "Hello, world!\n" - - -=head1 PUBLIC INTERFACE - -=cut - -use Carp; -use strict; -use vars qw($VERSION @ISA); -use IO::Handle; - -### Stringification, courtesy of B. K. Oxley (binkley): :-) -use overload '""' => sub { ${$_[0]->{SR}} }; -use overload 'bool' => sub { 1 }; ### have to do this, so object is true! - -### The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.122 $, 10; - -### Inheritance: -@ISA = qw(IO::Handle); -require IO::WrapTie and push @ISA, 'IO::WrapTie::Slave' if ($] >= 5.004); - - -#============================== - -=head2 Construction - -=over 4 - -=cut - -#------------------------------ - -=item new [ARGS...] - -I<Class method.> -Return a new, unattached scalar handle. -If any arguments are given, they're sent to open(). - -=cut - -sub new { - my $self = bless {}, shift; - $self->open(@_) if @_; - $self; -} -sub DESTROY { - shift->close; -} - -#------------------------------ - -=item open [SCALARREF] - -I<Instance method.> -Open the scalar handle on a new scalar, pointed to by SCALARREF. -If no SCALARREF is given, a "private" scalar is created to hold -the file data. - -Returns the self object on success, undefined on error. - -=cut - -sub open { - my ($self, $sref) = @_; - - # Sanity: - defined($sref) or do {my $s = ''; $sref = \$s}; - (ref($sref) eq "SCALAR") or croak "open() needs a ref to a scalar"; - - # Setup: - $self->{Pos} = 0; - $self->{SR} = $sref; - $self; -} - -#------------------------------ - -=item opened - -I<Instance method.> -Is the scalar handle opened on something? - -=cut - -sub opened { - shift->{SR}; -} - -#------------------------------ - -=item close - -I<Instance method.> -Disassociate the scalar handle from its underlying scalar. -Done automatically on destroy. - -=cut - -sub close { - my $self = shift; - %$self = (); - 1; -} - -=back - -=cut - - - -#============================== - -=head2 Input and output - -=over 4 - -=cut - - -#------------------------------ - -=item flush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub flush {} - -#------------------------------ - -=item getc - -I<Instance method.> -Return the next character, or undef if none remain. - -=cut - -sub getc { - my $self = shift; - - # Return undef right away if at EOF; else, move pos forward: - return undef if $self->eof; - substr(${$self->{SR}}, $self->{Pos}++, 1); -} - -#------------------------------ - -=item getline - -I<Instance method.> -Return the next line, or undef on end of string. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -=cut - -sub getline { - my $self = shift; - - # Return undef right away if at EOF: - return undef if $self->eof; - - # Get next line: - my $sr = $self->{SR}; - my $i = $self->{Pos}; # Start matching at this point. - my $len = length(${$sr}); - for (; $i < $len; ++$i) { - last if ord (substr (${$sr}, $i, 1)) == 10; - } - - # Extract the line: - my $line; - if ($i < $len) { - $line = substr (${$sr}, $self->{Pos}, $i - $self->{Pos} + 1); - $self->{Pos} = $i+1; # Remember where we finished up. - } - else { - $line = substr (${$sr}, $self->{Pos}, $i - $self->{Pos}); - $self->{Pos} = $len; - } - return $line; -} - -#------------------------------ - -=item getlines - -I<Instance method.> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -=cut - -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my ($line, @lines); - push @lines, $line while (defined($line = $self->getline)); - @lines; -} - -#------------------------------ - -=item print ARGS... - -I<Instance method.> -Print ARGS to the underlying scalar. - -B<Warning:> Currently, this always causes a "seek to the end of the string"; -this may change in the future. - -=cut - -sub print { - my $self = shift; - ${$self->{SR}} .= join('', @_); - $self->{Pos} = length(${$self->{SR}}); - 1; -} - -#------------------------------ - -=item read BUF, NBYTES, [OFFSET] - -I<Instance method.> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub read { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $read = substr(${$self->{SR}}, $self->{Pos}, $n); - $n = length($read); - $self->{Pos} += $n; - ($off ? substr($_[1], $off) : $_[1]) = $read; - return $n; -} - -#------------------------------ - -=item write BUF, NBYTES, [OFFSET] - -I<Instance method.> -Write some bytes to the scalar. - -=cut - -sub write { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $data = substr($_[1], $off, $n); - $n = length($data); - $self->print($data); - return $n; -} - -#------------------------------ - -=item sysread BUF, LEN, [OFFSET] - -I<Instance method.> -Read some bytes from the scalar. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub sysread { - my $self = shift; - $self->read (@_); -} - -#------------------------------ - -=item syswrite BUF, NBYTES, [OFFSET] - -I<Instance method.> -Write some bytes to the scalar. - -=cut - -sub syswrite { - my $self = shift; - $self->write (@_); -} - -=back - -=cut - - -#============================== - -=head2 Seeking/telling and other attributes - -=over 4 - -=cut - - -#------------------------------ - -=item autoflush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub autoflush {} - -#------------------------------ - -=item binmode - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub binmode {} - -#------------------------------ - -=item clearerr - -I<Instance method.> Clear the error and EOF flags. A no-op. - -=cut - -sub clearerr { 1 } - -#------------------------------ - -=item eof - -I<Instance method.> Are we at end of file? - -=cut - -sub eof { - my $self = shift; - ($self->{Pos} >= length(${$self->{SR}})); -} - -#------------------------------ - -=item seek OFFSET, WHENCE - -I<Instance method.> Seek to a given position in the stream. - -=cut - -sub seek { - my ($self, $pos, $whence) = @_; - my $eofpos = length(${$self->{SR}}); - - # Seek: - if ($whence == 0) { $self->{Pos} = $pos } # SEEK_SET - elsif ($whence == 1) { $self->{Pos} += $pos } # SEEK_CUR - elsif ($whence == 2) { $self->{Pos} = $eofpos + $pos} # SEEK_END - else { croak "bad seek whence ($whence)" } - - # Fixup: - if ($self->{Pos} < 0) { $self->{Pos} = 0 } - if ($self->{Pos} > $eofpos) { $self->{Pos} = $eofpos } - 1; -} - -#------------------------------ - -=item tell - -I<Instance method.> -Return the current position in the stream, as a numeric offset. - -=cut - -sub tell { shift->{Pos} } - -#------------------------------ - -=item setpos POS - -I<Instance method.> -Set the current position, using the opaque value returned by C<getpos()>. - -=cut - -sub setpos { shift->seek($_[0],0) } - -#------------------------------ - -=item getpos - -I<Instance method.> -Return the current position in the string, as an opaque object. - -=cut - -*getpos = \&tell; - - -#------------------------------ - -=item sref - -I<Instance method.> -Return a reference to the underlying scalar. - -=cut - -sub sref { shift->{SR} } - - -#------------------------------ -# Tied handle methods... -#------------------------------ - -# Conventional tiehandle interface: -sub TIEHANDLE { shift->new(@_) } -sub GETC { shift->getc(@_) } -sub PRINT { shift->print(@_) } -sub PRINTF { shift->print(sprintf(shift, @_)) } -sub READ { shift->read(@_) } -sub READLINE { wantarray ? shift->getlines(@_) : shift->getline(@_) } -sub WRITE { shift->write(@_); } -sub CLOSE { shift->close(@_); } - -#------------------------------------------------------------ - -1; - -__END__ - - - -=back - -=cut - -=head1 VERSION - -$Id: Scalar.pm,v 1.122 2000/09/28 06:32:28 eryq Exp $ - - -=head1 AUTHORS - - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -The full set of contributors always includes the folks mentioned -in L<IO::Stringy/"CHANGE LOG">. But just the same, special -thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Andy Glew,> -for contributing C<getc()>. - -I<Brandon Browning,> -for suggesting C<opened()>. - -I<David Richter,> -for finding and fixing the bug in C<PRINTF()>. - -I<Eric L. Brine,> -for his offset-using read() and write() implementations. - -I<Richard Jones> (F<rich@annexia.org>), -for his patches to massively improve the performance of C<getline()> -and add C<sysread> and C<syswrite>. - - -=cut diff --git a/cpan/lib/IO/ScalarArray.pm b/cpan/lib/IO/ScalarArray.pm deleted file mode 100644 index 7dec117b..00000000 --- a/cpan/lib/IO/ScalarArray.pm +++ /dev/null @@ -1,598 +0,0 @@ -package IO::ScalarArray; - - -=head1 NAME - -IO::ScalarArray - IO:: interface for reading/writing an array of scalars - - -=head1 SYNOPSIS - -If you have any Perl5, you can use the basic OO interface... - - use IO::ScalarArray; - - # Open a handle on an array-of-scalars: - $AH = new IO::ScalarArray; - $AH->open(\@a); - - # Open a handle on an array-of-scalars, read it line-by-line, - # then close it: - $AH = new IO::ScalarArray \@a; - while ($_ = $AH->getline) { print "Line: $_" } - $AH->close; - - # Open a handle on an array-of-scalars, and slurp in all the lines: - $AH = new IO::ScalarArray \@a; - print $AH->getlines; - - # Open a handle on an array-of-scalars, and append to it: - $AH = new IO::ScalarArray \@a; - $AH->print("bar\n"); - print "some string is now: ", $somestring, "\n"; - - # Get the current position: - $pos = $AH->getpos; ### $AH->tell() also works - - # Set the current position: - $AH->setpos($pos); ### $AH->seek(POS,WHENCE) also works - - # Open an anonymous temporary scalar array: - $AH = new IO::ScalarArray; - $AH->print("Hi there!\nHey there!\n"); - $AH->print("Ho there!\n"); - print "I got: ", @{$AH->aref}, "\n"; ### get at value - -If your Perl is 5.004 or later, you can use the TIEHANDLE -interface, and read/write as array-of-scalars just like files: - - use IO::ScalarArray; - - # Writing to a scalar array... - my @a; - tie *OUT, 'IO::ScalarArray', \@a; - print OUT "line 1\nline 2\n", "line 3\n"; - print "s is now... [", join('', @a), "]\n"; - - # Reading and writing an anonymous scalar array... - tie *OUT, 'IO::ScalarArray'; - print OUT "line 1\nline 2\n", "line 3\n"; - tied(OUT)->seek(0,0); - while (<OUT>) { print "LINE: ", $_ } - - -=head1 DESCRIPTION - -This class implements objects which behave just like FileHandle -(or IO::Handle) objects, except that you may use them to write to -(or read from) scalars. They can be tiehandle'd as well. - -For writing large amounts of data with individual print() statements, -this is likely to be more efficient than IO::Scalar. - -Basically, this: - - my @a; - $AH = new IO::ScalarArray \@a; - $AH->print("Hel", "lo, "); - $AH->print("world!\n"); - -Or this (if you have 5.004 or later): - - my @a; - $AH = tie *OUT, 'IO::ScalarArray', \@a; - print OUT "Hel", "lo, "; - print OUT "world!\n"; - -Causes @a to be set to the following arrayt of 3 strings: - - ( "Hel" , - "lo, " , - "world!\n" ) - -Compare this with IO::Scalar. - - -=head1 PUBLIC INTERFACE - -=cut - -use Carp; -use strict; -use vars qw($VERSION @ISA); -use IO::Handle; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.117 $, 10; - -# Inheritance: -@ISA = qw(IO::Handle); -require IO::WrapTie and push @ISA, 'IO::WrapTie::Slave' if ($] >= 5.004); - - -#============================== - -=head2 Construction - -=over 4 - -=cut - -#------------------------------ - -=item new [ARGS...] - -I<Class method.> -Return a new, unattached array handle. -If any arguments are given, they're sent to open(). - -=cut - -sub new { - my $self = bless {}, shift; - $self->open(@_) if @_; - $self; -} -sub DESTROY { - shift->close; -} - - -#------------------------------ - -=item open [ARRAYREF] - -I<Instance method.> -Open the array handle on a new array, pointed to by ARRAYREF. -If no ARRAYREF is given, a "private" array is created to hold -the file data. - -Returns the self object on success, undefined on error. - -=cut - -sub open { - my ($self, $aref) = @_; - - # Sanity: - defined($aref) or do {my @a; $aref = \@a}; - (ref($aref) eq "ARRAY") or croak "open needs a ref to a array"; - - # Setup: - $self->setpos([0,0]); - $self->{AR} = $aref; - $self; -} - -#------------------------------ - -=item opened - -I<Instance method.> -Is the array handle opened on something? - -=cut - -sub opened { - shift->{AR}; -} - -#------------------------------ - -=item close - -I<Instance method.> -Disassociate the array handle from its underlying array. -Done automatically on destroy. - -=cut - -sub close { - my $self = shift; - %$self = (); - 1; -} - -=back - -=cut - - - -#============================== - -=head2 Input and output - -=over 4 - -=cut - -#------------------------------ - -=item flush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub flush {} - -#------------------------------ - -=item getc - -I<Instance method.> -Return the next character, or undef if none remain. -This does a read(1), which is somewhat costly. - -=cut - -sub getc { - my $buf = ''; - ($_[0]->read($buf, 1) ? $buf : undef); -} - -#------------------------------ - -=item getline - -I<Instance method.> -Return the next line, or undef on end of data. -Can safely be called in an array context. -Currently, lines are delimited by "\n". - -=cut - -sub getline { - my $self = shift; - my ($str, $line) = (undef, ''); - - # Until we hit EOF (or exitted because of a found line): - until ($self->eof) { - # If at end of current string, go forward to next one (won't be EOF): - if ($self->_eos) {++$self->{Str}, $self->{Pos}=0}; - - # Get ref to current string in array, and set internal pos marker: - $str = \($self->{AR}[$self->{Str}]); # get current string - pos($$str) = $self->{Pos}; # start matching at this point - - # Get from here to either newline or end of string, and add to line: - $$str =~ m/\G(.*?)((\n)|\Z)/g; # match to 1st newline or EOS - $line .= $1.$2; # add it - $self->{Pos} += length($1.$2); # move forward by amount matched - return $line if $3; # done, got a line with "\n" - } - return ($line eq '') ? undef : $line; # return undef if EOF -} - -#------------------------------ - -=item getlines - -I<Instance method.> -Get all remaining lines. -It will croak() if accidentally called in a scalar context. - -=cut - -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my ($line, @lines); - push @lines, $line while (defined($line = $self->getline)); - @lines; -} - -#------------------------------ - -=item print ARGS... - -I<Instance method.> -Print ARGS to the underlying array. - -Currently, this always causes a "seek to the end of the array" -and generates a new array entry. This may change in the future. - -=cut - -sub print { - my $self = shift; - push @{$self->{AR}}, join('', @_); # add the data - $self->setpos([scalar(@{$self->{AR}}), 0]); - 1; -} - -#------------------------------ - -=item read BUF, NBYTES, [OFFSET]; - -I<Instance method.> -Read some bytes from the array. -Returns the number of bytes actually read, 0 on end-of-file, undef on error. - -=cut - -sub read { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - ### print "getline\n"; - my $justread; - my $len; - ($off ? substr($_[1], $off) : $_[1]) = ''; - - # Stop when we have zero bytes to go, or when we hit EOF: - until (!$n or $self->eof) { - # If at end of current string, go forward to next one (won't be EOF): - if ($self->_eos) { - ++$self->{Str}; - $self->{Pos} = 0; - } - - # Get longest possible desired substring of current string: - $justread = substr($self->{AR}[$self->{Str}], $self->{Pos}, $n); - $len = length($justread); - $_[1] .= $justread; - $n -= $len; - $self->{Pos} += $len; - } - return length($_[1])-$off; -} - -#------------------------------ - -=item write BUF, NBYTES, [OFFSET]; - -I<Instance method.> -Write some bytes into the array. - -=cut - -sub write { - my $self = $_[0]; - my $n = $_[2]; - my $off = $_[3] || 0; - - my $data = substr($_[1], $n, $off); - $n = length($data); - $self->print($data); - return $n; -} - - -=back - -=cut - - - -#============================== - -=head2 Seeking/telling and other attributes - -=over 4 - -=cut - -#------------------------------ - -=item autoflush - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub autoflush {} - -#------------------------------ - -=item binmode - -I<Instance method.> -No-op, provided for OO compatibility. - -=cut - -sub binmode {} - -#------------------------------ - -=item clearerr - -I<Instance method.> Clear the error and EOF flags. A no-op. - -=cut - -sub clearerr { 1 } - -#------------------------------ - -=item eof - -I<Instance method.> Are we at end of file? - -=cut - -sub eof { - ### print "checking EOF [$self->{Str}, $self->{Pos}]\n"; - ### print "SR = ", $#{$self->{AR}}, "\n"; - return 0 if ($_[0]->{Str} < $#{$_[0]->{AR}}); # before EOA - return 1 if ($_[0]->{Str} > $#{$_[0]->{AR}}); # after EOA - (($_[0]->{Str} == $#{$_[0]->{AR}}) && ($_[0]->_eos)); # at EOA, past EOS -} - -#------------------------------ -# -# _eos -# -# I<Instance method, private.> Are we at end of the CURRENT string? -# - -sub _eos { - ($_[0]->{Pos} >= length($_[0]->{AR}[$_[0]->{Str}])); # past last char -} - -#------------------------------ - -=item seek POS,WHENCE - -I<Instance method.> -Seek to a given position in the stream. -Only a WHENCE of 0 (SEEK_SET) is supported. - -=cut - -sub seek { - my ($self, $pos, $whence) = @_; - die "IO::ScalarArray::seek: whence of $whence not supported\n" if $whence; - - # Advance through array until done: - my $istr = 0; - while (($pos >= 0) && ($istr < scalar(@{$self->{AR}}))) { - if (length($self->{AR}[$istr]) > $pos) { # it's in this string! - return $self->setpos([$istr, $pos]); - } - else { # it's in next string - $pos -= length($self->{AR}[$istr++]); # move forward one string - } - } - # If we reached this point, pos is at or past end; zoom to EOF: - return $self->setpos([scalar(@{$self->{AR}}), 0]); -} - -#------------------------------ - -=item tell - -I<Instance method.> -Return the current position in the stream, as a numeric offset. - -=cut - -sub tell { - my $self = shift; - my $off = 0; - my ($s, $str_s); - for ($s = 0; $s < $self->{Str}; $s++) { # count all "whole" scalars - defined($str_s = $self->{AR}[$s]) or $str_s = ''; - ###print STDERR "COUNTING STRING $s (". length($str_s) . ")\n"; - $off += length($str_s); - } - ###print STDERR "COUNTING POS ($self->{Pos})\n"; - return ($off += $self->{Pos}); # plus the final, partial one -} - -#------------------------------ - -=item setpos POS - -I<Instance method.> -Seek to a given position in the array, using the opaque getpos() value. -Don't expect this to be a number. - -=cut - -sub setpos { - my ($self, $pos) = @_; - (ref($pos) eq 'ARRAY') or - die "setpos: only use a value returned by getpos!\n"; - ($self->{Str}, $self->{Pos}) = @$pos; -} - -#------------------------------ - -=item getpos - -I<Instance method.> -Return the current position in the array, as an opaque value. -Don't expect this to be a number. - -=cut - -sub getpos { - [$_[0]->{Str}, $_[0]->{Pos}]; -} - -#------------------------------ - -=item aref - -I<Instance method.> -Return a reference to the underlying array. - -=cut - -sub aref { - shift->{AR}; -} - -=back - -=cut - -#------------------------------ -# Tied handle methods... -#------------------------------ - -# Conventional tiehandle interface: -sub TIEHANDLE { shift->new(@_) } -sub GETC { shift->getc(@_) } -sub PRINT { shift->print(@_) } -sub PRINTF { shift->print(sprintf(shift, @_)) } -sub READ { shift->read(@_) } -sub READLINE { wantarray ? shift->getlines(@_) : shift->getline(@_) } -sub WRITE { shift->write(@_); } -sub CLOSE { shift->close(@_); } - -#------------------------------------------------------------ - -1; -__END__ - -# SOME PRIVATE NOTES: -# -# * The "current position" is the position before the next -# character to be read/written. -# -# * Str gives the string index of the current position, 0-based -# -# * Pos gives the offset within AR[Str], 0-based. -# -# * Inital pos is [0,0]. After print("Hello"), it is [1,0]. - - -=head1 VERSION - -$Id: ScalarArray.pm,v 1.117 2000/09/28 06:32:28 eryq Exp $ - - -=head1 AUTHOR - -=head2 Principal author - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - - -=head2 Other contributors - -Thanks to the following individuals for their invaluable contributions -(if I've forgotten or misspelled your name, please email me!): - -I<Andy Glew,> -for suggesting C<getc()>. - -I<Brandon Browning,> -for suggesting C<opened()>. - -I<Eric L. Brine,> -for his offset-using read() and write() implementations. - -=cut - -#------------------------------ -1; - diff --git a/cpan/lib/IO/Stringy.pm b/cpan/lib/IO/Stringy.pm deleted file mode 100644 index c7b5d369..00000000 --- a/cpan/lib/IO/Stringy.pm +++ /dev/null @@ -1,193 +0,0 @@ -package IO::Stringy; - -use vars qw($VERSION); -$VERSION = substr q$Revision: 1.216 $, 10; - -1; -__END__ - - -=head1 NAME - -IO-stringy - I/O on in-core objects like strings and arrays - - -=head1 SYNOPSIS - - IO:: - ::AtomicFile adpO Write a file which is updated atomically ERYQ - ::Lines bdpO I/O handle to read/write to array of lines ERYQ - ::Scalar RdpO I/O handle to read/write to a string ERYQ - ::ScalarArray RdpO I/O handle to read/write to array of scalars ERYQ - ::Wrap RdpO Wrap old-style FHs in standard OO interface ERYQ - ::WrapTie adpO Tie your handles & retain full OO interface ERYQ - - -=head1 DESCRIPTION - -This toolkit primarily provides modules for performing both traditional -and object-oriented i/o) on things I<other> than normal filehandles; -in particular, L<IO::Scalar|IO::Scalar>, L<IO::ScalarArray|IO::ScalarArray>, -and L<IO::Lines|IO::Lines>. - -If you have access to tie(), these classes will make use of the -L<IO::WrapTie|IO::WrapTie> module to inherit a convenient new_tie() -constructor. It also exports a nice wraptie() function. - -In the more-traditional IO::Handle front, we -have L<IO::AtomicFile|IO::AtomicFile> -which may be used to painlessly create files which are updated -atomically. - -And in the "this-may-prove-useful" corner, we have L<IO::Wrap|IO::Wrap>, -whose exported wraphandle() function will clothe anything that's not -a blessed object in an IO::Handle-like wrapper... so you can just -use OO syntax and stop worrying about whether your function's caller -handed you a string, a globref, or a FileHandle. - - -=head1 INSTALLATION - -You know the drill... - - perl Makefile.PL - make test - make install - - - -=head1 VERSION - -$Id: Stringy.pm,v 1.216 2000/09/28 06:32:28 eryq Exp $ - - - -=head1 CHANGE LOG - -=over 4 - -=item Version 1.216 (2000/09/28) - -B<IO::Scalar and IO::ScalarArray now inherit from IO::Handle.> -I thought I'd remembered a problem with this ages ago, related to -the fact that these IO:: modules don't have "real" filehandles, -but the problem apparently isn't surfacing now. -If you suddenly encounter Perl warnings during global destruction -(especially if you're using tied filehandles), then please let me know! -I<Thanks to B. K. Oxley (binkley) for this.> - -B<Nasty bug fixed in IO::Scalar::write().> -Apparently, the offset and the number-of-bytes arguments were, -for all practical purposes, I<reversed.> You were okay if -you did all your writing with print(), but boy was I<this> a stupid bug! -I<Thanks to Richard Jones for finding this one. -For you, Rich, a double-length haiku:> - - Newspaper headline - typeset by dyslexic man - loses urgency - - BABY EATS FISH is - simply not equivalent - to FISH EATS BABY - -B<New sysread and syswrite methods for IO::Scalar.> -I<Thanks again to Richard Jones for this.> - - -=item Version 1.215 (2000/09/05) - -Added 'bool' overload to '""' overload, so object always evaluates -to true. (Whew. Glad I caught this before it went to CPAN.) - - -=item Version 1.214 (2000/09/03) - -Evaluating an IO::Scalar in a string context now yields -the underlying string. -I<Thanks to B. K. Oxley (binkley) for this.> - - -=item Version 1.213 (2000/08/16) - -Minor documentation fixes. - - -=item Version 1.212 (2000/06/02) - -Fixed IO::InnerFile incompatibility with Perl5.004. -I<Thanks to many folks for reporting this.> - - -=item Version 1.210 (2000/04/17) - -Added flush() and other no-op methods. -I<Thanks to Doru Petrescu for suggesting this.> - - -=item Version 1.209 (2000/03/17) - -Small bug fixes. - - -=item Version 1.208 (2000/03/14) - -Incorporated a number of contributed patches and extensions, -mostly related to speed hacks, support for "offset", and -WRITE/CLOSE methods. -I<Thanks to Richard Jones, Doru Petrescu, and many others.> - - - -=item Version 1.206 (1999/04/18) - -Added creation of ./testout when Makefile.PL is run. - - -=item Version 1.205 (1999/01/15) - -Verified for Perl5.005. - - -=item Version 1.202 (1998/04/18) - -New IO::WrapTie and IO::AtomicFile added. - - -=item Version 1.110 - -Added IO::WrapTie. - - -=item Version 1.107 - -Added IO::Lines, and made some bug fixes to IO::ScalarArray. -Also, added getc(). - - -=item Version 1.105 - -No real changes; just upgraded IO::Wrap to have a $VERSION string. - -=back - - - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -Enjoy. Yell if it breaks. - - -=cut - - - - - - - - diff --git a/cpan/lib/IO/Wrap.pm b/cpan/lib/IO/Wrap.pm deleted file mode 100644 index 6eae65b3..00000000 --- a/cpan/lib/IO/Wrap.pm +++ /dev/null @@ -1,211 +0,0 @@ -package IO::Wrap; - -# SEE DOCUMENTATION AT BOTTOM OF FILE - -require 5.002; - -use strict; -use vars qw(@ISA @EXPORT $VERSION); -@ISA = qw(Exporter); -@EXPORT = qw(wraphandle); - -use FileHandle; -use Carp; - -# The package version, both in 1.23 style *and* usable by MakeMaker: -$VERSION = substr q$Revision: 1.104 $, 10; - - -#------------------------------ -# wraphandle RAW -#------------------------------ -sub wraphandle { - my $raw = shift; - new IO::Wrap $raw; -} - -#------------------------------ -# new STREAM -#------------------------------ -sub new { - my ($class, $stream) = @_; - no strict 'refs'; - - # Convert raw scalar to globref: - ref($stream) or $stream = \*$stream; - - # Wrap globref and incomplete objects: - if ((ref($stream) eq 'GLOB') or # globref - (ref($stream) eq 'FileHandle') && !defined(&FileHandle::read)) { - return bless \$stream, $class; - } - $stream; # already okay! -} - -#------------------------------ -# I/O methods... -#------------------------------ -sub close { - my $self = shift; - return close($$self); -} -sub getline { - my $self = shift; - my $fh = $$self; - return scalar(<$fh>); -} -sub getlines { - my $self = shift; - wantarray or croak("Can't call getlines in scalar context!"); - my $fh = $$self; - <$fh>; -} -sub print { - my $self = shift; - print { $$self } @_; -} -sub read { - my $self = shift; - return read($$self, $_[0], $_[1]); -} -sub seek { - my $self = shift; - return seek($$self, $_[0], $_[1]); -} -sub tell { - my $self = shift; - return tell($$self); -} - -#------------------------------ -1; -__END__ - - -=head1 NAME - -IO::Wrap - wrap raw filehandles in IO::Handle interface - - -=head1 SYNOPSIS - - 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!"); - ... - } - - -=head1 DESCRIPTION - -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: - - do_stuff(\*STDOUT); - do_stuff('STDERR'); - do_stuff($some_FileHandle_object); - do_stuff($some_IO_Handle_object); - -And even: - - do_stuff($any_object_with_a_print_method); - -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>, which provides you with the following functions: - - -=over 4 - -=item wraphandle SCALAR - -This function will take a single argument, and "wrap" it based on -what it seems to be... - -=over 4 - -=item * - -B<A raw scalar filehandle name,> like C<"STDOUT"> or C<"Class::HANDLE">. -In this case, the filehandle name is wrapped in an IO::Wrap object, -which is returned. - -=item * - -B<A raw filehandle glob,> like C<\*STDOUT>. -In this case, the filehandle glob is wrapped in an IO::Wrap object, -which is returned. - -=item * - -B<A blessed FileHandle object.> -In this case, the FileHandle is wrapped in an IO::Wrap object if and only -if your FileHandle class does not support the C<read()> method. - -=item * - -B<Any other kind of blessed object,> which is assumed to be already -conformant to the IO::Handle interface. -In this case, you just get back that object. - -=back - -=back - - -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>, not named operators) should work on the thing you get back: - - close - getline - getlines - print ARGS... - read BUFFER,NBYTES - seek POS,WHENCE - tell - - - -=head1 NOTES - -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. - -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. - - -=head1 WARNINGS - -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 C<\*FOO> -or as C<"Foo::FOO">. However, C<"STDIN"> and friends will work just fine. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -=cut - diff --git a/cpan/lib/IO/WrapTie.pm b/cpan/lib/IO/WrapTie.pm deleted file mode 100644 index 2535e74b..00000000 --- a/cpan/lib/IO/WrapTie.pm +++ /dev/null @@ -1,480 +0,0 @@ -# SEE DOCUMENTATION AT BOTTOM OF FILE - - -#------------------------------------------------------------ -package IO::WrapTie; -#------------------------------------------------------------ -require 5.004; # for tie -use strict; -use vars qw(@ISA @EXPORT $VERSION); -use Exporter; - -# Inheritance, exporting, and package version: -@ISA = qw(Exporter); -@EXPORT = qw(wraptie); -$VERSION = substr q$Revision: 1.108 $, 10; - -# Function, exported. -sub wraptie { - IO::WrapTie::Master->new(@_); -} - -# Class method; BACKWARDS-COMPATIBILITY ONLY! -sub new { - shift; - IO::WrapTie::Master->new(@_); -} - - - -#------------------------------------------------------------ -package IO::WrapTie::Master; -#------------------------------------------------------------ - -use strict; -use vars qw(@ISA $AUTOLOAD); -use IO::Handle; - -# We inherit from IO::Handle to get methods which invoke i/o operators, -# like print(), on our tied handle: -@ISA = qw(IO::Handle); - -#------------------------------ -# new SLAVE, TIEARGS... -#------------------------------ -# Create a new subclass of IO::Handle which... -# -# (1) Handles i/o OPERATORS because it is tied to an instance of -# an i/o-like class, like IO::Scalar. -# -# (2) Handles i/o METHODS by delegating them to that same tied object!. -# -# Arguments are the slave class (e.g., IO::Scalar), followed by all -# the arguments normally sent into that class's TIEHANDLE method. -# In other words, much like the arguments to tie(). :-) -# -# NOTE: -# The thing $x we return must be a BLESSED REF, for ($x->print()). -# The underlying symbol must be a FILEHANDLE, for (print $x "foo"). -# It has to have a way of getting to the "real" back-end object... -# -sub new { - my $master = shift; - my $io = IO::Handle->new; # create a new handle - my $slave = shift; - tie *$io, $slave, @_; # tie: will invoke slave's TIEHANDLE - bless $io, $master; # return a master -} - -#------------------------------ -# AUTOLOAD -#------------------------------ -# Delegate method invocations on the master to the underlying slave. -# -sub AUTOLOAD { - my $method = $AUTOLOAD; - $method =~ s/.*:://; - my $self = shift; tied(*$self)->$method(\@_); -} - -#------------------------------ -# PRELOAD -#------------------------------ -# Utility. -# -# Most methods like print(), getline(), etc. which work on the tied object -# via Perl's i/o operators (like 'print') are inherited from IO::Handle. -# -# Other methods, like seek() and sref(), we must delegate ourselves. -# AUTOLOAD takes care of these. -# -# However, it may be necessary to preload delegators into your -# own class. PRELOAD will do this. -# -sub PRELOAD { - my $class = shift; - foreach (@_) { - eval "sub ${class}::$_ { my \$s = shift; tied(*\$s)->$_(\@_) }"; - } -} - -# Preload delegators for some standard methods which we can't simply -# inherit from IO::Handle... for example, some IO::Handle methods -# assume that there is an underlying file descriptor. -# -PRELOAD IO::WrapTie::Master - qw(open opened close read clearerr eof seek tell setpos getpos); - - - -#------------------------------------------------------------ -package IO::WrapTie::Slave; -#------------------------------------------------------------ -# Teeny private class providing a new_tie constructor... -# -# HOW IT ALL WORKS: -# -# Slaves inherit from this class. -# -# When you send a new_tie() message to a tie-slave class (like IO::Scalar), -# it first determines what class should provide its master, via TIE_MASTER. -# In this case, IO::Scalar->TIE_MASTER would return IO::Scalar::Master. -# Then, we create a new master (an IO::Scalar::Master) with the same args -# sent to new_tie. -# -# In general, the new() method of the master is inherited directly -# from IO::WrapTie::Master. -# -sub new_tie { - my $self = shift; - $self->TIE_MASTER->new($self,@_); # e.g., IO::Scalar::Master->new(@_) -} - -# Default class method for new_tie(). -# All your tie-slave class (like IO::Scalar) has to do is override this -# method with a method that returns the name of an appropriate "master" -# class for tying that slave. -# -sub TIE_MASTER { 'IO::WrapTie::Master' } - -#------------------------------ -1; -__END__ - - -package IO::WrapTie; # for doc generator - - -=head1 NAME - -IO::WrapTie - wrap tieable objects in IO::Handle interface - -I<This is currently Alpha code, released for comments. - Please give me your feedback!> - - -=head1 SYNOPSIS - -First of all, you'll need tie(), so: - - require 5.004; - -I<Function interface (experimental).> -Use this with any existing class... - - use IO::WrapTie; - use FooHandle; # implements TIEHANDLE interface - - # Suppose we want a "FooHandle->new(&FOO_RDWR, 2)". - # We can instead say... - - $FH = wraptie('FooHandle', &FOO_RDWR, 2); - - # Now we can use... - print $FH "Hello, "; # traditional operator syntax... - $FH->print("world!\n"); # ...and OO syntax as well! - -I<OO interface (preferred).> -You can inherit from the IO::WrapTie::Slave mixin to get a -nifty C<new_tie()> constructor... - - #------------------------------ - package FooHandle; # a class which can TIEHANDLE - - use IO::WrapTie; - @ISA = qw(IO::WrapTie::Slave); # inherit new_tie() - ... - - - #------------------------------ - package main; - - $FH = FooHandle->new_tie(&FOO_RDWR, 2); # $FH is an IO::WrapTie::Master - print $FH "Hello, "; # traditional operator syntax - $FH->print("world!\n"); # OO syntax - -See IO::Scalar as an example. It also shows you how to create classes -which work both with and without 5.004. - - -=head1 DESCRIPTION - -Suppose you have a class C<FooHandle>, where... - -=over 4 - -=item * - -B<FooHandle does not inherit from IO::Handle;> that is, it performs -filehandle-like I/O, but to something other than an underlying -file descriptor. Good examples are IO::Scalar (for printing to a -string) and IO::Lines (for printing to an array of lines). - -=item * - -B<FooHandle implements the TIEHANDLE interface> (see L<perltie>); -that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, -READ, and READLINE. - -=item * - -B<FooHandle implements the traditional OO interface> of -FileHandle and IO::Handle; i.e., it contains methods like getline(), -read(), print(), seek(), tell(), eof(), etc. - -=back - - -Normally, users of your class would have two options: - - -=over 4 - -=item * - -B<Use only OO syntax,> and forsake named I/O operators like 'print'. - -=item * - -B<Use with tie,> and forsake treating it as a first-class object -(i.e., class-specific methods can only be invoked through the underlying -object via tied()... giving the object a "split personality"). - -=back - - -But now with IO::WrapTie, you can say: - - $WT = wraptie('FooHandle', &FOO_RDWR, 2); - $WT->print("Hello, world\n"); # OO syntax - print $WT "Yes!\n"; # Named operator syntax too! - $WT->weird_stuff; # Other methods! - -And if you're authoring a class like FooHandle, just have it inherit -from C<IO::WrapTie::Slave> and that first line becomes even prettier: - - $WT = FooHandle->new_tie(&FOO_RDWR, 2); - -B<The bottom line:> now, almost any class can look and work exactly like -an IO::Handle... and be used both with OO and non-OO filehandle syntax. - - -=head1 HOW IT ALL WORKS - - -=head2 The data structures - -Consider this example code, using classes in this distribution: - - use IO::Scalar; - use IO::WrapTie; - - $WT = wraptie('IO::Scalar',\$s); - print $WT "Hello, "; - $WT->print("world!\n"); - -In it, the wraptie() function creates a data structure as follows: - - * $WT is a blessed reference to a tied filehandle - $WT glob; that glob is tied to the "Slave" object. - | * You would do all your i/o with $WT directly. - | - | - | ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle - V / - .-------------. - | | - | | * Perl i/o operators work on the tied object, - | "Master" | invoking the TIEHANDLE methods. - | | * Method invocations are delegated to the tied - | | slave. - `-------------' - | - tied(*$WT) | .---isa--> IO::WrapTie::Slave - V / - .-------------. - | | - | "Slave" | * Instance of FileHandle-like class which doesn't - | | actually use file descriptors, like IO::Scalar. - | IO::Scalar | * The slave can be any kind of object. - | | * Must implement the TIEHANDLE interface. - `-------------' - - -I<NOTE:> just as an IO::Handle is really just a blessed reference to a -I<traditional> filehandle glob... so also, an IO::WrapTie::Master -is really just a blessed reference to a filehandle -glob I<which has been tied to some "slave" class.> - - -=head2 How wraptie() works - -=over 4 - -=item 1. - -The call to function C<wraptie(SLAVECLASS, TIEARGS...)> is -passed onto C<IO::WrapTie::Master::new()>. -Note that class IO::WrapTie::Master is a subclass of IO::Handle. - -=item 2. - -The C<IO::WrapTie::Master::new> method creates a new IO::Handle object, -reblessed into class IO::WrapTie::Master. This object is the I<master>, -which will be returned from the constructor. At the same time... - -=item 3. - -The C<new> method also creates the I<slave>: this is an instance -of SLAVECLASS which is created by tying the master's IO::Handle -to SLAVECLASS via C<tie(HANDLE, SLAVECLASS, TIEARGS...)>. -This call to C<tie()> creates the slave in the following manner: - -=item 4. - -Class SLAVECLASS is sent the message C<TIEHANDLE(TIEARGS...)>; it -will usually delegate this to C<SLAVECLASS::new(TIEARGS...)>, resulting -in a new instance of SLAVECLASS being created and returned. - -=item 5. - -Once both master and slave have been created, the master is returned -to the caller. - -=back - - -=head2 How I/O operators work (on the master) - -Consider using an i/o operator on the master: - - print $WT "Hello, world!\n"; - -Since the master ($WT) is really a [blessed] reference to a glob, -the normal Perl i/o operators like C<print> may be used on it. -They will just operate on the symbol part of the glob. - -Since the glob is tied to the slave, the slave's PRINT method -(part of the TIEHANDLE interface) will be automatically invoked. - -If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be -invoked, and that method happens to delegate to the C<print()> method -of the same class. So the I<real> work is ultimately done by -IO::Scalar::print(). - - -=head2 How methods work (on the master) - -Consider using a method on the master: - - $WT->print("Hello, world!\n"); - -Since the master ($WT) is blessed into the class IO::WrapTie::Master, -Perl first attempts to find a C<print()> method there. Failing that, -Perl next attempts to find a C<print()> method in the superclass, -IO::Handle. It just so happens that there I<is> such a method; -that method merely invokes the C<print> i/o operator on the self object... -and for that, see above! - -But let's suppose we're dealing with a method which I<isn't> part -of IO::Handle... for example: - - my $sref = $WT->sref; - -In this case, the intuitive behavior is to have the master delegate the -method invocation to the slave (now do you see where the designations -come from?). This is indeed what happens: IO::WrapTie::Master contains -an AUTOLOAD method which performs the delegation. - -So: when C<sref()> can't be found in IO::Handle, the AUTOLOAD method -of IO::WrapTie::Master is invoked, and the standard behavior of -delegating the method to the underlying slave (here, an IO::Scalar) -is done. - -Sometimes, to get this to work properly, you may need to create -a subclass of IO::WrapTie::Master which is an effective master for -I<your> class, and do the delegation there. - - - - -=head1 NOTES - -B<Why not simply use the object's OO interface?> - Because that means forsaking the use of named operators -like print(), and you may need to pass the object to a subroutine -which will attempt to use those operators: - - $O = FooHandle->new(&FOO_RDWR, 2); - $O->print("Hello, world\n"); # OO syntax is okay, BUT.... - - sub nope { print $_[0] "Nope!\n" } - X nope($O); # ERROR!!! (not a glob ref) - - -B<Why not simply use tie()?> - Because (1) you have to use tied() to invoke methods in the -object's public interface (yuck), and (2) you may need to pass -the tied symbol to another subroutine which will attempt to treat -it in an OO-way... and that will break it: - - tie *T, 'FooHandle', &FOO_RDWR, 2; - print T "Hello, world\n"; # Operator is okay, BUT... - - tied(*T)->other_stuff; # yuck! AND... - - sub nope { shift->print("Nope!\n") } - X nope(\*T); # ERROR!!! (method "print" on unblessed ref) - - -B<Why a master and slave? - Why not simply write FooHandle to inherit from IO::Handle?> - I tried this, with an implementation similar to that of IO::Socket. -The problem is that I<the whole point is to use this with objects -that don't have an underlying file/socket descriptor.>. -Subclassing IO::Handle will work fine for the OO stuff, and fine with -named operators I<if> you tie()... but if you just attempt to say: - - $IO = FooHandle->new(&FOO_RDWR, 2); - print $IO "Hello!\n"; - -you get a warning from Perl like: - - Filehandle GEN001 never opened - -because it's trying to do system-level i/o on an (unopened) file -descriptor. To avoid this, you apparently have to tie() the handle... -which brings us right back to where we started! At least the -IO::WrapTie mixin lets us say: - - $IO = FooHandle->new_tie(&FOO_RDWR, 2); - print $IO "Hello!\n"; - -and so is not I<too> bad. C<:-)> - - -=head1 WARNINGS - -Remember: this stuff is for doing FileHandle-like i/o on things -I<without underlying file descriptors>. If you have an underlying -file descriptor, you're better off just inheriting from IO::Handle. - -B<Be aware that new_tie() always returns an instance of a -kind of IO::WrapTie::Master...> it does B<not> return an instance -of the i/o class you're tying to! - -Invoking some methods on the master object causes AUTOLOAD to delegate -them to the slave object... so it I<looks> like you're manipulating a -"FooHandle" object directly, but you're not. - -I have not explored all the ramifications of this use of tie(). -I<Here there be dragons>. - - -=head1 AUTHOR - -Eryq (F<eryq@zeegee.com>). -President, ZeeGee Software Inc (F<http://www.zeegee.com>). - -=cut - |
