1IO::ScalarArray(3) User Contributed Perl Documentation IO::ScalarArray(3)
2
6 IO::ScalarArray - IO:: interface for reading/writing an array of
7 scalars
8
10 Perform I/O on strings, using the basic OO interface...
11 use IO::ScalarArray;
13 @data = ("My mes", "sage:\n");
14 ### Open a handle on an array, and append to it:
16 $AH = new IO::ScalarArray \@data;
17 $AH->print("Hello");
18 $AH->print(", world!\nBye now!\n");
19 print "The array is now: ", @data, "\n";
20 ### Open a handle on an array, read it line-by-line, then close it:
22 $AH = new IO::ScalarArray \@data;
23 while (defined($_ = $AH->getline)) {
24 print "Got line: $_";
25 }
26 $AH->close;
27 ### Open a handle on an array, and slurp in all the lines:
29 $AH = new IO::ScalarArray \@data;
30 print "All lines:\n", $AH->getlines;
31 ### Get the current position (either of two ways):
33 $pos = $AH->getpos;
34 $offset = $AH->tell;
35 ### Set the current position (either of two ways):
37 $AH->setpos($pos);
38 $AH->seek($offset, 0);
39 ### Open an anonymous temporary array:
41 $AH = new IO::ScalarArray;
42 $AH->print("Hi there!");
43 print "I printed: ", @{$AH->aref}, "\n"; ### get at value
44 Don't like OO for your I/O? No problem. Thanks to the magic of an
46 invisible tie(), the following now works out of the box, just as it
47 does with IO::Handle:
48 use IO::ScalarArray;
50 @data = ("My mes", "sage:\n");
51 ### Open a handle on an array, and append to it:
53 $AH = new IO::ScalarArray \@data;
54 print $AH "Hello";
55 print $AH ", world!\nBye now!\n";
56 print "The array is now: ", @data, "\n";
57 ### Open a handle on a string, read it line-by-line, then close it:
59 $AH = new IO::ScalarArray \@data;
60 while (<$AH>) {
61 print "Got line: $_";
62 }
63 close $AH;
64 ### Open a handle on a string, and slurp in all the lines:
66 $AH = new IO::ScalarArray \@data;
67 print "All lines:\n", <$AH>;
68 ### Get the current position (WARNING: requires 5.6):
70 $offset = tell $AH;
71 ### Set the current position (WARNING: requires 5.6):
73 seek $AH, $offset, 0;
74 ### Open an anonymous temporary scalar:
76 $AH = new IO::ScalarArray;
77 print $AH "Hi there!";
78 print "I printed: ", @{$AH->aref}, "\n"; ### get at value
79 And for you folks with 1.x code out there: the old tie() style still
81 works, though this is unnecessary and deprecated:
82 use IO::ScalarArray;
84 ### Writing to a scalar...
86 my @a;
87 tie *OUT, 'IO::ScalarArray', \@a;
88 print OUT "line 1\nline 2\n", "line 3\n";
89 print "Array is now: ", @a, "\n"
90 ### Reading and writing an anonymous scalar...
92 tie *OUT, 'IO::ScalarArray';
93 print OUT "line 1\nline 2\n", "line 3\n";
94 tied(OUT)->seek(0,0);
95 while (<OUT>) {
96 print "Got line: ", $_;
97 }
98
100 This class is part of the IO::Stringy distribution; see IO::Stringy for
101 change log and general information.
102 The IO::ScalarArray class implements objects which behave just like
104 IO::Handle (or FileHandle) objects, except that you may use them to
105 write to (or read from) arrays of scalars. Logically, an array of
106 scalars defines an in-core "file" whose contents are the concatenation
107 of the scalars in the array. The handles created by this class are
108 automatically tiehandle'd (though please see "WARNINGS" for information
109 relevant to your Perl version).
110 For writing large amounts of data with individual print() statements,
112 this class is likely to be more efficient than IO::Scalar.
113 Basically, this:
115 my @a;
117 $AH = new IO::ScalarArray \@a;
118 $AH->print("Hel", "lo, "); ### OO style
119 $AH->print("world!\n"); ### ditto
120 Or this:
122 my @a;
124 $AH = new IO::ScalarArray \@a;
125 print $AH "Hel", "lo, "; ### non-OO style
126 print $AH "world!\n"; ### ditto
127 Causes @a to be set to the following array of 3 strings:
129 ( "Hel" ,
131 "lo, " ,
132 "world!\n" )
133 See IO::Scalar and compare with this class.
135
137 Construction
138 new [ARGS...]
139 Class method. Return a new, unattached array handle. If any
140 arguments are given, they're sent to open().
141 open [ARRAYREF]
143 Instance method. Open the array handle on a new array, pointed to
144 by ARRAYREF. If no ARRAYREF is given, a "private" array is created
145 to hold the file data.
146 Returns the self object on success, undefined on error.
148 opened
150 Instance method. Is the array handle opened on something?
151 close
153 Instance method. Disassociate the array handle from its underlying
154 array. Done automatically on destroy.
155 Input and output
157 flush
158 Instance method. No-op, provided for OO compatibility.
159 fileno
161 Instance method. No-op, returns undef
162 getc
164 Instance method. Return the next character, or undef if none
165 remain. This does a read(1), which is somewhat costly.
166 getline
168 Instance method. Return the next line, or undef on end of data.
169 Can safely be called in an array context. Currently, lines are
170 delimited by "\n".
171 getlines
173 Instance method. Get all remaining lines. It will croak() if
174 accidentally called in a scalar context.
175 print ARGS...
177 Instance method. Print ARGS to the underlying array.
178 Currently, this always causes a "seek to the end of the array" and
180 generates a new array entry. This may change in the future.
181 read BUF, NBYTES, [OFFSET];
183 Instance method. Read some bytes from the array. Returns the
184 number of bytes actually read, 0 on end-of-file, undef on error.
185 write BUF, NBYTES, [OFFSET];
187 Instance method. Write some bytes into the array.
188 Seeking/telling and other attributes
190 autoflush
191 Instance method. No-op, provided for OO compatibility.
192 binmode
194 Instance method. No-op, provided for OO compatibility.
195 clearerr
197 Instance method. Clear the error and EOF flags. A no-op.
198 eof Instance method. Are we at end of file?
200 seek POS,WHENCE
202 Instance method. Seek to a given position in the stream. Only a
203 WHENCE of 0 (SEEK_SET) is supported.
204 tell
206 Instance method. Return the current position in the stream, as a
207 numeric offset.
208 setpos POS
210 Instance method. Seek to a given position in the array, using the
211 opaque getpos() value. Don't expect this to be a number.
212 getpos
214 Instance method. Return the current position in the array, as an
215 opaque value. Don't expect this to be a number.
216 aref
218 Instance method. Return a reference to the underlying array.
219
221 Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
222 support for "seek()", "tell()", and "eof()". Attempting to use these
223 functions with an IO::ScalarArray will not work prior to 5.005_57.
224 IO::ScalarArray will not have the relevant methods invoked; and even
225 worse, this kind of bug can lie dormant for a while. If you turn
226 warnings on (via $^W or "perl -w"), and you see something like this...
227 attempt to seek on unopened filehandle
229 ...then you are probably trying to use one of these functions on an
231 IO::ScalarArray with an old Perl. The remedy is to simply use the OO
232 version; e.g.:
233 $AH->seek(0,0); ### GOOD: will work on any 5.005
235 seek($AH,0,0); ### WARNING: will only work on 5.005_57 and beyond
236
238 $Id: ScalarArray.pm,v 1.7 2005/02/10 21:21:53 dfs Exp $
239
241 Primary Maintainer
242 Dianne Skoll (dfs@roaringpenguin.com).
243 Principal author
245 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
246 (http://www.zeegee.com).
247 Other contributors
249 Thanks to the following individuals for their invaluable contributions
250 (if I've forgotten or misspelled your name, please email me!):
251 Andy Glew, for suggesting "getc()".
253 Brandon Browning, for suggesting "opened()".
255 Eric L. Brine, for his offset-using read() and write() implementations.
257 Doug Wilson, for the IO::Handle inheritance and automatic tie-ing.
259perl v5.28.1 2015-04-22 IO::ScalarArray(3)