1IO::Scalar(3) User Contributed Perl Documentation IO::Scalar(3)
2
3
4
6 IO::Scalar - IO:: interface for reading/writing a scalar
7
9 Perform I/O on strings, using the basic OO interface...
10
11 use 5.005;
12 use IO::Scalar;
13 $data = "My message:\n";
14
15 ### Open a handle on a string, and append to it:
16 $SH = new IO::Scalar \$data;
17 $SH->print("Hello");
18 $SH->print(", world!\nBye now!\n");
19 print "The string is now: ", $data, "\n";
20
21 ### Open a handle on a string, read it line-by-line, then close it:
22 $SH = new IO::Scalar \$data;
23 while (defined($_ = $SH->getline)) {
24 print "Got line: $_";
25 }
26 $SH->close;
27
28 ### Open a handle on a string, and slurp in all the lines:
29 $SH = new IO::Scalar \$data;
30 print "All lines:\n", $SH->getlines;
31
32 ### Get the current position (either of two ways):
33 $pos = $SH->getpos;
34 $offset = $SH->tell;
35
36 ### Set the current position (either of two ways):
37 $SH->setpos($pos);
38 $SH->seek($offset, 0);
39
40 ### Open an anonymous temporary scalar:
41 $SH = new IO::Scalar;
42 $SH->print("Hi there!");
43 print "I printed: ", ${$SH->sref}, "\n"; ### get at value
44
45 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
49 use 5.005;
50 use IO::Scalar;
51 $data = "My message:\n";
52
53 ### Open a handle on a string, and append to it:
54 $SH = new IO::Scalar \$data;
55 print $SH "Hello";
56 print $SH ", world!\nBye now!\n";
57 print "The string is now: ", $data, "\n";
58
59 ### Open a handle on a string, read it line-by-line, then close it:
60 $SH = new IO::Scalar \$data;
61 while (<$SH>) {
62 print "Got line: $_";
63 }
64 close $SH;
65
66 ### Open a handle on a string, and slurp in all the lines:
67 $SH = new IO::Scalar \$data;
68 print "All lines:\n", <$SH>;
69
70 ### Get the current position (WARNING: requires 5.6):
71 $offset = tell $SH;
72
73 ### Set the current position (WARNING: requires 5.6):
74 seek $SH, $offset, 0;
75
76 ### Open an anonymous temporary scalar:
77 $SH = new IO::Scalar;
78 print $SH "Hi there!";
79 print "I printed: ", ${$SH->sref}, "\n"; ### get at value
80
81 And for you folks with 1.x code out there: the old tie() style still
82 works, though this is unnecessary and deprecated:
83
84 use IO::Scalar;
85
86 ### Writing to a scalar...
87 my $s;
88 tie *OUT, 'IO::Scalar', \$s;
89 print OUT "line 1\nline 2\n", "line 3\n";
90 print "String is now: $s\n"
91
92 ### Reading and writing an anonymous scalar...
93 tie *OUT, 'IO::Scalar';
94 print OUT "line 1\nline 2\n", "line 3\n";
95 tied(OUT)->seek(0,0);
96 while (<OUT>) {
97 print "Got line: ", $_;
98 }
99
100 Stringification works, too!
101
102 my $SH = new IO::Scalar \$data;
103 print $SH "Hello, ";
104 print $SH "world!";
105 print "I printed: $SH\n";
106
108 This class is part of the IO::Stringy distribution; see IO::Stringy for
109 change log and general information.
110
111 The IO::Scalar class implements objects which behave just like IO::Han‐
112 dle (or FileHandle) objects, except that you may use them to write to
113 (or read from) scalars. These handles are automatically tiehandle'd
114 (though please see "WARNINGS" for information relevant to your Perl
115 version).
116
117 Basically, this:
118
119 my $s;
120 $SH = new IO::Scalar \$s;
121 $SH->print("Hel", "lo, "); ### OO style
122 $SH->print("world!\n"); ### ditto
123
124 Or this:
125
126 my $s;
127 $SH = tie *OUT, 'IO::Scalar', \$s;
128 print OUT "Hel", "lo, "; ### non-OO style
129 print OUT "world!\n"; ### ditto
130
131 Causes $s to be set to:
132
133 "Hello, world!\n"
134
136 Construction
137
138 new [ARGS...]
139 Class method. Return a new, unattached scalar handle. If any
140 arguments are given, they're sent to open().
141
142 open [SCALARREF]
143 Instance method. Open the scalar handle on a new scalar, pointed
144 to by SCALARREF. If no SCALARREF is given, a "private" scalar is
145 created to hold the file data.
146
147 Returns the self object on success, undefined on error.
148
149 opened
150 Instance method. Is the scalar handle opened on something?
151
152 close
153 Instance method. Disassociate the scalar handle from its underly‐
154 ing scalar. Done automatically on destroy.
155
156 Input and output
157
158 flush
159 Instance method. No-op, provided for OO compatibility.
160
161 getc
162 Instance method. Return the next character, or undef if none
163 remain.
164
165 getline
166 Instance method. Return the next line, or undef on end of string.
167 Can safely be called in an array context. Currently, lines are
168 delimited by "\n".
169
170 getlines
171 Instance method. Get all remaining lines. It will croak() if
172 accidentally called in a scalar context.
173
174 print ARGS...
175 Instance method. Print ARGS to the underlying scalar.
176
177 Warning: this continues to always cause a seek to the end of the
178 string, but if you perform seek()s and tell()s, it is still safer
179 to explicitly seek-to-end before subsequent print()s.
180
181 read BUF, NBYTES, [OFFSET]
182 Instance method. Read some bytes from the scalar. Returns the
183 number of bytes actually read, 0 on end-of-file, undef on error.
184
185 write BUF, NBYTES, [OFFSET]
186 Instance method. Write some bytes to the scalar.
187
188 sysread BUF, LEN, [OFFSET]
189 Instance method. Read some bytes from the scalar. Returns the
190 number of bytes actually read, 0 on end-of-file, undef on error.
191
192 syswrite BUF, NBYTES, [OFFSET]
193 Instance method. Write some bytes to the scalar.
194
195 Seeking/telling and other attributes
196
197 autoflush
198 Instance method. No-op, provided for OO compatibility.
199
200 binmode
201 Instance method. No-op, provided for OO compatibility.
202
203 clearerr
204 Instance method. Clear the error and EOF flags. A no-op.
205
206 eof Instance method. Are we at end of file?
207
208 seek OFFSET, WHENCE
209 Instance method. Seek to a given position in the stream.
210
211 sysseek OFFSET, WHENCE
212 Instance method. Identical to "seek OFFSET, WHENCE", q.v.
213
214 tell
215 Instance method. Return the current position in the stream, as a
216 numeric offset.
217
218 setpos POS
219 Instance method. Set the current position, using the opaque value
220 returned by "getpos()".
221
222 getpos
223 Instance method. Return the current position in the string, as an
224 opaque object.
225
226 sref
227 Instance method. Return a reference to the underlying scalar.
228
230 Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
231 support for "seek()", "tell()", and "eof()". Attempting to use these
232 functions with an IO::Scalar will not work prior to 5.005_57.
233 IO::Scalar will not have the relevant methods invoked; and even worse,
234 this kind of bug can lie dormant for a while. If you turn warnings on
235 (via $^W or "perl -w"), and you see something like this...
236
237 attempt to seek on unopened filehandle
238
239 ...then you are probably trying to use one of these functions on an
240 IO::Scalar with an old Perl. The remedy is to simply use the OO ver‐
241 sion; e.g.:
242
243 $SH->seek(0,0); ### GOOD: will work on any 5.005
244 seek($SH,0,0); ### WARNING: will only work on 5.005_57 and beyond
245
247 $Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
248
250 Primary Maintainer
251
252 David F. Skoll (dfs@roaringpenguin.com).
253
254 Principal author
255
256 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc
257 (http://www.zeegee.com).
258
259 Other contributors
260
261 The full set of contributors always includes the folks mentioned in
262 "CHANGE LOG" in IO::Stringy. But just the same, special thanks to the
263 following individuals for their invaluable contributions (if I've for‐
264 gotten or misspelled your name, please email me!):
265
266 Andy Glew, for contributing "getc()".
267
268 Brandon Browning, for suggesting "opened()".
269
270 David Richter, for finding and fixing the bug in "PRINTF()".
271
272 Eric L. Brine, for his offset-using read() and write() implementations.
273
274 Richard Jones, for his patches to massively improve the performance of
275 "getline()" and add "sysread" and "syswrite".
276
277 B. K. Oxley (binkley), for stringification and inheritance improve‐
278 ments, and sundry good ideas.
279
280 Doug Wilson, for the IO::Handle inheritance and automatic tie-ing.
281
283 IO::String, which is quite similar but which was designed more-recently
284 and with an IO::Handle-like interface in mind, so you could mix OO- and
285 native-filehandle usage without using tied().
286
287 Note: as of version 2.x, these classes all work like their IO::Handle
288 counterparts, so we have comparable functionality to IO::String.
289
290
291
292perl v5.8.8 2005-02-10 IO::Scalar(3)