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

AUTHOR

230       Eryq (eryq@zeegee.com).  President, ZeeGee Software Inc
231       (http://www.zeegee.com).
232

CONTRIBUTORS

234       Dianne Skoll (dfs@roaringpenguin.com).
235

237       Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All
238       rights reserved.
239
240       This program is free software; you can redistribute it and/or modify it
241       under the same terms as Perl itself.
242
243
244
245perl v5.36.0                      2023-01-20                     IO::Scalar(3)
Impressum