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