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 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

PUBLIC INTERFACE

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

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 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

VERSION

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

AUTHORS

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