587 lines
15 KiB
HTML
587 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of IO::Stringy</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>IO::Stringy</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-02-28<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
IO-stringy - I/O on in-core objects like strings and arrays
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This toolkit primarily provides modules for performing both traditional
|
|
and object-oriented i/o) on things <I>other</I> than normal filehandles;
|
|
in particular, IO::Scalar, IO::ScalarArray,
|
|
and IO::Lines.
|
|
<P>
|
|
|
|
In the more-traditional IO::Handle front, we
|
|
have IO::AtomicFile
|
|
which may be used to painlessly create files which are updated
|
|
atomically.
|
|
<P>
|
|
|
|
And in the ``this-may-prove-useful'' corner, we have IO::Wrap,
|
|
whose exported <B>wraphandle()</B> function will clothe anything that's not
|
|
a blessed object in an IO::Handle-like wrapper... so you can just
|
|
use <FONT SIZE="-1">OO</FONT> syntax and stop worrying about whether your function's caller
|
|
handed you a string, a globref, or a FileHandle.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>WARNINGS</H2>
|
|
|
|
|
|
|
|
Perl's <FONT SIZE="-1">TIEHANDLE</FONT> spec was incomplete prior to 5.005_57;
|
|
it was missing support for <TT>"seek()"</TT>, <TT>"tell()"</TT>, and <TT>"eof()"</TT>.
|
|
Attempting to use these functions with an IO::Scalar, IO::ScalarArray,
|
|
IO::Lines, etc. <B>will not work</B> prior to 5.005_57.
|
|
None of the relevant methods will be invoked by Perl;
|
|
and even worse, this kind of bug can lie dormant for a while.
|
|
If you turn warnings on (via <TT>$^W</TT> or <TT>"perl -w"</TT>), and you see
|
|
something like this...
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
seek() on unopened file
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
...then you are probably trying to use one of these functions
|
|
on one of our <FONT SIZE="-1">IO::</FONT> classes with an old Perl. The remedy is to simply
|
|
use the <FONT SIZE="-1">OO</FONT> version; e.g.:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$SH->seek(0,0); ### GOOD: will work on any 5.005
|
|
seek($SH,0,0); ### WARNING: will only work on 5.005_57 and beyond
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H2>INSTALLATION</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Requirements</H3>
|
|
|
|
|
|
|
|
As of version 2.x, this toolkit requires Perl 5.005 for
|
|
the IO::Handle subclasses, and 5.005_57 or better is
|
|
<B>strongly</B> recommended. See ``<FONT SIZE="-1">WARNINGS''</FONT> for details.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Directions</H3>
|
|
|
|
|
|
|
|
Most of you already know the drill...
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
perl Makefile.PL
|
|
make
|
|
make test
|
|
make install
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
For everyone else out there...
|
|
if you've never installed Perl code before, or you're trying to use
|
|
this in an environment where your sysadmin or <FONT SIZE="-1">ISP</FONT> won't let you do
|
|
interesting things, <B>relax:</B> since this module contains no binary
|
|
extensions, you can cheat. That means copying the directory tree
|
|
under my ``./lib'' directory into someplace where your script can ``see''
|
|
it. For example, under Linux:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
cp -r IO-stringy-1.234/lib/* /path/to/my/perl/
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Now, in your Perl code, do this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use lib "/path/to/my/perl";
|
|
use IO::Scalar; ### or whatever
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Ok, now you've been told. At this point, anyone who whines about
|
|
not being given enough information gets an unflattering haiku
|
|
written about them in the next change log. I'll do it.
|
|
Don't think I won't.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
<TT>$Id:</TT> Stringy.pm,v 1.3 2005/02/10 21:24:05 dfs Exp $
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>TO DO</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">(2000/08/02) Finalize $/ support<DD>
|
|
|
|
|
|
Graham Barr submitted this patch half a <I>year</I> ago;
|
|
Like a moron, I lost his message under a ton of others,
|
|
and only now have the experimental implementation done.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Will the sudden sensitivity to $/ hose anyone out there?
|
|
I'm worried, so you have to enable it explicitly in 1.x.
|
|
It will be on by default in 2.x, though only IO::Scalar
|
|
has been implemented.
|
|
<DT id="2">(2001/08/08) Remove IO::WrapTie from new <FONT SIZE="-1">IO::</FONT> classes<DD>
|
|
|
|
|
|
It's not needed. Backwards compatibility could be maintained
|
|
by having <B>new_tie()</B> be identical to <B>new()</B>. Heck, I'll bet
|
|
that IO::WrapTie should be reimplemented so the returned
|
|
object is just like an IO::Scalar in its use of globrefs.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>CHANGE LOG</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="3">Version 2.110 (2005/02/10)<DD>
|
|
|
|
|
|
Maintainership taken over by <FONT SIZE="-1">DSKOLL</FONT> <<A HREF="mailto:dfs@roaringpenguin.com">dfs@roaringpenguin.com</A>>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Closed the following bugs at
|
|
<A HREF="https://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-stringy:">https://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-stringy:</A>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
2208 IO::ScalarArray->getline does not return undef for EOF if undef($/)
|
|
7132 IO-stringy/Makefile.PL bug - name should be module name
|
|
11249 IO::Scalar flush shouldn't return undef
|
|
2172 $\ (output record separator) not respected
|
|
8605 IO::InnerFile::seek() should return 1 on success
|
|
4798 *.html in lib/
|
|
4369 Improvement: handling of fixed-size reads in IO::Scalar
|
|
(Actually, bug 4369 was closed in Version 2.109)
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="4">Version 2.109 (2003/12/21)<DD>
|
|
|
|
|
|
IO::Scalar::getline now works with ref to int.
|
|
<I>Thanks to Dominique Quatravaux for this patch.</I>
|
|
<DT id="5">Version 2.108 (2001/08/20)<DD>
|
|
|
|
|
|
The terms-of-use have been placed in the distribution file ``<FONT SIZE="-1">COPYING''.</FONT>
|
|
Also, small documentation tweaks were made.
|
|
<DT id="6">Version 2.105 (2001/08/09)<DD>
|
|
|
|
|
|
Added support for various <B>seek()</B> whences to IO::ScalarArray.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Added support for consulting $/ in IO::Scalar and IO::ScalarArray.
|
|
The old <TT>"use_RS()"</TT> is not even an option.
|
|
Unsupported record separators will cause a <B>croak()</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Added a lot of regression tests to supoprt the above.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Better on-line docs (hyperlinks to individual functions).
|
|
<DT id="7">Version 2.103 (2001/08/08)<DD>
|
|
|
|
|
|
After sober consideration I have reimplemented <B>IO::Scalar::print()</B>
|
|
so that it once again always seeks to the end of the string.
|
|
Benchmarks show the new implementation to be just as fast as
|
|
Juergen's contributed patch; until someone can convince me otherwise,
|
|
the current, safer implementation stays.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
I thought more about giving IO::Scalar two separate handles,
|
|
one for reading and one for writing, as suggested by Binkley.
|
|
His points about what <B>tell()</B> and <B>eof()</B> return are, I think,
|
|
show-stoppers for this feature. Even the manpages for stdio's <B>fseek()</B>
|
|
seem to imply a <I>single</I> file position indicator, not two.
|
|
So I think I will take this off the <FONT SIZE="-1">TO DO</FONT> list.
|
|
<B>Remedy:</B> you can always have two handles open on the same
|
|
scalar, one which you only write to, and one which you only read from.
|
|
That should give the same effect.
|
|
<DT id="8">Version 2.101 (2001/08/07)<DD>
|
|
|
|
|
|
<B>Alpha release.</B>
|
|
This is the initial release of the ``IO::Scalar and friends are
|
|
now subclasses of IO::Handle''. I'm flinging it against the wall.
|
|
Please tell me if the banana sticks. When it does, the banana
|
|
will be called 2.2x.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
First off, <I>many many thanks to Doug Wilson</I>, who
|
|
has provided an <I>invaluable</I> service by patching IO::Scalar
|
|
and friends so that they (1) inherit from IO::Handle, (2) automatically
|
|
tie themselves so that the <TT>"new()"</TT> objects can be used in native i/o
|
|
constructs, and (3) doing it so that the whole damn thing passes
|
|
its regression tests. As Doug knows, my globref Kung-Fu was not
|
|
up to the task; he graciously provided the patches. This has earned
|
|
him a seat at the Co-Authors table, and the
|
|
right to have me address him as <I>sensei</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Performance of <B>IO::Scalar::print()</B> has been improved by as much as 2x
|
|
for lots of little prints, with the cost of forcing those
|
|
who print-then-seek-then-print to explicitly seek to end-of-string
|
|
before printing again.
|
|
<I>Thanks to Juergen Zeller for this patch.</I>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Added the <FONT SIZE="-1">COPYING</FONT> file, which had been missing from prior versions.
|
|
<I>Thanks to Albert Chin-A-Young for pointing this out.</I>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
IO::Scalar consults $/ by default (1.x ignored it by default).
|
|
Yes, I still need to support IO::ScalarArray.
|
|
<DT id="9">Version 1.221 (2001/08/07)<DD>
|
|
|
|
|
|
I threatened in ``<FONT SIZE="-1">INSTALLATION''</FONT> to write an unflattering haiku
|
|
about anyone who whined that I gave them insufficient information...
|
|
but it turns out that I left out a crucial direction. D'<FONT SIZE="-1">OH</FONT>!
|
|
<I>Thanks to David Beroff for the ``patch'' and the haiku...</I>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Enough info there?
|
|
Here's unflattering haiku:
|
|
Forgot the line, "make"! ;-)
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="10">Version 1.220 (2001/04/03)<DD>
|
|
|
|
|
|
Added untested <FONT SIZE="-1">SEEK, TELL,</FONT> and <FONT SIZE="-1">EOF</FONT> methods to IO::Scalar
|
|
and IO::ScalarArray to support corresponding functions for
|
|
tied filehandles: untested, because I'm still running 5.00556
|
|
and Perl is complaining about ``<B>tell()</B> on unopened file''.
|
|
<I>Thanks to Graham Barr for the suggestion.</I>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Removed not-fully-blank lines from modules; these were causing
|
|
lots of POD-related warnings.
|
|
<I>Thanks to Nicolas Joly for the suggestion.</I>
|
|
<DT id="11">Version 1.219 (2001/02/23)<DD>
|
|
|
|
|
|
IO::Scalar objects can now be made sensitive to $/ .
|
|
Pains were taken to keep the fast code fast while adding this feature.
|
|
<I>Cheers to Graham Barr for submitting his patch;
|
|
jeers to me for losing his email for 6 months.</I>
|
|
<DT id="12">Version 1.218 (2001/02/23)<DD>
|
|
|
|
|
|
IO::Scalar has a new <B>sysseek()</B> method.
|
|
<I>Thanks again to Richard Jones.</I>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
New ``<FONT SIZE="-1">TO DO''</FONT> section, because people who submit patches/ideas should
|
|
at least know that they're in the system... and that I won't lose
|
|
their stuff. Please read it.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
New entries in ``<FONT SIZE="-1">AUTHOR''</FONT>.
|
|
Please read those too.
|
|
<DT id="13">Version 1.216 (2000/09/28)<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 <FONT SIZE="-1">IO::</FONT> 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 <B>print()</B>, 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>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Newspaper headline
|
|
typeset by dyslexic man
|
|
loses urgency
|
|
|
|
BABY EATS FISH is
|
|
simply not equivalent
|
|
to FISH EATS BABY
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>New sysread and syswrite methods for IO::Scalar.</B>
|
|
<I>Thanks again to Richard Jones for this.</I>
|
|
<DT id="14">Version 1.215 (2000/09/05)<DD>
|
|
|
|
|
|
Added 'bool' overload to '""' overload, so object always evaluates
|
|
to true. (Whew. Glad I caught this before it went to <FONT SIZE="-1">CPAN.</FONT>)
|
|
<DT id="15">Version 1.214 (2000/09/03)<DD>
|
|
|
|
|
|
Evaluating an IO::Scalar in a string context now yields
|
|
the underlying string.
|
|
<I>Thanks to B. K. Oxley (binkley) for this.</I>
|
|
<DT id="16">Version 1.213 (2000/08/16)<DD>
|
|
|
|
|
|
Minor documentation fixes.
|
|
<DT id="17">Version 1.212 (2000/06/02)<DD>
|
|
|
|
|
|
Fixed IO::InnerFile incompatibility with Perl5.004.
|
|
<I>Thanks to many folks for reporting this.</I>
|
|
<DT id="18">Version 1.210 (2000/04/17)<DD>
|
|
|
|
|
|
Added <B>flush()</B> and other no-op methods.
|
|
<I>Thanks to Doru Petrescu for suggesting this.</I>
|
|
<DT id="19">Version 1.209 (2000/03/17)<DD>
|
|
|
|
|
|
Small bug fixes.
|
|
<DT id="20">Version 1.208 (2000/03/14)<DD>
|
|
|
|
|
|
Incorporated a number of contributed patches and extensions,
|
|
mostly related to speed hacks, support for ``offset'', and
|
|
<FONT SIZE="-1">WRITE/CLOSE</FONT> methods.
|
|
<I>Thanks to Richard Jones, Doru Petrescu, and many others.</I>
|
|
<DT id="21">Version 1.206 (1999/04/18)<DD>
|
|
|
|
|
|
Added creation of ./testout when Makefile.PL is run.
|
|
<DT id="22">Version 1.205 (1999/01/15)<DD>
|
|
|
|
|
|
Verified for Perl5.005.
|
|
<DT id="23">Version 1.202 (1998/04/18)<DD>
|
|
|
|
|
|
New IO::WrapTie and IO::AtomicFile added.
|
|
<DT id="24">Version 1.110<DD>
|
|
|
|
|
|
Added IO::WrapTie.
|
|
<DT id="25">Version 1.107<DD>
|
|
|
|
|
|
Added IO::Lines, and made some bug fixes to IO::ScalarArray.
|
|
Also, added <B>getc()</B>.
|
|
<DT id="26">Version 1.105<DD>
|
|
|
|
|
|
No real changes; just upgraded IO::Wrap to have a <TT>$VERSION</TT> string.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="27">Primary Maintainer<DD>
|
|
|
|
|
|
Dianne Skoll (<I><A HREF="mailto:dfs@roaringpenguin.com">dfs@roaringpenguin.com</A></I>).
|
|
<DT id="28">Original Author<DD>
|
|
|
|
|
|
Eryq (<I><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></I>).
|
|
President, ZeeGee Software Inc (<I><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></I>).
|
|
<DT id="29">Co-Authors<DD>
|
|
|
|
|
|
For all their bug reports and patch submissions, the following
|
|
are officially recognized:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Richard Jones
|
|
B. K. Oxley (binkley)
|
|
Doru Petrescu
|
|
Doug Wilson (for picking up the ball I dropped, and doing tie() right)
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
Go to <I><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></I> for the latest downloads
|
|
and on-line documentation for this module.
|
|
<P>
|
|
|
|
Enjoy. Yell if it breaks.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="30"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="31"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="32"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="33"><A HREF="#lbAE">WARNINGS</A><DD>
|
|
<DT id="34"><A HREF="#lbAF">INSTALLATION</A><DD>
|
|
<DL>
|
|
<DT id="35"><A HREF="#lbAG">Requirements</A><DD>
|
|
<DT id="36"><A HREF="#lbAH">Directions</A><DD>
|
|
</DL>
|
|
<DT id="37"><A HREF="#lbAI">VERSION</A><DD>
|
|
<DT id="38"><A HREF="#lbAJ">TO DO</A><DD>
|
|
<DT id="39"><A HREF="#lbAK">CHANGE LOG</A><DD>
|
|
<DT id="40"><A HREF="#lbAL">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|