summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorfukachan <fukachan>2001-02-27 07:24:14 +0000
committerfukachan <fukachan>2001-02-27 07:24:14 +0000
commitd2b53f9d7b64533b013228943f22bd132233b9a5 (patch)
treedd7c22fbbbc3b78253874fb11da75602f386c57d
parentbd024ba03f18d40e864cfec8c6f4afa7e6e37c16 (diff)
downloadfml8-d2b53f9d7b64533b013228943f22bd132233b9a5.tar.gz
fml8-d2b53f9d7b64533b013228943f22bd132233b9a5.tar.bz2
fml8-d2b53f9d7b64533b013228943f22bd132233b9a5.zip
Initial revision
-rw-r--r--cpan/dist/IO-stringy/MANIFEST32
-rwxr-xr-xcpan/dist/IO-stringy/Makefile.PL22
-rw-r--r--cpan/dist/IO-stringy/README119
-rw-r--r--cpan/dist/IO-stringy/README.system8
-rw-r--r--cpan/dist/IO-stringy/docs/IO/AtomicFile.pm.html101
-rw-r--r--cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html126
-rw-r--r--cpan/dist/IO-stringy/docs/IO/Lines.pm.html103
-rw-r--r--cpan/dist/IO-stringy/docs/IO/Scalar.pm.html361
-rw-r--r--cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html338
-rw-r--r--cpan/dist/IO-stringy/docs/IO/Stringy.pm.html208
-rw-r--r--cpan/dist/IO-stringy/docs/IO/Wrap.pm.html169
-rw-r--r--cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html418
-rw-r--r--cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gifbin0 -> 421 bytes
-rw-r--r--cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gifbin0 -> 345 bytes
-rw-r--r--cpan/dist/IO-stringy/docs/IO/icons/zeegee.gifbin0 -> 5269 bytes
-rw-r--r--cpan/dist/IO-stringy/docs/index-menu.html31
-rw-r--r--cpan/dist/IO-stringy/docs/index.html13
-rw-r--r--cpan/dist/IO-stringy/docs/index.menu30
-rw-r--r--cpan/dist/IO-stringy/lib/IO/AtomicFile.pm190
-rw-r--r--cpan/dist/IO-stringy/lib/IO/InnerFile.pm274
-rw-r--r--cpan/dist/IO-stringy/lib/IO/Lines.pm148
-rw-r--r--cpan/dist/IO-stringy/lib/IO/Scalar.pm585
-rw-r--r--cpan/dist/IO-stringy/lib/IO/ScalarArray.pm598
-rw-r--r--cpan/dist/IO-stringy/lib/IO/Stringy.pm193
-rw-r--r--cpan/dist/IO-stringy/lib/IO/Wrap.pm211
-rw-r--r--cpan/dist/IO-stringy/lib/IO/WrapTie.pm480
-rw-r--r--cpan/dist/IO-stringy/t/Common.pm255
-rw-r--r--cpan/dist/IO-stringy/t/ExtUtils/TBone.pm534
-rw-r--r--cpan/dist/IO-stringy/t/IO_Lines.t43
-rw-r--r--cpan/dist/IO-stringy/t/IO_Scalar.t51
-rw-r--r--cpan/dist/IO-stringy/t/IO_ScalarArray.t49
-rw-r--r--cpan/dist/IO-stringy/t/IO_WrapTie.t66
-rw-r--r--cpan/lib/IO/AtomicFile.pm190
-rw-r--r--cpan/lib/IO/InnerFile.pm274
-rw-r--r--cpan/lib/IO/Lines.pm148
-rw-r--r--cpan/lib/IO/Scalar.pm585
-rw-r--r--cpan/lib/IO/ScalarArray.pm598
-rw-r--r--cpan/lib/IO/Stringy.pm193
-rw-r--r--cpan/lib/IO/Wrap.pm211
-rw-r--r--cpan/lib/IO/WrapTie.pm480
40 files changed, 8435 insertions, 0 deletions
diff --git a/cpan/dist/IO-stringy/MANIFEST b/cpan/dist/IO-stringy/MANIFEST
new file mode 100644
index 00000000..88f05544
--- /dev/null
+++ b/cpan/dist/IO-stringy/MANIFEST
@@ -0,0 +1,32 @@
+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
new file mode 100755
index 00000000..aeecddc2
--- /dev/null
+++ b/cpan/dist/IO-stringy/Makefile.PL
@@ -0,0 +1,22 @@
+#!/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
new file mode 100644
index 00000000..26e28f18
--- /dev/null
+++ b/cpan/dist/IO-stringy/README
@@ -0,0 +1,119 @@
+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
new file mode 100644
index 00000000..f108bff0
--- /dev/null
+++ b/cpan/dist/IO-stringy/README.system
@@ -0,0 +1,8 @@
+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
new file mode 100644
index 00000000..8907c02b
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/AtomicFile.pm.html
@@ -0,0 +1,101 @@
+<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-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
+ print $FH &quot;Hello!\n&quot;;
+ $FH-&gt;close || die &quot;couldn't install atomic file: $!&quot;;
+
+ # Write a temp file, but delete it before it gets installed:
+ my $FH = IO::AtomicFile-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
+ print $FH &quot;Hello!\n&quot;;
+ $FH-&gt;delete;
+
+ # Write a temp file, but neither install it nor delete it:
+ my $FH = IO::AtomicFile-&gt;open(&quot;bar.dat&quot;, &quot;w&quot;);
+ print $FH &quot;Hello!\n&quot;;
+ $FH-&gt;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 &quot;close&quot; 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
new file mode 100644
index 00000000..b0f3a5b6
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html
@@ -0,0 +1,126 @@
+<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-&gt;new($fh, $start, $length);
+ while (&lt;$inner&gt;) {
+ ...
+ }
+</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
new file mode 100644
index 00000000..a95a3695
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/Lines.pm.html
@@ -0,0 +1,103 @@
+<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>&quot;\n&quot;</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
new file mode 100644
index 00000000..015bfa5e
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html
@@ -0,0 +1,361 @@
+<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-&gt;open(\$somestring);
+
+ ### Open a handle on a string, read it line-by-line, then close it:
+ $SH = new IO::Scalar \$somestring;
+ while ($_ = $SH-&gt;getline) { print &quot;Line: $_&quot; }
+ $SH-&gt;close;
+
+ ### Open a handle on a string, and slurp in all the lines:
+ $SH = new IO::Scalar \$somestring;
+ print $SH-&gt;getlines;
+
+ ### Open a handle on a string, and append to it:
+ $SH = new IO::Scalar \$somestring
+ $SH-&gt;print(&quot;bar\n&quot;); ### will add &quot;bar\n&quot; to the end
+
+ ### Get the current position:
+ $pos = $SH-&gt;getpos; ### $SH-&gt;tell() also works
+
+ ### Set the current position:
+ $SH-&gt;setpos($pos); ### $SH-&gt;seek(POS,WHENCE) also works
+
+ ### Open an anonymous temporary scalar:
+ $SH = new IO::Scalar;
+ $SH-&gt;print(&quot;Hi there!&quot;);
+ print &quot;I got: &quot;, ${$SH-&gt;sref}, &quot;\n&quot;; ### 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 &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
+ print &quot;s is now... $s\n&quot;
+
+ ### Reading and writing an anonymous scalar...
+ tie *OUT, 'IO::Scalar';
+ print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
+ tied(OUT)-&gt;seek(0,0);
+ while (&lt;OUT&gt;) { print &quot;LINE: &quot;, $_ }
+</PRE></FONT>
+
+<P>Stringification now works, too!
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ my $SH = new IO::Scalar \$somestring;
+ $SH-&gt;print(&quot;Hello, &quot;);
+ $SH-&gt;print(&quot;world!&quot;);
+ print &quot;I've got: &lt;$SH&gt;\n&quot;;
+</PRE></FONT>
+
+
+<P><HR>
+<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
+
+
+<P>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-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;); # OO style
+ $SH-&gt;print(&quot;world!\n&quot;); # 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 &quot;Hel&quot;, &quot;lo, &quot;; # non-OO style
+ print OUT &quot;world!\n&quot;; # ditto
+</PRE></FONT>
+
+<P>Or this (if you have 5.004 or later):
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ my $s;
+ $SH = IO::Scalar-&gt;new_tie(\$s);
+ $SH-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;); # OO style...
+ print $SH &quot;world!\n&quot;; # ...or non-OO style!
+</PRE></FONT>
+
+<P>Causes $s to be set to:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ &quot;Hello, world!\n&quot;
+</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 &quot;private&quot; 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 &quot;\n&quot;.
+
+<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 &quot;seek to the end of the string&quot;;
+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
new file mode 100644
index 00000000..908a814b
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html
@@ -0,0 +1,338 @@
+<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-&gt;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-&gt;getline) { print &quot;Line: $_&quot; }
+ $AH-&gt;close;
+
+ # Open a handle on an array-of-scalars, and slurp in all the lines:
+ $AH = new IO::ScalarArray \@a;
+ print $AH-&gt;getlines;
+
+ # Open a handle on an array-of-scalars, and append to it:
+ $AH = new IO::ScalarArray \@a;
+ $AH-&gt;print(&quot;bar\n&quot;);
+ print &quot;some string is now: &quot;, $somestring, &quot;\n&quot;;
+
+ # Get the current position:
+ $pos = $AH-&gt;getpos; ### $AH-&gt;tell() also works
+
+ # Set the current position:
+ $AH-&gt;setpos($pos); ### $AH-&gt;seek(POS,WHENCE) also works
+
+ # Open an anonymous temporary scalar array:
+ $AH = new IO::ScalarArray;
+ $AH-&gt;print(&quot;Hi there!\nHey there!\n&quot;);
+ $AH-&gt;print(&quot;Ho there!\n&quot;);
+ print &quot;I got: &quot;, @{$AH-&gt;aref}, &quot;\n&quot;; ### 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 &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
+ print &quot;s is now... [&quot;, join('', @a), &quot;]\n&quot;;
+
+ # Reading and writing an anonymous scalar array...
+ tie *OUT, 'IO::ScalarArray';
+ print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
+ tied(OUT)-&gt;seek(0,0);
+ while (&lt;OUT&gt;) { print &quot;LINE: &quot;, $_ }
+</PRE></FONT>
+
+
+<P><HR>
+<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
+
+
+<P>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-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;);
+ $AH-&gt;print(&quot;world!\n&quot;);
+</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 &quot;Hel&quot;, &quot;lo, &quot;;
+ print OUT &quot;world!\n&quot;;
+</PRE></FONT>
+
+<P>Causes @a to be set to the following arrayt of 3 strings:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ ( &quot;Hel&quot; ,
+ &quot;lo, &quot; ,
+ &quot;world!\n&quot; )
+</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 &quot;private&quot; 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 &quot;\n&quot;.
+
+<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 &quot;seek to the end of the array&quot;
+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
new file mode 100644
index 00000000..ded5f7d2
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html
@@ -0,0 +1,208 @@
+<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 &amp; 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 &quot;this-may-prove-useful&quot; 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 &quot;real&quot; 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 '&quot;&quot;' 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 &quot;offset&quot;, 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
new file mode 100644
index 00000000..c7269929
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html
@@ -0,0 +1,169 @@
+<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-&gt;print(&quot;Hey there!&quot;);
+ ...
+ }
+
+</PRE></FONT>
+
+
+<P><HR>
+<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
+
+
+<P>Let's say you want to write some code which does I/O, but you don't
+want to force the caller to provide you with a FileHandle or IO::Handle
+object. You want them to be able to say:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ do_stuff(\*STDOUT);
+ do_stuff('STDERR');
+ do_stuff($some_FileHandle_object);
+ do_stuff($some_IO_Handle_object);
+</PRE></FONT>
+
+<P>And even:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ do_stuff($any_object_with_a_print_method);
+</PRE></FONT>
+
+<P>Sure, one way to do it is to force the caller to use tiehandle().
+But that puts the burden on them. Another way to do it is to
+use <B>IO::Wrap</B>, which provides you with the following functions:
+
+
+
+<DL>
+<P><DT><B><A NAME="item:wraphandle">wraphandle SCALAR</A></B></DT>
+<DD>
+This function will take a single argument, and &quot;wrap&quot; it based on
+what it seems to be...
+
+
+
+<UL>
+<P><LI>
+<P><B>A raw scalar filehandle name,</B> like <CODE>&quot;STDOUT&quot;</CODE> or <CODE>&quot;Class::HANDLE&quot;</CODE>.
+In this case, the filehandle name is wrapped in an IO::Wrap object,
+which is returned.
+
+<P><LI>
+<P><B>A raw filehandle glob,</B> like <CODE>\*STDOUT</CODE>.
+In this case, the filehandle glob is wrapped in an IO::Wrap object,
+which is returned.
+
+<P><LI>
+<P><B>A blessed FileHandle object.</B>
+In this case, the FileHandle is wrapped in an IO::Wrap object if and only
+if your FileHandle class does not support the <CODE>read()</CODE> method.
+
+<P><LI>
+<P><B>Any other kind of blessed object,</B> which is assumed to be already
+conformant to the IO::Handle interface.
+In this case, you just get back that object.
+
+</UL>
+
+</DL>
+
+
+<P>If you get back an IO::Wrap object, it will obey a basic subset of
+the IO:: interface. That is, the following methods (note: I said
+<I>methods</I>, not named operators) should work on the thing you get back:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ close
+ getline
+ getlines
+ print ARGS...
+ read BUFFER,NBYTES
+ seek POS,WHENCE
+ tell
+</PRE></FONT>
+
+
+<P><HR>
+<A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A>
+
+
+<P>Clearly, when wrapping a raw external filehandle (like \*STDOUT),
+I didn't want to close the file descriptor when the &quot;wrapper&quot; object is
+destroyed... since the user might not appreciate that! Hence,
+there's no DESTROY method in this class.
+
+
+<P>When wrapping a FileHandle object, however, I believe that Perl will
+invoke the FileHandle::DESTROY when the last reference goes away,
+so in that case, the filehandle is closed if the wrapped FileHandle
+really was the last reference to it.
+
+
+
+<P><HR>
+<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>
+
+
+<P>This module does not allow you to wrap filehandle names which are given
+as strings that lack the package they were opened in. That is, if a user
+opens FOO in package Foo, they must pass it to you either as <CODE>\*FOO</CODE>
+or as <CODE>&quot;Foo::FOO&quot;</CODE>. However, <CODE>&quot;STDIN&quot;</CODE> and friends will work just fine.
+
+
+
+
+<P><HR>
+<A NAME="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
new file mode 100644
index 00000000..129f47f5
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html
@@ -0,0 +1,418 @@
+<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 &quot;FooHandle-&gt;new(&amp;FOO_RDWR, 2)&quot;.
+ # We can instead say...
+
+ $FH = wraptie('FooHandle', &amp;FOO_RDWR, 2);
+
+ # Now we can use...
+ print $FH &quot;Hello, &quot;; # traditional operator syntax...
+ $FH-&gt;print(&quot;world!\n&quot;); # ...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-&gt;new_tie(&amp;FOO_RDWR, 2); # $FH is an IO::WrapTie::Master
+ print $FH &quot;Hello, &quot;; # traditional operator syntax
+ $FH-&gt;print(&quot;world!\n&quot;); # 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 &quot;split personality&quot;).
+
+</UL>
+
+
+<P>But now with IO::WrapTie, you can say:
+
+<FONT SIZE=3 FACE="courier"><PRE>
+ $WT = wraptie('FooHandle', &amp;FOO_RDWR, 2);
+ $WT-&gt;print(&quot;Hello, world\n&quot;); # OO syntax
+ print $WT &quot;Yes!\n&quot;; # Named operator syntax too!
+ $WT-&gt;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-&gt;new_tie(&amp;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 &quot;Hello, &quot;;
+ $WT-&gt;print(&quot;world!\n&quot;);
+</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 &quot;Slave&quot; object.
+ | * You would do all your i/o with $WT directly.
+ |
+ |
+ | ,---isa--&gt; IO::WrapTie::Master &gt;--isa--&gt; IO::Handle
+ V /
+ .-------------.
+ | |
+ | | * Perl i/o operators work on the tied object,
+ | &quot;Master&quot; | invoking the TIEHANDLE methods.
+ | | * Method invocations are delegated to the tied
+ | | slave.
+ `-------------'
+ |
+ tied(*$WT) | .---isa--&gt; IO::WrapTie::Slave
+ V /
+ .-------------.
+ | |
+ | &quot;Slave&quot; | * 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 &quot;slave&quot; 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 &quot;Hello, world!\n&quot;;
+</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-&gt;print(&quot;Hello, world!\n&quot;);
+</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-&gt;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-&gt;new(&amp;FOO_RDWR, 2);
+ $O-&gt;print(&quot;Hello, world\n&quot;); # OO syntax is okay, BUT....
+
+ sub nope { print $_[0] &quot;Nope!\n&quot; }
+ 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', &amp;FOO_RDWR, 2;
+ print T &quot;Hello, world\n&quot;; # Operator is okay, BUT...
+
+ tied(*T)-&gt;other_stuff; # yuck! AND...
+
+ sub nope { shift-&gt;print(&quot;Nope!\n&quot;) }
+ X nope(\*T); # ERROR!!! (method &quot;print&quot; 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-&gt;new(&amp;FOO_RDWR, 2);
+ print $IO &quot;Hello!\n&quot;;
+</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-&gt;new_tie(&amp;FOO_RDWR, 2);
+ print $IO &quot;Hello!\n&quot;;
+</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
+&quot;FooHandle&quot; 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
new file mode 100644
index 00000000..86986436
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif
Binary files differ
diff --git a/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif b/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif
new file mode 100644
index 00000000..d26510cd
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif
Binary files differ
diff --git a/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif b/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif
new file mode 100644
index 00000000..f6001a5f
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif
Binary files differ
diff --git a/cpan/dist/IO-stringy/docs/index-menu.html b/cpan/dist/IO-stringy/docs/index-menu.html
new file mode 100644
index 00000000..890a1f6a
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/index-menu.html
@@ -0,0 +1,31 @@
+<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
new file mode 100644
index 00000000..bac53b82
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/index.html
@@ -0,0 +1,13 @@
+<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
new file mode 100644
index 00000000..92466a8e
--- /dev/null
+++ b/cpan/dist/IO-stringy/docs/index.menu
@@ -0,0 +1,30 @@
+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
new file mode 100644
index 00000000..90bfce39
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/AtomicFile.pm
@@ -0,0 +1,190 @@
+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
new file mode 100644
index 00000000..4eca6d44
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/InnerFile.pm
@@ -0,0 +1,274 @@
+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
new file mode 100644
index 00000000..50b67304
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/Lines.pm
@@ -0,0 +1,148 @@
+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
new file mode 100644
index 00000000..6287b5fb
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/Scalar.pm
@@ -0,0 +1,585 @@
+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
new file mode 100644
index 00000000..7dec117b
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/ScalarArray.pm
@@ -0,0 +1,598 @@
+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
new file mode 100644
index 00000000..c7b5d369
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/Stringy.pm
@@ -0,0 +1,193 @@
+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
new file mode 100644
index 00000000..6eae65b3
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/Wrap.pm
@@ -0,0 +1,211 @@
+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
new file mode 100644
index 00000000..2535e74b
--- /dev/null
+++ b/cpan/dist/IO-stringy/lib/IO/WrapTie.pm
@@ -0,0 +1,480 @@
+# 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
new file mode 100644
index 00000000..6787a7f2
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/Common.pm
@@ -0,0 +1,255 @@
+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
new file mode 100644
index 00000000..88dbe29c
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/ExtUtils/TBone.pm
@@ -0,0 +1,534 @@
+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
new file mode 100644
index 00000000..13fc13c0
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/IO_Lines.t
@@ -0,0 +1,43 @@
+#!/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
new file mode 100644
index 00000000..ce275004
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/IO_Scalar.t
@@ -0,0 +1,51 @@
+#!/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
new file mode 100644
index 00000000..29955911
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/IO_ScalarArray.t
@@ -0,0 +1,49 @@
+#!/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
new file mode 100644
index 00000000..2817ca47
--- /dev/null
+++ b/cpan/dist/IO-stringy/t/IO_WrapTie.t
@@ -0,0 +1,66 @@
+#!/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
new file mode 100644
index 00000000..90bfce39
--- /dev/null
+++ b/cpan/lib/IO/AtomicFile.pm
@@ -0,0 +1,190 @@
+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
new file mode 100644
index 00000000..4eca6d44
--- /dev/null
+++ b/cpan/lib/IO/InnerFile.pm
@@ -0,0 +1,274 @@
+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
new file mode 100644
index 00000000..50b67304
--- /dev/null
+++ b/cpan/lib/IO/Lines.pm
@@ -0,0 +1,148 @@
+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
new file mode 100644
index 00000000..6287b5fb
--- /dev/null
+++ b/cpan/lib/IO/Scalar.pm
@@ -0,0 +1,585 @@
+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
new file mode 100644
index 00000000..7dec117b
--- /dev/null
+++ b/cpan/lib/IO/ScalarArray.pm
@@ -0,0 +1,598 @@
+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
new file mode 100644
index 00000000..c7b5d369
--- /dev/null
+++ b/cpan/lib/IO/Stringy.pm
@@ -0,0 +1,193 @@
+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
new file mode 100644
index 00000000..6eae65b3
--- /dev/null
+++ b/cpan/lib/IO/Wrap.pm
@@ -0,0 +1,211 @@
+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
new file mode 100644
index 00000000..2535e74b
--- /dev/null
+++ b/cpan/lib/IO/WrapTie.pm
@@ -0,0 +1,480 @@
+# 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
+