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 getc
161 Instance method. Return the next character, or undef if none
162 remain. This does a read(1), which is somewhat costly.
163 getline
165 Instance method. Return the next line, or undef on end of data.
166 Can safely be called in an array context. Currently, lines are
167 delimited by "\n".
168 getlines
170 Instance method. Get all remaining lines. It will croak() if
171 accidentally called in a scalar context.
172 print ARGS...
174 Instance method. Print ARGS to the underlying array.
175 Currently, this always causes a "seek to the end of the array" and
177 generates a new array entry. This may change in the future.
178 read BUF, NBYTES, [OFFSET];
180 Instance method. Read some bytes from the array. Returns the
181 number of bytes actually read, 0 on end-of-file, undef on error.
182 write BUF, NBYTES, [OFFSET];
184 Instance method. Write some bytes into the array.
185 Seeking/telling and other attributes
187 autoflush
188 Instance method. No-op, provided for OO compatibility.
189 binmode
191 Instance method. No-op, provided for OO compatibility.
192 clearerr
194 Instance method. Clear the error and EOF flags. A no-op.
195 eof Instance method. Are we at end of file?
197 seek POS,WHENCE
199 Instance method. Seek to a given position in the stream. Only a
200 WHENCE of 0 (SEEK_SET) is supported.
201 tell
203 Instance method. Return the current position in the stream, as a
204 numeric offset.
205 setpos POS
207 Instance method. Seek to a given position in the array, using the
208 opaque getpos() value. Don't expect this to be a number.
209 getpos
211 Instance method. Return the current position in the array, as an
212 opaque value. Don't expect this to be a number.
213 aref
215 Instance method. Return a reference to the underlying array.
216
218 Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
219 support for "seek()", "tell()", and "eof()". Attempting to use these
220 functions with an IO::ScalarArray will not work prior to 5.005_57.
221 IO::ScalarArray will not have the relevant methods invoked; and even
222 worse, this kind of bug can lie dormant for a while. If you turn
223 warnings on (via $^W or "perl -w"), and you see something like this...
224 attempt to seek on unopened filehandle
226 ...then you are probably trying to use one of these functions on an
228 IO::ScalarArray with an old Perl. The remedy is to simply use the OO
229 version; e.g.:
230 $AH->seek(0,0); ### GOOD: will work on any 5.005
232 seek($AH,0,0); ### WARNING: will only work on 5.005_57 and beyond
233
235 $Id: ScalarArray.pm,v 1.7 2005/02/10 21:21:53 dfs Exp $
236
238 Primary Maintainer
239 David F. Skoll (dfs@roaringpenguin.com).
240 Principal author
242 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
243 (http://www.zeegee.com).
244 Other contributors
246 Thanks to the following individuals for their invaluable contributions
247 (if I've forgotten or misspelled your name, please email me!):
248 Andy Glew, for suggesting "getc()".
250 Brandon Browning, for suggesting "opened()".
252 Eric L. Brine, for his offset-using read() and write() implementations.
254 Doug Wilson, for the IO::Handle inheritance and automatic tie-ing.
256perl v5.12.0 2005-02-10 IO::ScalarArray(3)