import IO-stringy 2.105 from CPAN

git-cpan-module:   IO-stringy
git-cpan-version:  2.105
git-cpan-authorid: ERYQ
git-cpan-file:     authors/id/E/ER/ERYQ/IO-stringy-2.105.tar.gz

Author: EryqOuithaqueue

COPYING

@@ -0,0 +1,40 @@
+The "IO-stringy" Perl5 toolkit.
+Copyright (c) 1996 by Eryq.  All rights reserved.
+Copyright (c) 1999,2001 by ZeeGee Software Inc.  All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+You should have received a copy of the Perl license along with
+Perl; see the file README in Perl distribution.
+
+You should have received a copy of the GNU General Public License
+along with Perl; see the file Copying.  If not, write to
+the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+
+You should have received a copy of the Artistic License
+along with Perl; see the file Artistic.
+
+			    NO WARRANTY
+
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS

MANIFEST

@@ -1,3 +1,4 @@
+COPYING
 MANIFEST
 Makefile.PL
 README
@@ -16,6 +17,7 @@ docs/IO/icons/zeegee.gif
 docs/index-menu.html
 docs/index.html
 docs/index.menu
+examples/IO_Scalar_synopsis
 lib/IO/AtomicFile.pm
 lib/IO/InnerFile.pm
 lib/IO/Lines.pm
@@ -30,3 +32,5 @@ t/IO_Lines.t
 t/IO_Scalar.t
 t/IO_ScalarArray.t
 t/IO_WrapTie.t
+t/simple.t
+t/two.t

Makefile.PL

