3 <TITLE>IO::ScalarArray 2.103</TITLE>
6 bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
7 <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 2.103</H1>
9 <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
10 <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
11 <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
12 <LI> <A NAME="menu:PUBLIC_INTERFACE"><A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A></A>
14 <LI> <A NAME="menu:Construction"><A HREF="#Construction">Construction</A></A>
16 <LI> <A NAME="menu:item:new_ARGS"><A HREF="#item:new_ARGS">new [ARGS...]</A></A>
17 <LI> <A NAME="menu:item:open_ARRAYREF"><A HREF="#item:open_ARRAYREF">open [ARRAYREF]</A></A>
18 <LI> <A NAME="menu:item:opened"><A HREF="#item:opened">opened</A></A>
19 <LI> <A NAME="menu:item:close"><A HREF="#item:close">close</A></A>
21 <LI> <A NAME="menu:Input_and_output"><A HREF="#Input_and_output">Input and output</A></A>
23 <LI> <A NAME="menu:item:flush"><A HREF="#item:flush">flush </A></A>
24 <LI> <A NAME="menu:item:getc"><A HREF="#item:getc">getc</A></A>
25 <LI> <A NAME="menu:item:getline"><A HREF="#item:getline">getline</A></A>
26 <LI> <A NAME="menu:item:getlines"><A HREF="#item:getlines">getlines</A></A>
27 <LI> <A NAME="menu:item:print_ARGS"><A HREF="#item:print_ARGS">print ARGS...</A></A>
28 <LI> <A NAME="menu:item:read_BUF_NBYTES_OFFSET"><A HREF="#item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET];</A></A>
29 <LI> <A NAME="menu:item:write_BUF_NBYTES_OFFSET"><A HREF="#item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET];</A></A>
31 <LI> <A NAME="menu:Seeking_telling_and_other_attributes"><A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A></A>
33 <LI> <A NAME="menu:item:autoflush"><A HREF="#item:autoflush">autoflush </A></A>
34 <LI> <A NAME="menu:item:binmode"><A HREF="#item:binmode">binmode</A></A>
35 <LI> <A NAME="menu:item:clearerr"><A HREF="#item:clearerr">clearerr</A></A>
36 <LI> <A NAME="menu:item:eof"><A HREF="#item:eof">eof </A></A>
37 <LI> <A NAME="menu:item:seek_POS_WHENCE"><A HREF="#item:seek_POS_WHENCE">seek POS,WHENCE</A></A>
38 <LI> <A NAME="menu:item:tell"><A HREF="#item:tell">tell</A></A>
39 <LI> <A NAME="menu:item:setpos_POS"><A HREF="#item:setpos_POS">setpos POS</A></A>
40 <LI> <A NAME="menu:item:getpos"><A HREF="#item:getpos">getpos</A></A>
41 <LI> <A NAME="menu:item:aref"><A HREF="#item:aref">aref</A></A>
44 <LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A>
45 <LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A>
46 <LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
48 <LI> <A NAME="menu:Principal_author"><A HREF="#Principal_author">Principal author</A></A>
49 <LI> <A NAME="menu:Other_contributors"><A HREF="#Other_contributors">Other contributors</A></A>
55 <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>
58 <P>IO::ScalarArray - IO:: interface for reading/writing an array of scalars
63 <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>
66 <P>Perform I/O on strings, using the basic OO interface...
68 <FONT SIZE=3 FACE="courier"><PRE>
70 @data = ("My mes", "sage:\n");
72 <FONT SIZE=3 FACE="courier"><PRE>
73 ### Open a handle on an array, and append to it:
74 $AH = new IO::ScalarArray \@data;
75 $AH->print("Hello");
76 $AH->print(", world!\nBye now!\n");
77 print "The array is now: ", @data, "\n";
79 <FONT SIZE=3 FACE="courier"><PRE>
80 ### Open a handle on an array, read it line-by-line, then close it:
81 $AH = new IO::ScalarArray \@data;
82 while (defined($_ = $AH->getline)) {
83 print "Got line: $_";
87 <FONT SIZE=3 FACE="courier"><PRE>
88 ### Open a handle on an array, and slurp in all the lines:
89 $AH = new IO::ScalarArray \@data;
90 print "All lines:\n", $AH->getlines;
92 <FONT SIZE=3 FACE="courier"><PRE>
93 ### Get the current position (either of two ways):
94 $pos = $AH->getpos;
95 $offset = $AH->tell;
97 <FONT SIZE=3 FACE="courier"><PRE>
98 ### Set the current position (either of two ways):
100 $AH->seek($offset, 0);
102 <FONT SIZE=3 FACE="courier"><PRE>
103 ### Open an anonymous temporary array:
104 $AH = new IO::ScalarArray;
105 $AH->print("Hi there!");
106 print "I printed: ", @{$AH->aref}, "\n"; ### get at value
109 <P>Don't like OO for your I/O? No problem.
110 Thanks to the magic of an invisible tie(), the following now
111 works out of the box, just as it does with IO::Handle:
114 @data = ("My mes", "sage:\n");
116 <FONT SIZE=3 FACE="courier"><PRE>
117 ### Open a handle on an array, and append to it:
118 $AH = new IO::ScalarArray \@data;
119 print $AH "Hello";
120 print $AH ", world!\nBye now!\n";
121 print "The array is now: ", @data, "\n";
123 <FONT SIZE=3 FACE="courier"><PRE>
124 ### Open a handle on a string, read it line-by-line, then close it:
125 $AH = new IO::ScalarArray \@data;
126 while (<$AH>) {
127 print "Got line: $_";
131 <FONT SIZE=3 FACE="courier"><PRE>
132 ### Open a handle on a string, and slurp in all the lines:
133 $AH = new IO::ScalarArray \@data;
134 print "All lines:\n", <$AH>;
136 <FONT SIZE=3 FACE="courier"><PRE>
137 ### Get the current position (WARNING: requires 5.6):
140 <FONT SIZE=3 FACE="courier"><PRE>
141 ### Set the current position (WARNING: requires 5.6):
142 seek $AH, $offset, 0;
144 <FONT SIZE=3 FACE="courier"><PRE>
145 ### Open an anonymous temporary scalar:
146 $AH = new IO::ScalarArray;
147 print $AH "Hi there!";
148 print "I printed: ", @{$AH->aref}, "\n"; ### get at value
151 <P>And for you folks with 1.x code out there: the old tie() style still works,
152 though this is <I>unnecessary and deprecated</I>:
154 <FONT SIZE=3 FACE="courier"><PRE>
157 <FONT SIZE=3 FACE="courier"><PRE>
158 ### Writing to a scalar...
160 tie *OUT, 'IO::ScalarArray', \@a;
161 print OUT "line 1\nline 2\n", "line 3\n";
162 print "Array is now: ", @a, "\n"
164 <FONT SIZE=3 FACE="courier"><PRE>
165 ### Reading and writing an anonymous scalar...
166 tie *OUT, 'IO::ScalarArray';
167 print OUT "line 1\nline 2\n", "line 3\n";
168 tied(OUT)->seek(0,0);
169 while (<OUT>) {
170 print "Got line: ", $_;
176 <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
179 <P>This class is part of the IO::Stringy distribution;
180 see <A HREF="../IO/Stringy.pm.html">IO::Stringy</A> for change log and general information.
183 <P>The IO::ScalarArray class implements objects which behave just like
184 IO::Handle (or FileHandle) objects, except that you may use them
185 to write to (or read from) arrays of scalars. Logically, an
186 array of scalars defines an in-core "file" whose contents are
187 the concatenation of the scalars in the array. The handles created by
188 this class are automatically tiehandle'd (though please see <A HREF="#WARNINGS">WARNINGS</A>
189 for information relevant to your Perl version).
192 <P>For writing large amounts of data with individual print() statements,
193 this class is likely to be more efficient than IO::Scalar.
198 <FONT SIZE=3 FACE="courier"><PRE>
200 $AH = new IO::ScalarArray \@a;
201 $AH->print("Hel", "lo, "); ### OO style
202 $AH->print("world!\n"); ### ditto
207 <FONT SIZE=3 FACE="courier"><PRE>
209 $AH = new IO::ScalarArray \@a;
210 print $AH "Hel", "lo, "; ### non-OO style
211 print $AH "world!\n"; ### ditto
214 <P>Causes @a to be set to the following array of 3 strings:
216 <FONT SIZE=3 FACE="courier"><PRE>
219 "world!\n" )
222 <P>See <A HREF="../IO/Scalar.pm.html">IO::Scalar</A> and compare with this class.
227 <A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A>
232 <A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A>
237 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:new"><A NAME="item:new_ARGS">new [ARGS...]</A></A></B></DT>
240 Return a new, unattached array handle.
241 If any arguments are given, they're sent to open().
243 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:open"><A NAME="item:open_ARRAYREF">open [ARRAYREF]</A></A></B></DT>
245 <I>Instance method.</I>
246 Open the array handle on a new array, pointed to by ARRAYREF.
247 If no ARRAYREF is given, a "private" array is created to hold
251 <P>Returns the self object on success, undefined on error.
253 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:opened">opened</A></B></DT>
255 <I>Instance method.</I>
256 Is the array handle opened on something?
258 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:close">close</A></B></DT>
260 <I>Instance method.</I>
261 Disassociate the array handle from its underlying array.
262 Done automatically on destroy.
269 <A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A>
274 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:flush">flush</A></B></DT>
276 <I>Instance method.</I>
277 No-op, provided for OO compatibility.
279 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getc">getc</A></B></DT>
281 <I>Instance method.</I>
282 Return the next character, or undef if none remain.
283 This does a read(1), which is somewhat costly.
285 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getline">getline</A></B></DT>
287 <I>Instance method.</I>
288 Return the next line, or undef on end of data.
289 Can safely be called in an array context.
290 Currently, lines are delimited by "\n".
292 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getlines">getlines</A></B></DT>
294 <I>Instance method.</I>
295 Get all remaining lines.
296 It will croak() if accidentally called in a scalar context.
298 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:print"><A NAME="item:print_ARGS">print ARGS...</A></A></B></DT>
300 <I>Instance method.</I>
301 Print ARGS to the underlying array.
304 <P>Currently, this always causes a "seek to the end of the array"
305 and generates a new array entry. This may change in the future.
307 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:read"><A NAME="item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET];</A></A></B></DT>
309 <I>Instance method.</I>
310 Read some bytes from the array.
311 Returns the number of bytes actually read, 0 on end-of-file, undef on error.
313 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:write"><A NAME="item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET];</A></A></B></DT>
315 <I>Instance method.</I>
316 Write some bytes into the array.
323 <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>
328 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:autoflush">autoflush</A></B></DT>
330 <I>Instance method.</I>
331 No-op, provided for OO compatibility.
333 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:binmode">binmode</A></B></DT>
335 <I>Instance method.</I>
336 No-op, provided for OO compatibility.
338 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:clearerr">clearerr</A></B></DT>
340 <I>Instance method.</I> Clear the error and EOF flags. A no-op.
342 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:eof">eof</A></B></DT>
344 <I>Instance method.</I> Are we at end of file?
346 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:seek"><A NAME="item:seek_POS_WHENCE">seek POS,WHENCE</A></A></B></DT>
348 <I>Instance method.</I>
349 Seek to a given position in the stream.
350 Only a WHENCE of 0 (SEEK_SET) is supported.
352 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tell">tell</A></B></DT>
354 <I>Instance method.</I>
355 Return the current position in the stream, as a numeric offset.
357 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:setpos"><A NAME="item:setpos_POS">setpos POS</A></A></B></DT>
359 <I>Instance method.</I>
360 Seek to a given position in the array, using the opaque getpos() value.
361 Don't expect this to be a number.
363 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getpos">getpos</A></B></DT>
365 <I>Instance method.</I>
366 Return the current position in the array, as an opaque value.
367 Don't expect this to be a number.
369 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:aref">aref</A></B></DT>
371 <I>Instance method.</I>
372 Return a reference to the underlying array.
379 <A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>
382 <P>Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
383 it was missing support for <CODE>seek()</CODE>, <CODE>tell()</CODE>, and <CODE>eof()</CODE>.
384 Attempting to use these functions with an IO::ScalarArray will not work
385 prior to 5.005_57. IO::ScalarArray will not have the relevant methods
386 invoked; and even worse, this kind of bug can lie dormant for a while.
387 If you turn warnings on (via <CODE>$^W</CODE> or <CODE>perl -w</CODE>),
388 and you see something like this...
390 <FONT SIZE=3 FACE="courier"><PRE>
391 attempt to seek on unopened filehandle
394 <P>...then you are probably trying to use one of these functions
395 on an IO::ScalarArray with an old Perl. The remedy is to simply
396 use the OO version; e.g.:
398 <FONT SIZE=3 FACE="courier"><PRE>
399 $AH->seek(0,0); ### GOOD: will work on any 5.005
400 seek($AH,0,0); ### WARNING: will only work on 5.005_57 and beyond
405 <A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>
408 <P>$Id: ScalarArray.pm,v 2.103 2001/08/09 08:04:44 eryq Exp $
413 <A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>
418 <A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A>
421 <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
422 President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).
427 <A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A>
430 <P>Thanks to the following individuals for their invaluable contributions
431 (if I've forgotten or misspelled your name, please email me!):
435 for suggesting <CODE>getc()</CODE>.
438 <P><I>Brandon Browning,</I>
439 for suggesting <CODE>opened()</CODE>.
442 <P><I>Eric L. Brine,</I>
443 for his offset-using read() and write() implementations.
446 <P><I>Doug Wilson,</I>
447 for the IO::Handle inheritance and automatic tie-ing.
450 <ADDRESS><FONT SIZE=-1>
451 Generated Sun Dec 21 13:54:37 2003 by cvu_pod2html