diff options
| author | fukachan <fukachan> | 2001-02-27 07:24:14 +0000 |
|---|---|---|
| committer | fukachan <fukachan> | 2001-02-27 07:24:14 +0000 |
| commit | d2b53f9d7b64533b013228943f22bd132233b9a5 (patch) | |
| tree | dd7c22fbbbc3b78253874fb11da75602f386c57d | |
| parent | bd024ba03f18d40e864cfec8c6f4afa7e6e37c16 (diff) | |
| download | fml8-d2b53f9d7b64533b013228943f22bd132233b9a5.tar.gz fml8-d2b53f9d7b64533b013228943f22bd132233b9a5.tar.bz2 fml8-d2b53f9d7b64533b013228943f22bd132233b9a5.zip | |
Initial revision
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->open("bar.dat", "w"); + print $FH "Hello!\n"; + $FH->close || die "couldn't install atomic file: $!"; + + # Write a temp file, but delete it before it gets installed: + my $FH = IO::AtomicFile->open("bar.dat", "w"); + print $FH "Hello!\n"; + $FH->delete; + + # Write a temp file, but neither install it nor delete it: + my $FH = IO::AtomicFile->open("bar.dat", "w"); + print $FH "Hello!\n"; + $FH->detach; +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>This module is intended for people who need to update files +reliably in the face of unexpected program termination. + + +<P>For example, you generally don't want to be halfway in the middle of +writing <I>/etc/passwd</I> and have your program terminate! Even +the act of writing a single scalar to a filehandle is <I>not</I> atomic. + + +<P>But this module gives you true atomic updates, via rename(). +When you open a file <I>/foo/bar.dat</I> via this module, you are <I>actually</I> +opening a temporary file <I>/foo/bar.dat..TMP</I>, and writing your +output there. The act of closing this file (either explicitly +via close(), or implicitly via the destruction of the object) +will cause rename() to be called... therefore, from the point +of view of the outside world, the file's contents are updated +in a single time quantum. + + +<P>To ensure that problems do not go undetected, the "close" method +done by the destructor will raise a fatal exception if the rename() +fails. The explicit close() just returns undef. + + +<P>You can also decide at any point to trash the file you've been +building. + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + + + +<P><HR> +<A NAME="REVISION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> REVISION</H2></A> + + +<P>$Revision: 1.105 $ + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:44 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html b/cpan/dist/IO-stringy/docs/IO/InnerFile.pm.html 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->new($fh, $start, $length); + while (<$inner>) { + ... + } +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>If you have a filehandle that can seek() and tell(), then you +can open an IO::InnerFile on a range of the underlying file. + + + +<P><HR> +<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> + + + +<DL> +<P><DT><B><A NAME="item:new">new FILEHANDLE, [START, [LENGTH]]</A></B></DT> +<DD> +<I>Class method, constructor.</I> +Create a new inner-file opened on the given FILEHANDLE, +from bytes START to START+LENGTH. Both START and LENGTH +default to 0; negative values are silently coerced to zero. + + +<P>Note that FILEHANDLE must be able to seek() and tell(), in addition +to whatever other methods you may desire for reading it. + +<P><DT><B><A NAME="item:set_length">set_length LENGTH</A></B></DT> +<DD> +<P><DT><B><A NAME="item:get_length">get_length</A></B></DT> +<DD> +<P><DT><B><A NAME="item:add_length">add_length NBYTES</A></B></DT> +<DD> +<I>Instance methods.</I> +Get/set the virtual length of the inner file. + +<P><DT><B><A NAME="item:set_start">set_start START</A></B></DT> +<DD> +<P><DT><B><A NAME="item:get_start">get_start</A></B></DT> +<DD> +<P><DT><B><A NAME="item:add_start">add_start NBYTES</A></B></DT> +<DD> +<I>Instance methods.</I> +Get/set the virtual start position of the inner file. + +<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> +<DD> +<P><DT><B><A NAME="item:close">close</A></B></DT> +<DD> +<P><DT><B><A NAME="item:flush">flush</A></B></DT> +<DD> +<P><DT><B><A NAME="item:getc">getc</A></B></DT> +<DD> +<P><DT><B><A NAME="item:getline">getline</A></B></DT> +<DD> +<P><DT><B><A NAME="item:print">print LIST</A></B></DT> +<DD> +<P><DT><B><A NAME="item:printf">printf LIST</A></B></DT> +<DD> +<P><DT><B><A NAME="item:read">read BUF, NBYTES</A></B></DT> +<DD> +<P><DT><B><A NAME="item:readline">readline</A></B></DT> +<DD> +<P><DT><B><A NAME="item:seek">seek OFFFSET, WHENCE</A></B></DT> +<DD> +<P><DT><B><A NAME="item:tell">tell</A></B></DT> +<DD> +<P><DT><B><A NAME="item:write">write ARGS...</A></B></DT> +<DD> +<I>Instance methods.</I> +Standard filehandle methods. + +</DL> + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + +<P>Original version by Doru Petrescu (pdoru@kappa.ro). + + +<P>Documentation and current maintenance by Eryq (eryq@zeegee.com). + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:46 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Lines.pm.html b/cpan/dist/IO-stringy/docs/IO/Lines.pm.html 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>"\n"</CODE>, with the possible exception of the +final element. This makes <CODE>getline()</CODE> <I>much</I> more efficient; +if you plan to do line-oriented reading/printing, you want this class. + + +<P>The <CODE>print()</CODE> method will enforce this rule, so you can print +arbitrary data to the line-array: it will break the data at +newlines appropriately. + + +<P>See <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A> for full usage. + + + +<P><HR> +<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> + + +<P>$Id: Lines.pm,v 1.110 2000/08/16 04:59:02 eryq Exp $ + + + +<P><HR> +<A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A> + + + +<P><HR> +<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + + + +<P><HR> +<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> + + +<P>Thanks to the following individuals for their invaluable contributions +(if I've forgotten or misspelled your name, please email me!): + + +<P><I>Morris M. Siegel,</I> +for his $/ patch and the new <CODE>getlines()</CODE>. + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:48 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html b/cpan/dist/IO-stringy/docs/IO/Scalar.pm.html 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->open(\$somestring); + + ### Open a handle on a string, read it line-by-line, then close it: + $SH = new IO::Scalar \$somestring; + while ($_ = $SH->getline) { print "Line: $_" } + $SH->close; + + ### Open a handle on a string, and slurp in all the lines: + $SH = new IO::Scalar \$somestring; + print $SH->getlines; + + ### Open a handle on a string, and append to it: + $SH = new IO::Scalar \$somestring + $SH->print("bar\n"); ### will add "bar\n" to the end + + ### Get the current position: + $pos = $SH->getpos; ### $SH->tell() also works + + ### Set the current position: + $SH->setpos($pos); ### $SH->seek(POS,WHENCE) also works + + ### Open an anonymous temporary scalar: + $SH = new IO::Scalar; + $SH->print("Hi there!"); + print "I got: ", ${$SH->sref}, "\n"; ### get at value +</PRE></FONT> + +<P>If your Perl is 5.004 or later, you can use the TIEHANDLE +interface, and read/write scalars just like files: + +<FONT SIZE=3 FACE="courier"><PRE> + use IO::Scalar; +</PRE></FONT> +<FONT SIZE=3 FACE="courier"><PRE> + ### Writing to a scalar... + my $s; + tie *OUT, 'IO::Scalar', \$s; + print OUT "line 1\nline 2\n", "line 3\n"; + print "s is now... $s\n" + + ### Reading and writing an anonymous scalar... + tie *OUT, 'IO::Scalar'; + print OUT "line 1\nline 2\n", "line 3\n"; + tied(OUT)->seek(0,0); + while (<OUT>) { print "LINE: ", $_ } +</PRE></FONT> + +<P>Stringification now works, too! + +<FONT SIZE=3 FACE="courier"><PRE> + my $SH = new IO::Scalar \$somestring; + $SH->print("Hello, "); + $SH->print("world!"); + print "I've got: <$SH>\n"; +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>This class implements objects which behave just like FileHandle +(or IO::Handle) objects, except that you may use them to write to +(or read from) scalars. They can be tiehandle'd as well. + + +<P>Basically, this: + +<FONT SIZE=3 FACE="courier"><PRE> + my $s; + $SH = new IO::Scalar \$s; + $SH->print("Hel", "lo, "); # OO style + $SH->print("world!\n"); # ditto +</PRE></FONT> + +<P>Or this (if you have 5.004 or later): + +<FONT SIZE=3 FACE="courier"><PRE> + my $s; + $SH = tie *OUT, 'IO::Scalar', \$s; + print OUT "Hel", "lo, "; # non-OO style + print OUT "world!\n"; # ditto +</PRE></FONT> + +<P>Or this (if you have 5.004 or later): + +<FONT SIZE=3 FACE="courier"><PRE> + my $s; + $SH = IO::Scalar->new_tie(\$s); + $SH->print("Hel", "lo, "); # OO style... + print $SH "world!\n"; # ...or non-OO style! +</PRE></FONT> + +<P>Causes $s to be set to: + +<FONT SIZE=3 FACE="courier"><PRE> + "Hello, world!\n" +</PRE></FONT> + + +<P><HR> +<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> + + + +<P><HR> +<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:new">new [ARGS...]</A></B></DT> +<DD> +<I>Class method.</I> +Return a new, unattached scalar handle. +If any arguments are given, they're sent to open(). + +<P><DT><B><A NAME="item:open">open [SCALARREF]</A></B></DT> +<DD> +<I>Instance method.</I> +Open the scalar handle on a new scalar, pointed to by SCALARREF. +If no SCALARREF is given, a "private" scalar is created to hold +the file data. + + +<P>Returns the self object on success, undefined on error. + +<P><DT><B><A NAME="item:opened">opened</A></B></DT> +<DD> +<I>Instance method.</I> +Is the scalar handle opened on something? + +<P><DT><B><A NAME="item:close">close</A></B></DT> +<DD> +<I>Instance method.</I> +Disassociate the scalar handle from its underlying scalar. +Done automatically on destroy. + +</DL> + + + +<P><HR> +<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:flush">flush</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:getc">getc</A></B></DT> +<DD> +<I>Instance method.</I> +Return the next character, or undef if none remain. + +<P><DT><B><A NAME="item:getline">getline</A></B></DT> +<DD> +<I>Instance method.</I> +Return the next line, or undef on end of string. +Can safely be called in an array context. +Currently, lines are delimited by "\n". + +<P><DT><B><A NAME="item:getlines">getlines</A></B></DT> +<DD> +<I>Instance method.</I> +Get all remaining lines. +It will croak() if accidentally called in a scalar context. + +<P><DT><B><A NAME="item:print">print ARGS...</A></B></DT> +<DD> +<I>Instance method.</I> +Print ARGS to the underlying scalar. + + +<P><B>Warning:</B> Currently, this always causes a "seek to the end of the string"; +this may change in the future. + +<P><DT><B><A NAME="item:read">read BUF, NBYTES, [OFFSET]</A></B></DT> +<DD> +<I>Instance method.</I> +Read some bytes from the scalar. +Returns the number of bytes actually read, 0 on end-of-file, undef on error. + +<P><DT><B><A NAME="item:write">write BUF, NBYTES, [OFFSET]</A></B></DT> +<DD> +<I>Instance method.</I> +Write some bytes to the scalar. + +<P><DT><B><A NAME="item:sysread">sysread BUF, LEN, [OFFSET]</A></B></DT> +<DD> +<I>Instance method.</I> +Read some bytes from the scalar. +Returns the number of bytes actually read, 0 on end-of-file, undef on error. + +<P><DT><B><A NAME="item:syswrite">syswrite BUF, NBYTES, [OFFSET]</A></B></DT> +<DD> +<I>Instance method.</I> +Write some bytes to the scalar. + +</DL> + + + +<P><HR> +<A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:autoflush">autoflush</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:clearerr">clearerr</A></B></DT> +<DD> +<I>Instance method.</I> Clear the error and EOF flags. A no-op. + +<P><DT><B><A NAME="item:eof">eof</A></B></DT> +<DD> +<I>Instance method.</I> Are we at end of file? + +<P><DT><B><A NAME="item:seek">seek OFFSET, WHENCE</A></B></DT> +<DD> +<I>Instance method.</I> Seek to a given position in the stream. + +<P><DT><B><A NAME="item:tell">tell</A></B></DT> +<DD> +<I>Instance method.</I> +Return the current position in the stream, as a numeric offset. + +<P><DT><B><A NAME="item:setpos">setpos POS</A></B></DT> +<DD> +<I>Instance method.</I> +Set the current position, using the opaque value returned by <CODE>getpos()</CODE>. + +<P><DT><B><A NAME="item:getpos">getpos</A></B></DT> +<DD> +<I>Instance method.</I> +Return the current position in the string, as an opaque object. + +<P><DT><B><A NAME="item:sref">sref</A></B></DT> +<DD> +<I>Instance method.</I> +Return a reference to the underlying scalar. + +</DL> + + + +<P><HR> +<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> + + +<P>$Id: Scalar.pm,v 1.122 2000/09/28 06:32:28 eryq Exp $ + + + +<P><HR> +<A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A> + + + +<P><HR> +<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + + + +<P><HR> +<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> + + +<P>The full set of contributors always includes the folks mentioned +in <A HREF="../IO/Stringy.pm.html#CHANGE_LOG">CHANGE LOG</A>. But just the same, special +thanks to the following individuals for their invaluable contributions +(if I've forgotten or misspelled your name, please email me!): + + +<P><I>Andy Glew,</I> +for contributing <CODE>getc()</CODE>. + + +<P><I>Brandon Browning,</I> +for suggesting <CODE>opened()</CODE>. + + +<P><I>David Richter,</I> +for finding and fixing the bug in <CODE>PRINTF()</CODE>. + + +<P><I>Eric L. Brine,</I> +for his offset-using read() and write() implementations. + + +<P><I>Richard Jones</I> (<I><FILE><A HREF="mailto:rich@annexia.org">rich@annexia.org</A></FILE></I>), +for his patches to massively improve the performance of <CODE>getline()</CODE> +and add <CODE>sysread</CODE> and <CODE>syswrite</CODE>. + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:51 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html b/cpan/dist/IO-stringy/docs/IO/ScalarArray.pm.html 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->open(\@a); + + # Open a handle on an array-of-scalars, read it line-by-line, + # then close it: + $AH = new IO::ScalarArray \@a; + while ($_ = $AH->getline) { print "Line: $_" } + $AH->close; + + # Open a handle on an array-of-scalars, and slurp in all the lines: + $AH = new IO::ScalarArray \@a; + print $AH->getlines; + + # Open a handle on an array-of-scalars, and append to it: + $AH = new IO::ScalarArray \@a; + $AH->print("bar\n"); + print "some string is now: ", $somestring, "\n"; + + # Get the current position: + $pos = $AH->getpos; ### $AH->tell() also works + + # Set the current position: + $AH->setpos($pos); ### $AH->seek(POS,WHENCE) also works + + # Open an anonymous temporary scalar array: + $AH = new IO::ScalarArray; + $AH->print("Hi there!\nHey there!\n"); + $AH->print("Ho there!\n"); + print "I got: ", @{$AH->aref}, "\n"; ### get at value +</PRE></FONT> + +<P>If your Perl is 5.004 or later, you can use the TIEHANDLE +interface, and read/write as array-of-scalars just like files: + +<FONT SIZE=3 FACE="courier"><PRE> + use IO::ScalarArray; +</PRE></FONT> +<FONT SIZE=3 FACE="courier"><PRE> + # Writing to a scalar array... + my @a; + tie *OUT, 'IO::ScalarArray', \@a; + print OUT "line 1\nline 2\n", "line 3\n"; + print "s is now... [", join('', @a), "]\n"; + + # Reading and writing an anonymous scalar array... + tie *OUT, 'IO::ScalarArray'; + print OUT "line 1\nline 2\n", "line 3\n"; + tied(OUT)->seek(0,0); + while (<OUT>) { print "LINE: ", $_ } +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>This class implements objects which behave just like FileHandle +(or IO::Handle) objects, except that you may use them to write to +(or read from) scalars. They can be tiehandle'd as well. + + +<P>For writing large amounts of data with individual print() statements, +this is likely to be more efficient than IO::Scalar. + + +<P>Basically, this: + +<FONT SIZE=3 FACE="courier"><PRE> + my @a; + $AH = new IO::ScalarArray \@a; + $AH->print("Hel", "lo, "); + $AH->print("world!\n"); +</PRE></FONT> + +<P>Or this (if you have 5.004 or later): + +<FONT SIZE=3 FACE="courier"><PRE> + my @a; + $AH = tie *OUT, 'IO::ScalarArray', \@a; + print OUT "Hel", "lo, "; + print OUT "world!\n"; +</PRE></FONT> + +<P>Causes @a to be set to the following arrayt of 3 strings: + +<FONT SIZE=3 FACE="courier"><PRE> + ( "Hel" , + "lo, " , + "world!\n" ) +</PRE></FONT> + +<P>Compare this with IO::Scalar. + + + +<P><HR> +<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> + + + +<P><HR> +<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:new">new [ARGS...]</A></B></DT> +<DD> +<I>Class method.</I> +Return a new, unattached array handle. +If any arguments are given, they're sent to open(). + +<P><DT><B><A NAME="item:open">open [ARRAYREF]</A></B></DT> +<DD> +<I>Instance method.</I> +Open the array handle on a new array, pointed to by ARRAYREF. +If no ARRAYREF is given, a "private" array is created to hold +the file data. + + +<P>Returns the self object on success, undefined on error. + +<P><DT><B><A NAME="item:opened">opened</A></B></DT> +<DD> +<I>Instance method.</I> +Is the array handle opened on something? + +<P><DT><B><A NAME="item:close">close</A></B></DT> +<DD> +<I>Instance method.</I> +Disassociate the array handle from its underlying array. +Done automatically on destroy. + +</DL> + + + +<P><HR> +<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:flush">flush</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:getc">getc</A></B></DT> +<DD> +<I>Instance method.</I> +Return the next character, or undef if none remain. +This does a read(1), which is somewhat costly. + +<P><DT><B><A NAME="item:getline">getline</A></B></DT> +<DD> +<I>Instance method.</I> +Return the next line, or undef on end of data. +Can safely be called in an array context. +Currently, lines are delimited by "\n". + +<P><DT><B><A NAME="item:getlines">getlines</A></B></DT> +<DD> +<I>Instance method.</I> +Get all remaining lines. +It will croak() if accidentally called in a scalar context. + +<P><DT><B><A NAME="item:print">print ARGS...</A></B></DT> +<DD> +<I>Instance method.</I> +Print ARGS to the underlying array. + + +<P>Currently, this always causes a "seek to the end of the array" +and generates a new array entry. This may change in the future. + +<P><DT><B><A NAME="item:read">read BUF, NBYTES, [OFFSET];</A></B></DT> +<DD> +<I>Instance method.</I> +Read some bytes from the array. +Returns the number of bytes actually read, 0 on end-of-file, undef on error. + +<P><DT><B><A NAME="item:write">write BUF, NBYTES, [OFFSET];</A></B></DT> +<DD> +<I>Instance method.</I> +Write some bytes into the array. + +</DL> + + + +<P><HR> +<A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A> + + + +<DL> +<P><DT><B><A NAME="item:autoflush">autoflush</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:binmode">binmode</A></B></DT> +<DD> +<I>Instance method.</I> +No-op, provided for OO compatibility. + +<P><DT><B><A NAME="item:clearerr">clearerr</A></B></DT> +<DD> +<I>Instance method.</I> Clear the error and EOF flags. A no-op. + +<P><DT><B><A NAME="item:eof">eof</A></B></DT> +<DD> +<I>Instance method.</I> Are we at end of file? + +<P><DT><B><A NAME="item:seek">seek POS,WHENCE</A></B></DT> +<DD> +<I>Instance method.</I> +Seek to a given position in the stream. +Only a WHENCE of 0 (SEEK_SET) is supported. + +<P><DT><B><A NAME="item:tell">tell</A></B></DT> +<DD> +<I>Instance method.</I> +Return the current position in the stream, as a numeric offset. + +<P><DT><B><A NAME="item:setpos">setpos POS</A></B></DT> +<DD> +<I>Instance method.</I> +Seek to a given position in the array, using the opaque getpos() value. +Don't expect this to be a number. + +<P><DT><B><A NAME="item:getpos">getpos</A></B></DT> +<DD> +<I>Instance method.</I> +Return the current position in the array, as an opaque value. +Don't expect this to be a number. + +<P><DT><B><A NAME="item:aref">aref</A></B></DT> +<DD> +<I>Instance method.</I> +Return a reference to the underlying array. + +</DL> + + + +<P><HR> +<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> + + +<P>$Id: ScalarArray.pm,v 1.117 2000/09/28 06:32:28 eryq Exp $ + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + + +<P><HR> +<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + + + +<P><HR> +<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> + + +<P>Thanks to the following individuals for their invaluable contributions +(if I've forgotten or misspelled your name, please email me!): + + +<P><I>Andy Glew,</I> +for suggesting <CODE>getc()</CODE>. + + +<P><I>Brandon Browning,</I> +for suggesting <CODE>opened()</CODE>. + + +<P><I>Eric L. Brine,</I> +for his offset-using read() and write() implementations. + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:53 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html b/cpan/dist/IO-stringy/docs/IO/Stringy.pm.html 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 & retain full OO interface ERYQ +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>This toolkit primarily provides modules for performing both traditional +and object-oriented i/o) on things <I>other</I> than normal filehandles; +in particular, <A HREF="../IO/Scalar.pm.html">IO::Scalar</A>, <A HREF="../IO/ScalarArray.pm.html">IO::ScalarArray</A>, +and <A HREF="../IO/Lines.pm.html">IO::Lines</A>. + + +<P>If you have access to tie(), these classes will make use of the +<A HREF="../IO/WrapTie.pm.html">IO::WrapTie</A> module to inherit a convenient new_tie() +constructor. It also exports a nice wraptie() function. + + +<P>In the more-traditional IO::Handle front, we +have <A HREF="../IO/AtomicFile.pm.html">IO::AtomicFile</A> +which may be used to painlessly create files which are updated +atomically. + + +<P>And in the "this-may-prove-useful" corner, we have <A HREF="../IO/Wrap.pm.html">IO::Wrap</A>, +whose exported wraphandle() function will clothe anything that's not +a blessed object in an IO::Handle-like wrapper... so you can just +use OO syntax and stop worrying about whether your function's caller +handed you a string, a globref, or a FileHandle. + + + +<P><HR> +<A NAME="INSTALLATION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> INSTALLATION</H2></A> + + +<P>You know the drill... + +<FONT SIZE=3 FACE="courier"><PRE> + perl Makefile.PL + make test + make install +</PRE></FONT> + + +<P><HR> +<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> + + +<P>$Id: Stringy.pm,v 1.216 2000/09/28 06:32:28 eryq Exp $ + + + +<P><HR> +<A NAME="CHANGE_LOG"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> CHANGE LOG</H2></A> + + + +<DL> +<P><DT><B><A NAME="item:Version">Version 1.216 (2000/09/28)</A></B></DT> +<DD> +<B>IO::Scalar and IO::ScalarArray now inherit from IO::Handle.</B> +I thought I'd remembered a problem with this ages ago, related to +the fact that these IO:: modules don't have "real" filehandles, +but the problem apparently isn't surfacing now. +If you suddenly encounter Perl warnings during global destruction +(especially if you're using tied filehandles), then please let me know! +<I>Thanks to B. K. Oxley (binkley) for this.</I> + + +<P><B>Nasty bug fixed in IO::Scalar::write().</B> +Apparently, the offset and the number-of-bytes arguments were, +for all practical purposes, <I>reversed.</I> You were okay if +you did all your writing with print(), but boy was <I>this</I> a stupid bug! +<I>Thanks to Richard Jones for finding this one. +For you, Rich, a double-length haiku:</I> + +<FONT SIZE=3 FACE="courier"><PRE> + Newspaper headline + typeset by dyslexic man + loses urgency + + BABY EATS FISH is + simply not equivalent + to FISH EATS BABY +</PRE></FONT> + +<P><B>New sysread and syswrite methods for IO::Scalar.</B> +<I>Thanks again to Richard Jones for this.</I> + +<P><DT><B><A NAME="item:Version">Version 1.215 (2000/09/05)</A></B></DT> +<DD> +Added 'bool' overload to '""' overload, so object always evaluates +to true. (Whew. Glad I caught this before it went to CPAN.) + +<P><DT><B><A NAME="item:Version">Version 1.214 (2000/09/03)</A></B></DT> +<DD> +Evaluating an IO::Scalar in a string context now yields +the underlying string. +<I>Thanks to B. K. Oxley (binkley) for this.</I> + +<P><DT><B><A NAME="item:Version">Version 1.213 (2000/08/16)</A></B></DT> +<DD> +Minor documentation fixes. + +<P><DT><B><A NAME="item:Version">Version 1.212 (2000/06/02)</A></B></DT> +<DD> +Fixed IO::InnerFile incompatibility with Perl5.004. +<I>Thanks to many folks for reporting this.</I> + +<P><DT><B><A NAME="item:Version">Version 1.210 (2000/04/17)</A></B></DT> +<DD> +Added flush() and other no-op methods. +<I>Thanks to Doru Petrescu for suggesting this.</I> + +<P><DT><B><A NAME="item:Version">Version 1.209 (2000/03/17)</A></B></DT> +<DD> +Small bug fixes. + +<P><DT><B><A NAME="item:Version">Version 1.208 (2000/03/14)</A></B></DT> +<DD> +Incorporated a number of contributed patches and extensions, +mostly related to speed hacks, support for "offset", and +WRITE/CLOSE methods. +<I>Thanks to Richard Jones, Doru Petrescu, and many others.</I> + +<P><DT><B><A NAME="item:Version">Version 1.206 (1999/04/18)</A></B></DT> +<DD> +Added creation of ./testout when Makefile.PL is run. + +<P><DT><B><A NAME="item:Version">Version 1.205 (1999/01/15)</A></B></DT> +<DD> +Verified for Perl5.005. + +<P><DT><B><A NAME="item:Version">Version 1.202 (1998/04/18)</A></B></DT> +<DD> +New IO::WrapTie and IO::AtomicFile added. + +<P><DT><B><A NAME="item:Version">Version 1.110</A></B></DT> +<DD> +Added IO::WrapTie. + +<P><DT><B><A NAME="item:Version">Version 1.107</A></B></DT> +<DD> +Added IO::Lines, and made some bug fixes to IO::ScalarArray. +Also, added getc(). + +<P><DT><B><A NAME="item:Version">Version 1.105</A></B></DT> +<DD> +No real changes; just upgraded IO::Wrap to have a $VERSION string. + +</DL> + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + + +<P>Enjoy. Yell if it breaks. + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:35:55 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html b/cpan/dist/IO-stringy/docs/IO/Wrap.pm.html 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->print("Hey there!"); + ... + } + +</PRE></FONT> + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>Let's say you want to write some code which does I/O, but you don't +want to force the caller to provide you with a FileHandle or IO::Handle +object. You want them to be able to say: + +<FONT SIZE=3 FACE="courier"><PRE> + do_stuff(\*STDOUT); + do_stuff('STDERR'); + do_stuff($some_FileHandle_object); + do_stuff($some_IO_Handle_object); +</PRE></FONT> + +<P>And even: + +<FONT SIZE=3 FACE="courier"><PRE> + do_stuff($any_object_with_a_print_method); +</PRE></FONT> + +<P>Sure, one way to do it is to force the caller to use tiehandle(). +But that puts the burden on them. Another way to do it is to +use <B>IO::Wrap</B>, which provides you with the following functions: + + + +<DL> +<P><DT><B><A NAME="item:wraphandle">wraphandle SCALAR</A></B></DT> +<DD> +This function will take a single argument, and "wrap" it based on +what it seems to be... + + + +<UL> +<P><LI> +<P><B>A raw scalar filehandle name,</B> like <CODE>"STDOUT"</CODE> or <CODE>"Class::HANDLE"</CODE>. +In this case, the filehandle name is wrapped in an IO::Wrap object, +which is returned. + +<P><LI> +<P><B>A raw filehandle glob,</B> like <CODE>\*STDOUT</CODE>. +In this case, the filehandle glob is wrapped in an IO::Wrap object, +which is returned. + +<P><LI> +<P><B>A blessed FileHandle object.</B> +In this case, the FileHandle is wrapped in an IO::Wrap object if and only +if your FileHandle class does not support the <CODE>read()</CODE> method. + +<P><LI> +<P><B>Any other kind of blessed object,</B> which is assumed to be already +conformant to the IO::Handle interface. +In this case, you just get back that object. + +</UL> + +</DL> + + +<P>If you get back an IO::Wrap object, it will obey a basic subset of +the IO:: interface. That is, the following methods (note: I said +<I>methods</I>, not named operators) should work on the thing you get back: + +<FONT SIZE=3 FACE="courier"><PRE> + close + getline + getlines + print ARGS... + read BUFFER,NBYTES + seek POS,WHENCE + tell +</PRE></FONT> + + +<P><HR> +<A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A> + + +<P>Clearly, when wrapping a raw external filehandle (like \*STDOUT), +I didn't want to close the file descriptor when the "wrapper" object is +destroyed... since the user might not appreciate that! Hence, +there's no DESTROY method in this class. + + +<P>When wrapping a FileHandle object, however, I believe that Perl will +invoke the FileHandle::DESTROY when the last reference goes away, +so in that case, the filehandle is closed if the wrapped FileHandle +really was the last reference to it. + + + +<P><HR> +<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A> + + +<P>This module does not allow you to wrap filehandle names which are given +as strings that lack the package they were opened in. That is, if a user +opens FOO in package Foo, they must pass it to you either as <CODE>\*FOO</CODE> +or as <CODE>"Foo::FOO"</CODE>. However, <CODE>"STDIN"</CODE> and friends will work just fine. + + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:36:00 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html b/cpan/dist/IO-stringy/docs/IO/WrapTie.pm.html 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 "FooHandle->new(&FOO_RDWR, 2)". + # We can instead say... + + $FH = wraptie('FooHandle', &FOO_RDWR, 2); + + # Now we can use... + print $FH "Hello, "; # traditional operator syntax... + $FH->print("world!\n"); # ...and OO syntax as well! +</PRE></FONT> + +<P><I>OO interface (preferred).</I> +You can inherit from the IO::WrapTie::Slave mixin to get a +nifty <CODE>new_tie()</CODE> constructor... + +<FONT SIZE=3 FACE="courier"><PRE> + #------------------------------ + package FooHandle; # a class which can TIEHANDLE + + use IO::WrapTie; + @ISA = qw(IO::WrapTie::Slave); # inherit new_tie() + ... + + + #------------------------------ + package main; + + $FH = FooHandle->new_tie(&FOO_RDWR, 2); # $FH is an IO::WrapTie::Master + print $FH "Hello, "; # traditional operator syntax + $FH->print("world!\n"); # OO syntax +</PRE></FONT> + +<P>See IO::Scalar as an example. It also shows you how to create classes +which work both with and without 5.004. + + + +<P><HR> +<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> + + +<P>Suppose you have a class <CODE>FooHandle</CODE>, where... + + + +<UL> +<P><LI> +<P><B>FooHandle does not inherit from IO::Handle;</B> that is, it performs +filehandle-like I/O, but to something other than an underlying +file descriptor. Good examples are IO::Scalar (for printing to a +string) and IO::Lines (for printing to an array of lines). + +<P><LI> +<P><B>FooHandle implements the TIEHANDLE interface</B> (see <A HREF="perltie.pm.html">perltie</A>); +that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, +READ, and READLINE. + +<P><LI> +<P><B>FooHandle implements the traditional OO interface</B> of +FileHandle and IO::Handle; i.e., it contains methods like getline(), +read(), print(), seek(), tell(), eof(), etc. + +</UL> + + +<P>Normally, users of your class would have two options: + + + +<UL> +<P><LI> +<P><B>Use only OO syntax,</B> and forsake named I/O operators like 'print'. + +<P><LI> +<P><B>Use with tie,</B> and forsake treating it as a first-class object +(i.e., class-specific methods can only be invoked through the underlying +object via tied()... giving the object a "split personality"). + +</UL> + + +<P>But now with IO::WrapTie, you can say: + +<FONT SIZE=3 FACE="courier"><PRE> + $WT = wraptie('FooHandle', &FOO_RDWR, 2); + $WT->print("Hello, world\n"); # OO syntax + print $WT "Yes!\n"; # Named operator syntax too! + $WT->weird_stuff; # Other methods! +</PRE></FONT> + +<P>And if you're authoring a class like FooHandle, just have it inherit +from <CODE>IO::WrapTie::Slave</CODE> and that first line becomes even prettier: + +<FONT SIZE=3 FACE="courier"><PRE> + $WT = FooHandle->new_tie(&FOO_RDWR, 2); +</PRE></FONT> + +<P><B>The bottom line:</B> now, almost any class can look and work exactly like +an IO::Handle... and be used both with OO and non-OO filehandle syntax. + + + +<P><HR> +<A NAME="HOW_IT_ALL_WORKS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> HOW IT ALL WORKS</H2></A> + + + +<P><HR> +<A NAME="The_data_structures"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> The data structures</H3></A> + + +<P>Consider this example code, using classes in this distribution: + +<FONT SIZE=3 FACE="courier"><PRE> + use IO::Scalar; + use IO::WrapTie; + + $WT = wraptie('IO::Scalar',\$s); + print $WT "Hello, "; + $WT->print("world!\n"); +</PRE></FONT> + +<P>In it, the wraptie() function creates a data structure as follows: + +<FONT SIZE=3 FACE="courier"><PRE> + * $WT is a blessed reference to a tied filehandle + $WT glob; that glob is tied to the "Slave" object. + | * You would do all your i/o with $WT directly. + | + | + | ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle + V / + .-------------. + | | + | | * Perl i/o operators work on the tied object, + | "Master" | invoking the TIEHANDLE methods. + | | * Method invocations are delegated to the tied + | | slave. + `-------------' + | + tied(*$WT) | .---isa--> IO::WrapTie::Slave + V / + .-------------. + | | + | "Slave" | * Instance of FileHandle-like class which doesn't + | | actually use file descriptors, like IO::Scalar. + | IO::Scalar | * The slave can be any kind of object. + | | * Must implement the TIEHANDLE interface. + `-------------' +</PRE></FONT> + +<P><I>NOTE:</I> just as an IO::Handle is really just a blessed reference to a +<I>traditional</I> filehandle glob... so also, an IO::WrapTie::Master +is really just a blessed reference to a filehandle +glob <I>which has been tied to some "slave" class.</I> + + + +<P><HR> +<A NAME="How_wraptie_works"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How wraptie() works</H3></A> + + + +<OL> +<P><LI> +<P>The call to function <CODE>wraptie(SLAVECLASS, TIEARGS...)</CODE> is +passed onto <CODE>IO::WrapTie::Master::new()</CODE>. +Note that class IO::WrapTie::Master is a subclass of IO::Handle. + +<P><LI> +<P>The <CODE>IO::WrapTie::Master::new</CODE> method creates a new IO::Handle object, +reblessed into class IO::WrapTie::Master. This object is the <I>master</I>, +which will be returned from the constructor. At the same time... + +<P><LI> +<P>The <CODE>new</CODE> method also creates the <I>slave</I>: this is an instance +of SLAVECLASS which is created by tying the master's IO::Handle +to SLAVECLASS via <CODE>tie(HANDLE, SLAVECLASS, TIEARGS...)</CODE>. +This call to <CODE>tie()</CODE> creates the slave in the following manner: + +<P><LI> +<P>Class SLAVECLASS is sent the message <CODE>TIEHANDLE(TIEARGS...)</CODE>; it +will usually delegate this to <CODE>SLAVECLASS::new(TIEARGS...)</CODE>, resulting +in a new instance of SLAVECLASS being created and returned. + +<P><LI> +<P>Once both master and slave have been created, the master is returned +to the caller. + +</OL> + + + +<P><HR> +<A NAME="How_I_O_operators_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How I/O operators work (on the master)</H3></A> + + +<P>Consider using an i/o operator on the master: + +<FONT SIZE=3 FACE="courier"><PRE> + print $WT "Hello, world!\n"; +</PRE></FONT> + +<P>Since the master ($WT) is really a [blessed] reference to a glob, +the normal Perl i/o operators like <CODE>print</CODE> may be used on it. +They will just operate on the symbol part of the glob. + + +<P>Since the glob is tied to the slave, the slave's PRINT method +(part of the TIEHANDLE interface) will be automatically invoked. + + +<P>If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be +invoked, and that method happens to delegate to the <CODE>print()</CODE> method +of the same class. So the <I>real</I> work is ultimately done by +IO::Scalar::print(). + + + +<P><HR> +<A NAME="How_methods_work_on_the_master"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> How methods work (on the master)</H3></A> + + +<P>Consider using a method on the master: + +<FONT SIZE=3 FACE="courier"><PRE> + $WT->print("Hello, world!\n"); +</PRE></FONT> + +<P>Since the master ($WT) is blessed into the class IO::WrapTie::Master, +Perl first attempts to find a <CODE>print()</CODE> method there. Failing that, +Perl next attempts to find a <CODE>print()</CODE> method in the superclass, +IO::Handle. It just so happens that there <I>is</I> such a method; +that method merely invokes the <CODE>print</CODE> i/o operator on the self object... +and for that, see above! + + +<P>But let's suppose we're dealing with a method which <I>isn't</I> part +of IO::Handle... for example: + +<FONT SIZE=3 FACE="courier"><PRE> + my $sref = $WT->sref; +</PRE></FONT> + +<P>In this case, the intuitive behavior is to have the master delegate the +method invocation to the slave (now do you see where the designations +come from?). This is indeed what happens: IO::WrapTie::Master contains +an AUTOLOAD method which performs the delegation. + + +<P>So: when <CODE>sref()</CODE> can't be found in IO::Handle, the AUTOLOAD method +of IO::WrapTie::Master is invoked, and the standard behavior of +delegating the method to the underlying slave (here, an IO::Scalar) +is done. + + +<P>Sometimes, to get this to work properly, you may need to create +a subclass of IO::WrapTie::Master which is an effective master for +<I>your</I> class, and do the delegation there. + + + +<P><HR> +<A NAME="NOTES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NOTES</H2></A> + + +<P><B>Why not simply use the object's OO interface?</B> + Because that means forsaking the use of named operators +like print(), and you may need to pass the object to a subroutine +which will attempt to use those operators: + +<FONT SIZE=3 FACE="courier"><PRE> + $O = FooHandle->new(&FOO_RDWR, 2); + $O->print("Hello, world\n"); # OO syntax is okay, BUT.... + + sub nope { print $_[0] "Nope!\n" } + X nope($O); # ERROR!!! (not a glob ref) + +</PRE></FONT> + +<P><B>Why not simply use tie()?</B> + Because (1) you have to use tied() to invoke methods in the +object's public interface (yuck), and (2) you may need to pass +the tied symbol to another subroutine which will attempt to treat +it in an OO-way... and that will break it: + +<FONT SIZE=3 FACE="courier"><PRE> + tie *T, 'FooHandle', &FOO_RDWR, 2; + print T "Hello, world\n"; # Operator is okay, BUT... + + tied(*T)->other_stuff; # yuck! AND... + + sub nope { shift->print("Nope!\n") } + X nope(\*T); # ERROR!!! (method "print" on unblessed ref) +</PRE></FONT> + +<P><B>Why a master and slave? + Why not simply write FooHandle to inherit from IO::Handle?</B> + I tried this, with an implementation similar to that of IO::Socket. +The problem is that <I>the whole point is to use this with objects +that don't have an underlying file/socket descriptor.</I>. +Subclassing IO::Handle will work fine for the OO stuff, and fine with +named operators <I>if</I> you tie()... but if you just attempt to say: + +<FONT SIZE=3 FACE="courier"><PRE> + $IO = FooHandle->new(&FOO_RDWR, 2); + print $IO "Hello!\n"; +</PRE></FONT> + +<P>you get a warning from Perl like: + +<FONT SIZE=3 FACE="courier"><PRE> + Filehandle GEN001 never opened +</PRE></FONT> + +<P>because it's trying to do system-level i/o on an (unopened) file +descriptor. To avoid this, you apparently have to tie() the handle... +which brings us right back to where we started! At least the +IO::WrapTie mixin lets us say: + +<FONT SIZE=3 FACE="courier"><PRE> + $IO = FooHandle->new_tie(&FOO_RDWR, 2); + print $IO "Hello!\n"; +</PRE></FONT> + +<P>and so is not <I>too</I> bad. <CODE>:-)</CODE> + + + +<P><HR> +<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A> + + +<P>Remember: this stuff is for doing FileHandle-like i/o on things +<I>without underlying file descriptors</I>. If you have an underlying +file descriptor, you're better off just inheriting from IO::Handle. + + +<P><B>Be aware that new_tie() always returns an instance of a +kind of IO::WrapTie::Master...</B> it does <B>not</B> return an instance +of the i/o class you're tying to! + + +<P>Invoking some methods on the master object causes AUTOLOAD to delegate +them to the slave object... so it <I>looks</I> like you're manipulating a +"FooHandle" object directly, but you're not. + + +<P>I have not explored all the ramifications of this use of tie(). +<I>Here there be dragons</I>. + + + +<P><HR> +<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> + + +<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). +President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). + +<P><HR> +<ADDRESS><FONT SIZE=-1> +Generated Thu Sep 28 02:36:03 2000 by cvu_pod2html +</FONT></ADDRESS> +</FONT></BODY> +</HTML> diff --git a/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif b/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif Binary files differnew file mode 100644 index 00000000..86986436 --- /dev/null +++ b/cpan/dist/IO-stringy/docs/IO/icons/h1bullet.gif diff --git a/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif b/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif Binary files differnew file mode 100644 index 00000000..d26510cd --- /dev/null +++ b/cpan/dist/IO-stringy/docs/IO/icons/h2bullet.gif diff --git a/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif b/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif Binary files differnew file mode 100644 index 00000000..f6001a5f --- /dev/null +++ b/cpan/dist/IO-stringy/docs/IO/icons/zeegee.gif 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 + |
