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       fileno
160           Instance method.  No-op, returns undef
161
162       getc
163           Instance method.  Return the next character, or undef if none
164           remain.
165
166       getline
167           Instance method.  Return the next line, or undef on end of string.
168           Can safely be called in an array context.  Currently, lines are
169           delimited by "\n".
170
171       getlines
172           Instance method.  Get all remaining lines.  It will croak() if
173           accidentally called in a scalar context.
174
175       print ARGS...
176           Instance method.  Print ARGS to the underlying scalar.
177
178           Warning: this continues to always cause a seek to the end of the
179           string, but if you perform seek()s and tell()s, it is still safer
180           to explicitly seek-to-end before subsequent print()s.
181
182       read BUF, NBYTES, [OFFSET]
183           Instance method.  Read some bytes from the scalar.  Returns the
184           number of bytes actually read, 0 on end-of-file, undef on error.
185
186       write BUF, NBYTES, [OFFSET]
187           Instance method.  Write some bytes to the scalar.
188
189       sysread BUF, LEN, [OFFSET]
190           Instance method.  Read some bytes from the scalar.  Returns the
191           number of bytes actually read, 0 on end-of-file, undef on error.
192
193       syswrite BUF, NBYTES, [OFFSET]
194           Instance method.  Write some bytes to the scalar.
195
196   Seeking/telling and other attributes
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

WARNINGS

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
241       version; 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

VERSION

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

AUTHORS

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