IO::Scalar(3pm)

1IO::Scalar(3)         User Contributed Perl Documentation        IO::Scalar(3)
2
3
4

NAME

6       IO::Scalar - IO:: interface for reading/writing a scalar
7

SYNOPSIS

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

DESCRIPTION

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
112       IO::Handle (or FileHandle) objects, except that you may use them to
113       write to (or read from) scalars.  These handles are automatically
114       tiehandle'd (though please see "WARNINGS" for information relevant to
115       your Perl 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

PUBLIC INTERFACE

136   Construction
137       new [ARGS...]
138           Class method.  Return a new, unattached scalar handle.  If any
139           arguments are given, they're sent to open().
140
141       open [SCALARREF]
142           Instance method.  Open the scalar handle on a new scalar, pointed
143           to by SCALARREF.  If no SCALARREF is given, a "private" scalar is
144           created to hold the file data.
145
146           Returns the self object on success, undefined on error.
147
148       opened
149           Instance method.  Is the scalar handle opened on something?
150
151       close
152           Instance method.  Disassociate the scalar handle from its
153           underlying scalar.  Done automatically on destroy.
154
155   Input and output
156       flush
157           Instance method.  No-op, provided for OO compatibility.
158
159       getc
160           Instance method.  Return the next character, or undef if none
161           remain.
162
163       getline
164           Instance method.  Return the next line, or undef on end of string.
165           Can safely be called in an array context.  Currently, lines are
166           delimited by "\n".
167
168       getlines
169           Instance method.  Get all remaining lines.  It will croak() if
170           accidentally called in a scalar context.
171
172       print ARGS...
173           Instance method.  Print ARGS to the underlying scalar.
174
175           Warning: this continues to always cause a seek to the end of the
176           string, but if you perform seek()s and tell()s, it is still safer
177           to explicitly seek-to-end before subsequent print()s.
178
179       read BUF, NBYTES, [OFFSET]
180           Instance method.  Read some bytes from the scalar.  Returns the
181           number of bytes actually read, 0 on end-of-file, undef on error.
182
183       write BUF, NBYTES, [OFFSET]
184           Instance method.  Write some bytes to the scalar.
185
186       sysread BUF, LEN, [OFFSET]
187           Instance method.  Read some bytes from the scalar.  Returns the
188           number of bytes actually read, 0 on end-of-file, undef on error.
189
190       syswrite BUF, NBYTES, [OFFSET]
191           Instance method.  Write some bytes to the scalar.
192
193   Seeking/telling and other attributes
194       autoflush
195           Instance method.  No-op, provided for OO compatibility.
196
197       binmode
198           Instance method.  No-op, provided for OO compatibility.
199
200       clearerr
201           Instance method.  Clear the error and EOF flags.  A no-op.
202
203       eof Instance method.  Are we at end of file?
204
205       seek OFFSET, WHENCE
206           Instance method.  Seek to a given position in the stream.
207
208       sysseek OFFSET, WHENCE
209           Instance method. Identical to "seek OFFSET, WHENCE", q.v.
210
211       tell
212           Instance method.  Return the current position in the stream, as a
213           numeric offset.
214
215       setpos POS
216           Instance method.  Set the current position, using the opaque value
217           returned by "getpos()".
218
219       getpos
220           Instance method.  Return the current position in the string, as an
221           opaque object.
222
223       sref
224           Instance method.  Return a reference to the underlying scalar.
225

WARNINGS

227       Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
228       support for "seek()", "tell()", and "eof()".  Attempting to use these
229       functions with an IO::Scalar will not work prior to 5.005_57.
230       IO::Scalar will not have the relevant methods invoked; and even worse,
231       this kind of bug can lie dormant for a while.  If you turn warnings on
232       (via $^W or "perl -w"), and you see something like this...
233
234           attempt to seek on unopened filehandle
235
236       ...then you are probably trying to use one of these functions on an
237       IO::Scalar with an old Perl.  The remedy is to simply use the OO
238       version; e.g.:
239
240           $SH->seek(0,0);    ### GOOD: will work on any 5.005
241           seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
242

VERSION

244       $Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
245

AUTHORS

247   Primary Maintainer
248       David F. Skoll (dfs@roaringpenguin.com).
249
250   Principal author
251       Eryq (eryq@zeegee.com).  President, ZeeGee Software Inc
252       (http://www.zeegee.com).
253
254   Other contributors
255       The full set of contributors always includes the folks mentioned in
256       "CHANGE LOG" in IO::Stringy.  But just the same, special thanks to the
257       following individuals for their invaluable contributions (if I've
258       forgotten or misspelled your name, please email me!):
259
260       Andy Glew, for contributing "getc()".
261
262       Brandon Browning, for suggesting "opened()".
263
264       David Richter, for finding and fixing the bug in "PRINTF()".
265
266       Eric L. Brine, for his offset-using read() and write() implementations.
267
268       Richard Jones, for his patches to massively improve the performance of
269       "getline()" and add "sysread" and "syswrite".
270
271       B. K. Oxley (binkley), for stringification and inheritance
272       improvements, and sundry good ideas.
273
274       Doug Wilson, for the IO::Handle inheritance and automatic tie-ing.
275