@@ -14,7 +14,7 @@ WriteMakefile(
 	      VERSION_FROM => "lib/IO/Stringy.pm",
 	      DISTNAME     => "IO-stringy",
 	      'dist'       => {
-		  PREOP    => "cvu_perl_preop -m IO::Stringy -f",
+		  PREOP    => "cvu_perl_preop -m IO::Stringy -f -A",
 		  COMPRESS => 'gzip',
 		  SUFFIX   => 'gz',
 	      }

README

@@ -15,10 +15,6 @@ DESCRIPTION
     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.
 
@@ -28,10 +24,37 @@ DESCRIPTION
     and stop worrying about whether your function's caller handed you a
     string, a globref, or a FileHandle.
 
+WARNINGS
+    Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
+    support for `seek()', `tell()', and `eof()'. Attempting to use these
+    functions with an IO::Scalar, IO::ScalarArray, IO::Lines, etc. will not
+    work prior to 5.005_57. None of the relevant methods will be invoked by
+    Perl; and even worse, this kind of bug can lie dormant for a while. If
+    you turn warnings on (via `$^W' or `perl -w'), and you see something
+    like this...
+
+        seek() on unopened file
+
+    ...then you are probably trying to use one of these functions on one of
+    our IO:: classes with an old Perl. The remedy is to simply use the OO
+    version; e.g.:
+
+        $SH->seek(0,0);    ### GOOD: will work on any 5.005
+        seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
+
 INSTALLATION
+  Requirements
+
+    As of version 2.x, this toolkit requires Perl 5.005 for the IO::Handle
+    subclasses, and 5.005_57 or better is strongly recommended. See the
+    section on "WARNINGS" for details.
+
+  Directions
+
     Most of you already know the drill...
 
         perl Makefile.PL
+        make
         make test
         make install
 
@@ -54,7 +77,7 @@ INSTALLATION
     them in the next change log. I'll do it. Don't think I won't.
 
 VERSION
-    $Id: Stringy.pm,v 1.220 2001/04/04 05:37:51 eryq Exp $
+    $Id: Stringy.pm,v 2.105 2001/08/09 08:08:32 eryq Exp $
 
 TO DO
     (2000/08/02)  Finalize $/ support
@@ -63,7 +86,8 @@ TO DO
         experimental implementation done.
 
         Will the sudden sensitivity to $/ hose anyone out there? I'm
-        worried, so you have to enable it explicitly.
+        worried, so you have to enable it explicitly in 1.x. It will be on
+        by default in 2.x, though only IO::Scalar has been implemented.
 
     (2000/09/28)  Separate read/write cursors?
         Binkley sent me a very interesting variant of IO::Scalar which
@@ -74,17 +98,89 @@ TO DO
             maintain an independent read and write file position (and 
             seek(2) resets them both)? 
 
-        He also pointed out some issues with his implementation:
+        (My answer: perhaps, but stdio's fseek/ftell manpages seem to imply
+        a single file position indicator, and I'm trying to be IO::-ish.)
+        Binkley also pointed out some issues with his implementation:
 
             For example, what does eof or tell return?  The read position or 
             the write position?  (I assumed read position was more important). 
 
         Your opinions on this are most welcome. (Me, I'm just squeamish that
         this will break some code which depends on the existing behavior,
         and that attempts to maintain backwards-compatibility will slow down
-        the code. But I'll give it a shot.)
+        the code.)
+
+    (2001/08/08)  Remove IO::WrapTie from new IO:: classes
+        It's not needed. Backwards compatibility could be maintained by
+        having new_tie() be identical to new(). Heck, I'll bet that
+        IO::WrapTie should be reimplemented so the returned object is just
+        like an IO::Scalar in its use of globrefs.
 
 CHANGE LOG
+    Version 2.105   (2001/08/09)
+        Added support for various seek() whences to IO::ScalarArray.
+
+        Added support for consulting $/ in IO::Scalar and IO::ScalarArray.
+        The old `use_RS()' is not even an option. Unsupported record
+        separators will cause a croak().
+
+        Added a lot of regression tests to supoprt the above.
+
+        Better on-line docs (hyperlinks to individual functions).
+
+    Version 2.103   (2001/08/08)
+        After sober consideration I have reimplemented IO::Scalar::print()
+        so that it once again always seeks to the end of the string.
+        Benchmarks show the new implementation to be just as fast as
+        Juergen's contributed patch; until someone can convince me
+        otherwise, the current, safer implementation stays.
+
+        I thought more about giving IO::Scalar two separate handles, one for
+        reading and one for writing, as suggested by Binkley. His points
+        about what tell() and eof() return are, I think, show-stoppers for
+        this feature. Even the manpages for stdio's fseek() seem to imply a
+        *single* file position indicator, not two. So I think I will take
+        this off the TO DO list. Remedy: you can always have two handles
+        open on the same scalar, one which you only write to, and one which
+        you only read from. That should give the same effect.
+
+    Version 2.101   (2001/08/07)
+        Alpha release. This is the initial release of the "IO::Scalar and
+        friends are now subclasses of IO::Handle". I'm flinging it against
+        the wall. Please tell me if the banana sticks. When it does, the
+        banana will be called 2.2x.
+
+        First off, *many many thanks to Doug Wilson*, who has provided an
+        *invaluable* service by patching IO::Scalar and friends so that they
+        (1) inherit from IO::Handle, (2) automatically tie themselves so
+        that the `new()' objects can be used in native i/o constructs, and
+        (3) doing it so that the whole damn thing passes its regression
+        tests. As Doug knows, my globref Kung-Fu was not up to the task; he
+        graciously provided the patches. This has earned him a seat at the
+        Co-Authors table, and the right to have me address him as *sensei*.
+
+        Performance of IO::Scalar::print() has been improved by as much as
+        2x for lots of little prints, with the cost of forcing those who
+        print-then-seek-then-print to explicitly seek to end-of-string
+        before printing again. *Thanks to Juergen Zeller for this patch.*
+
+        Added the COPYING file, which had been missing from prior versions.
+        *Thanks to Albert Chin-A-Young for pointing this out.*
+
+        IO::Scalar consults $/ by default (1.x ignored it by default). Yes,
+        I still need to support IO::ScalarArray.
+
+    Version 1.221   (2001/08/07)
+        I threatened in the section on "INSTALLATION" to write an
+        unflattering haiku about anyone who whined that I gave them
+        insufficient information... but it turns out that I left out a
+        crucial direction. D'OH! *Thanks to David Beroff for the "patch" and
+        the haiku...*
+
+               Enough info there?
+                 Here's unflattering haiku:
+               Forgot the line, "make"!  ;-)
+
     Version 1.220   (2001/04/03)
         Added untested SEEK, TELL, and EOF methods to IO::Scalar and
         IO::ScalarArray to support corresponding functions for tied
@@ -189,13 +285,14 @@ AUTHOR
         Eryq ([email protected]). President, ZeeGee Software Inc
         (http://www.zeegee.com).
 
-    Unofficial Co-Authors
+    Co-Authors
         For all their bug reports and patch submissions, the following are
         officially recognized:
 
              Richard Jones
              B. K. Oxley (binkley) 
              Doru Petrescu 
+             Doug Wilson (for picking up the ball I dropped, and doing tie() right)
 
     Enjoy. Yell if it breaks.
 

README.system

@@ -5,4 +5,4 @@ DEVELOPMENT PERL:
 This is perl, version 5.005_56 built for i586-linux
 
 DEVELOPMENT DATE:
-Wed Apr  4 01:38:38 EDT 2001
+Thu Aug  9 04:09:45 EDT 2001

docs/IO/AtomicFile.pm.html

@@ -5,7 +5,8 @@
 <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>
+</A>
+<P><B>This module is <FONT COLOR="#990000">ALPHA</FONT> code, which means that public interfaces are largely untested, and may change in future releases. Use with caution! Please report any errors back to <A HREF="mailto:[email protected]">[email protected]</A> as soon as you can.</B><UL>
 <LI> <A HREF="#NAME">NAME</A>
 <LI> <A HREF="#SYNOPSIS">SYNOPSIS</A>
 <LI> <A HREF="#DESCRIPTION">DESCRIPTION</A>
@@ -29,19 +30,19 @@
     use IO::AtomicFile;
 </PRE></FONT>
 <FONT SIZE=3 FACE="courier"><PRE>
-    # Write a temp file, and have it install itself when closed:
+    ### 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;;    
 </PRE></FONT>
 <FONT SIZE=3 FACE="courier"><PRE>
-    # Write a temp file, but delete it before it gets installed:
+    ### 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; 
 </PRE></FONT>
 <FONT SIZE=3 FACE="courier"><PRE>
-    # Write a temp file, but neither install it nor delete it:
+    ### 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;   
@@ -94,11 +95,11 @@
 <A NAME="REVISION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> REVISION</H2></A>
 
 
-<P>$Revision: 1.106 $
+<P>$Revision: 2.101 $
 
 <P><HR>
 <ADDRESS><FONT SIZE=-1>
-Generated Wed Apr  4 01:38:08 2001 by cvu_pod2html
+Generated Thu Aug  9 04:09:17 2001 by cvu_pod2html
 </FONT></ADDRESS>
 </FONT></BODY>
 </HTML>

docs/IO/InnerFile.pm.html

@@ -5,11 +5,33 @@
 <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>
+</A>
+<P><B>This module is <FONT COLOR="#990000">ALPHA</FONT> code, which means that public interfaces are largely untested, and may change in future releases. Use with caution! Please report any errors back to <A HREF="mailto:[email protected]">[email protected]</A> as soon as you can.</B><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="#item:new">new FILEHANDLE, [START, [LENGTH]]</A>
+<LI> <A HREF="#item:set_length">set_length LENGTH</A>
+<LI> <A HREF="#item:get_length">get_length </A>
+<LI> <A HREF="#item:add_length">add_length NBYTES</A>
+<LI> <A HREF="#item:set_start">set_start START</A>
+<LI> <A HREF="#item:get_start">get_start </A>
+<LI> <A HREF="#item:add_start">add_start NBYTES</A>
+<LI> <A HREF="#item:binmode">binmode</A>
+<LI> <A HREF="#item:close">close</A>
+<LI> <A HREF="#item:flush">flush</A>
+<LI> <A HREF="#item:getc">getc</A>
+<LI> <A HREF="#item:getline">getline</A>
+<LI> <A HREF="#item:print">print LIST</A>
+<LI> <A HREF="#item:printf">printf LIST</A>
+<LI> <A HREF="#item:read">read BUF, NBYTES</A>
+<LI> <A HREF="#item:readline">readline</A>
+<LI> <A HREF="#item:seek">seek OFFFSET, WHENCE</A>
+<LI> <A HREF="#item:tell">tell</A>
+<LI> <A HREF="#item:write">write ARGS...</A>
+</UL>
 <LI> <A HREF="#AUTHOR">AUTHOR</A>
 </UL>
 </A>
@@ -120,7 +142,7 @@
 
 <P><HR>
 <ADDRESS><FONT SIZE=-1>
-Generated Wed Apr  4 01:38:12 2001 by cvu_pod2html
+Generated Thu Aug  9 04:09:22 2001 by cvu_pod2html
 </FONT></ADDRESS>
 </FONT></BODY>
 </HTML>

docs/IO/Lines.pm.html

@@ -5,7 +5,8 @@
 <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>
+</A>
+<P><B>This module is <FONT COLOR="#990000">ALPHA</FONT> code, which means that public interfaces are largely untested, and may change in future releases. Use with caution! Please report any errors back to <A HREF="mailto:[email protected]">[email protected]</A> as soon as you can.</B><UL>
 <LI> <A HREF="#NAME">NAME</A>
 <LI> <A HREF="#SYNOPSIS">SYNOPSIS</A>
 <LI> <A HREF="#DESCRIPTION">DESCRIPTION</A>
@@ -33,7 +34,7 @@
     use IO::Lines;
 </PRE></FONT>
 <FONT SIZE=3 FACE="courier"><PRE>
-    # See IO::ScalarArray for details 
+    ### See IO::ScalarArray for details 
 </PRE></FONT>
 
 
@@ -59,15 +60,15 @@
 newlines appropriately.
 
 
-<P>See <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A> for full usage.
+<P>See <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A> for full usage and warnings.
 
 
 
 <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.111 2001/04/04 05:37:51 eryq Exp $
+<P>$Id: Lines.pm,v 2.103 2001/08/09 08:04:44 eryq Exp $
 
 
 
@@ -96,9 +97,13 @@
 <P><I>Morris M. Siegel,</I>
 for his $/ patch and the new <CODE>getlines()</CODE>.
 
+
+<P><I>Doug Wilson,</I>
+for the IO::Handle inheritance and automatic tie-ing.
+
 <P><HR>
 <ADDRESS><FONT SIZE=-1>
-Generated Wed Apr  4 01:38:18 2001 by cvu_pod2html
+Generated Thu Aug  9 04:09:26 2001 by cvu_pod2html
 </FONT></ADDRESS>
 </FONT></BODY>
 </HTML>