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