vcs.maemo.org Git - pkg-perl/blob - deb-src/libio-stringy-perl/io-stringy-2.110/README

   1 NAME
   2     IO-stringy - I/O on in-core objects like strings and arrays
   3
   4 SYNOPSIS
   5         IO::
   6         ::AtomicFile   adpO  Write a file which is updated atomically     ERYQ
   7         ::Lines        bdpO  I/O handle to read/write to array of lines   ERYQ
   8         ::Scalar       RdpO  I/O handle to read/write to a string         ERYQ
   9         ::ScalarArray  RdpO  I/O handle to read/write to array of scalars ERYQ
  10         ::Wrap         RdpO  Wrap old-style FHs in standard OO interface  ERYQ
  11         ::WrapTie      adpO  Tie your handles & retain full OO interface  ERYQ
  12
  13 DESCRIPTION
  14     This toolkit primarily provides modules for performing both traditional
  15     and object-oriented i/o) on things *other* than normal filehandles; in
  16     particular, IO::Scalar, IO::ScalarArray, and IO::Lines.
  17
  18     In the more-traditional IO::Handle front, we have IO::AtomicFile which
  19     may be used to painlessly create files which are updated atomically.
  20
  21     And in the "this-may-prove-useful" corner, we have IO::Wrap, whose
  22     exported wraphandle() function will clothe anything that's not a blessed
  23     object in an IO::Handle-like wrapper... so you can just use OO syntax
  24     and stop worrying about whether your function's caller handed you a
  25     string, a globref, or a FileHandle.
  26
  27 WARNINGS
  28     Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
  29     support for "seek()", "tell()", and "eof()". Attempting to use these
  30     functions with an IO::Scalar, IO::ScalarArray, IO::Lines, etc. will not
  31     work prior to 5.005_57. None of the relevant methods will be invoked by
  32     Perl; and even worse, this kind of bug can lie dormant for a while. If
  33     you turn warnings on (via $^W or "perl -w"), and you see something like
  34     this...
  35
  36         seek() on unopened file
  37
  38     ...then you are probably trying to use one of these functions on one of
  39     our IO:: classes with an old Perl. The remedy is to simply use the OO
  40     version; e.g.:
  41
  42         $SH->seek(0,0);    ### GOOD: will work on any 5.005
  43         seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
  44
  45 INSTALLATION
  46   Requirements
  47     As of version 2.x, this toolkit requires Perl 5.005 for the IO::Handle
  48     subclasses, and 5.005_57 or better is strongly recommended. See
  49     "WARNINGS" for details.
  50
  51   Directions
  52     Most of you already know the drill...
  53
  54         perl Makefile.PL
  55         make
  56         make test
  57         make install
  58
  59     For everyone else out there... if you've never installed Perl code
  60     before, or you're trying to use this in an environment where your
  61     sysadmin or ISP won't let you do interesting things, relax: since this
  62     module contains no binary extensions, you can cheat. That means copying
  63     the directory tree under my "./lib" directory into someplace where your
  64     script can "see" it. For example, under Linux:
  65
  66         cp -r IO-stringy-1.234/lib/* /path/to/my/perl/
  67
  68     Now, in your Perl code, do this:
  69
  70         use lib "/path/to/my/perl";
  71         use IO::Scalar;                   ### or whatever
  72
  73     Ok, now you've been told. At this point, anyone who whines about not
  74     being given enough information gets an unflattering haiku written about
  75     them in the next change log. I'll do it. Don't think I won't.
  76
  77 VERSION
  78     $Id: README,v 1.2 2005/02/10 21:24:05 dfs Exp $
  79
  80 TO DO
  81     (2000/08/02) Finalize $/ support
  82         Graham Barr submitted this patch half a *year* ago; Like a moron, I
  83         lost his message under a ton of others, and only now have the
  84         experimental implementation done.
  85
  86         Will the sudden sensitivity to $/ hose anyone out there? I'm
  87         worried, so you have to enable it explicitly in 1.x. It will be on
  88         by default in 2.x, though only IO::Scalar has been implemented.
  89
  90     (2001/08/08) Remove IO::WrapTie from new IO:: classes
  91         It's not needed. Backwards compatibility could be maintained by
  92         having new_tie() be identical to new(). Heck, I'll bet that
  93         IO::WrapTie should be reimplemented so the returned object is just
  94         like an IO::Scalar in its use of globrefs.
  95
  96 CHANGE LOG
  97     Version 2.110 (2005/02/10)
  98         Maintainership taken over by DSKOLL <dfs@roaringpenguin.com>
  99
 100         Closed the following bugs at
 101         https://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-stringy:
 102
 103     *   2208 IO::ScalarArray->getline does not return undef for EOF if
 104         undef($/)
 105
 106     *   7132 IO-stringy/Makefile.PL bug - name should be module name
 107
 108     *   11249 IO::Scalar flush shouldn't return undef
 109
 110     *   2172 $\ (output record separator) not respected
 111
 112     *   8605 IO::InnerFile::seek() should return 1 on success
 113
 114     *   4798 *.html in lib/
 115
 116     *   4369 Improvement: handling of fixed-size reads in IO::Scalar
 117
 118         (Actually, bug 4369 was closed in Version 2.109)
 119
 120     Version 2.109 (2003/12/21)
 121         IO::Scalar::getline now works with ref to int. *Thanks to Dominique
 122         Quatravaux for this patch.*
 123
 124     Version 2.108 (2001/08/20)
 125         The terms-of-use have been placed in the distribution file
 126         "COPYING". Also, small documentation tweaks were made.
 127
 128     Version 2.105 (2001/08/09)
 129         Added support for various seek() whences to IO::ScalarArray.
 130
 131         Added support for consulting $/ in IO::Scalar and IO::ScalarArray.
 132         The old "use_RS()" is not even an option. Unsupported record
 133         separators will cause a croak().
 134
 135         Added a lot of regression tests to supoprt the above.
 136
 137         Better on-line docs (hyperlinks to individual functions).
 138
 139     Version 2.103 (2001/08/08)
 140         After sober consideration I have reimplemented IO::Scalar::print()
 141         so that it once again always seeks to the end of the string.
 142         Benchmarks show the new implementation to be just as fast as
 143         Juergen's contributed patch; until someone can convince me
 144         otherwise, the current, safer implementation stays.
 145
 146         I thought more about giving IO::Scalar two separate handles, one for
 147         reading and one for writing, as suggested by Binkley. His points
 148         about what tell() and eof() return are, I think, show-stoppers for
 149         this feature. Even the manpages for stdio's fseek() seem to imply a
 150         *single* file position indicator, not two. So I think I will take
 151         this off the TO DO list. Remedy: you can always have two handles
 152         open on the same scalar, one which you only write to, and one which
 153         you only read from. That should give the same effect.
 154
 155     Version 2.101 (2001/08/07)
 156         Alpha release. This is the initial release of the "IO::Scalar and
 157         friends are now subclasses of IO::Handle". I'm flinging it against
 158         the wall. Please tell me if the banana sticks. When it does, the
 159         banana will be called 2.2x.
 160
 161         First off, *many many thanks to Doug Wilson*, who has provided an
 162         *invaluable* service by patching IO::Scalar and friends so that they
 163         (1) inherit from IO::Handle, (2) automatically tie themselves so
 164         that the "new()" objects can be used in native i/o constructs, and
 165         (3) doing it so that the whole damn thing passes its regression
 166         tests. As Doug knows, my globref Kung-Fu was not up to the task; he
 167         graciously provided the patches. This has earned him a seat at the
 168         Co-Authors table, and the right to have me address him as *sensei*.
 169
 170         Performance of IO::Scalar::print() has been improved by as much as
 171         2x for lots of little prints, with the cost of forcing those who
 172         print-then-seek-then-print to explicitly seek to end-of-string
 173         before printing again. *Thanks to Juergen Zeller for this patch.*
 174
 175         Added the COPYING file, which had been missing from prior versions.
 176         *Thanks to Albert Chin-A-Young for pointing this out.*
 177
 178         IO::Scalar consults $/ by default (1.x ignored it by default). Yes,
 179         I still need to support IO::ScalarArray.
 180
 181     Version 1.221 (2001/08/07)
 182         I threatened in "INSTALLATION" to write an unflattering haiku about
 183         anyone who whined that I gave them insufficient information... but
 184         it turns out that I left out a crucial direction. D'OH! *Thanks to
 185         David Beroff for the "patch" and the haiku...*
 186
 187                Enough info there?
 188                  Here's unflattering haiku:
 189                Forgot the line, "make"!  ;-)
 190
 191     Version 1.220 (2001/04/03)
 192         Added untested SEEK, TELL, and EOF methods to IO::Scalar and
 193         IO::ScalarArray to support corresponding functions for tied
 194         filehandles: untested, because I'm still running 5.00556 and Perl is
 195         complaining about "tell() on unopened file". *Thanks to Graham Barr
 196         for the suggestion.*
 197
 198         Removed not-fully-blank lines from modules; these were causing lots
 199         of POD-related warnings. *Thanks to Nicolas Joly for the
 200         suggestion.*
 201
 202     Version 1.219 (2001/02/23)
 203         IO::Scalar objects can now be made sensitive to $/ . Pains were
 204         taken to keep the fast code fast while adding this feature. *Cheers
 205         to Graham Barr for submitting his patch; jeers to me for losing his
 206         email for 6 months.*
 207
 208     Version 1.218 (2001/02/23)
 209         IO::Scalar has a new sysseek() method. *Thanks again to Richard
 210         Jones.*
 211
 212         New "TO DO" section, because people who submit patches/ideas should
 213         at least know that they're in the system... and that I won't lose
 214         their stuff. Please read it.
 215
 216         New entries in "AUTHOR". Please read those too.
 217
 218     Version 1.216 (2000/09/28)
 219         IO::Scalar and IO::ScalarArray now inherit from IO::Handle. I
 220         thought I'd remembered a problem with this ages ago, related to the
 221         fact that these IO:: modules don't have "real" filehandles, but the
 222         problem apparently isn't surfacing now. If you suddenly encounter
 223         Perl warnings during global destruction (especially if you're using
 224         tied filehandles), then please let me know! *Thanks to B. K. Oxley
 225         (binkley) for this.*
 226
 227         Nasty bug fixed in IO::Scalar::write(). Apparently, the offset and
 228         the number-of-bytes arguments were, for all practical purposes,
 229         *reversed.* You were okay if you did all your writing with print(),
 230         but boy was *this* a stupid bug! *Thanks to Richard Jones for
 231         finding this one. For you, Rich, a double-length haiku:*
 232
 233                Newspaper headline
 234                   typeset by dyslexic man
 235                loses urgency
 236
 237                BABY EATS FISH is
 238                   simply not equivalent
 239                to FISH EATS BABY
 240
 241         New sysread and syswrite methods for IO::Scalar. *Thanks again to
 242         Richard Jones for this.*
 243
 244     Version 1.215 (2000/09/05)
 245         Added 'bool' overload to '""' overload, so object always evaluates
 246         to true. (Whew. Glad I caught this before it went to CPAN.)
 247
 248     Version 1.214 (2000/09/03)
 249         Evaluating an IO::Scalar in a string context now yields the
 250         underlying string. *Thanks to B. K. Oxley (binkley) for this.*
 251
 252     Version 1.213 (2000/08/16)
 253         Minor documentation fixes.
 254
 255     Version 1.212 (2000/06/02)
 256         Fixed IO::InnerFile incompatibility with Perl5.004. *Thanks to many
 257         folks for reporting this.*
 258
 259     Version 1.210 (2000/04/17)
 260         Added flush() and other no-op methods. *Thanks to Doru Petrescu for
 261         suggesting this.*
 262
 263     Version 1.209 (2000/03/17)
 264         Small bug fixes.
 265
 266     Version 1.208 (2000/03/14)
 267         Incorporated a number of contributed patches and extensions, mostly
 268         related to speed hacks, support for "offset", and WRITE/CLOSE
 269         methods. *Thanks to Richard Jones, Doru Petrescu, and many others.*
 270
 271     Version 1.206 (1999/04/18)
 272         Added creation of ./testout when Makefile.PL is run.
 273
 274     Version 1.205 (1999/01/15)
 275         Verified for Perl5.005.
 276
 277     Version 1.202 (1998/04/18)
 278         New IO::WrapTie and IO::AtomicFile added.
 279
 280     Version 1.110
 281         Added IO::WrapTie.
 282
 283     Version 1.107
 284         Added IO::Lines, and made some bug fixes to IO::ScalarArray. Also,
 285         added getc().
 286
 287     Version 1.105
 288         No real changes; just upgraded IO::Wrap to have a $VERSION string.
 289
 290 AUTHOR
 291     Primary Maintainer
 292         David F. Skoll (dfs@roaringpenguin.com).
 293
 294     Original Author
 295         Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
 296         (http://www.zeegee.com).
 297
 298     Co-Authors
 299         For all their bug reports and patch submissions, the following are
 300         officially recognized:
 301
 302              Richard Jones
 303              B. K. Oxley (binkley)
 304              Doru Petrescu
 305              Doug Wilson (for picking up the ball I dropped, and doing tie() right)
 306
 307     Go to http://www.zeegee.com for the latest downloads and on-line
 308     documentation for this module.
 309
 310     Enjoy. Yell if it breaks.
 311