1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "IO::Scalar 3"
132 .TH IO::Scalar 3 "2005-02-10" "perl v5.8.7" "User Contributed Perl Documentation"
134 IO::Scalar \- IO:: interface for reading/writing a scalar
136 .IX Header "SYNOPSIS"
137 Perform I/O on strings, using the basic \s-1OO\s0 interface...
142 \& $data = "My message:\en";
146 \& ### Open a handle on a string, and append to it:
147 \& $SH = new IO::Scalar \e$data;
148 \& $SH\->print("Hello");
149 \& $SH\->print(", world!\enBye now!\en");
150 \& print "The string is now: ", $data, "\en";
154 \& ### Open a handle on a string, read it line\-by\-line, then close it:
155 \& $SH = new IO::Scalar \e$data;
156 \& while (defined($_ = $SH\->getline)) {
157 \& print "Got line: $_";
163 \& ### Open a handle on a string, and slurp in all the lines:
164 \& $SH = new IO::Scalar \e$data;
165 \& print "All lines:\en", $SH\->getlines;
169 \& ### Get the current position (either of two ways):
170 \& $pos = $SH\->getpos;
171 \& $offset = $SH\->tell;
175 \& ### Set the current position (either of two ways):
176 \& $SH\->setpos($pos);
177 \& $SH\->seek($offset, 0);
181 \& ### Open an anonymous temporary scalar:
182 \& $SH = new IO::Scalar;
183 \& $SH\->print("Hi there!");
184 \& print "I printed: ", ${$SH\->sref}, "\en"; ### get at value
187 Don't like \s-1OO\s0 for your I/O? No problem.
188 Thanks to the magic of an invisible \fItie()\fR, the following now
189 works out of the box, just as it does with IO::Handle:
194 \& $data = "My message:\en";
198 \& ### Open a handle on a string, and append to it:
199 \& $SH = new IO::Scalar \e$data;
200 \& print $SH "Hello";
201 \& print $SH ", world!\enBye now!\en";
202 \& print "The string is now: ", $data, "\en";
206 \& ### Open a handle on a string, read it line\-by\-line, then close it:
207 \& $SH = new IO::Scalar \e$data;
209 \& print "Got line: $_";
215 \& ### Open a handle on a string, and slurp in all the lines:
216 \& $SH = new IO::Scalar \e$data;
217 \& print "All lines:\en", <$SH>;
221 \& ### Get the current position (WARNING: requires 5.6):
222 \& $offset = tell $SH;
226 \& ### Set the current position (WARNING: requires 5.6):
227 \& seek $SH, $offset, 0;
231 \& ### Open an anonymous temporary scalar:
232 \& $SH = new IO::Scalar;
233 \& print $SH "Hi there!";
234 \& print "I printed: ", ${$SH\->sref}, "\en"; ### get at value
237 And for you folks with 1.x code out there: the old \fItie()\fR style still works,
238 though this is \fIunnecessary and deprecated\fR:
245 \& ### Writing to a scalar...
247 \& tie *OUT, 'IO::Scalar', \e$s;
248 \& print OUT "line 1\enline 2\en", "line 3\en";
249 \& print "String is now: $s\en"
253 \& ### Reading and writing an anonymous scalar...
254 \& tie *OUT, 'IO::Scalar';
255 \& print OUT "line 1\enline 2\en", "line 3\en";
256 \& tied(OUT)\->seek(0,0);
258 \& print "Got line: ", $_;
262 Stringification works, too!
265 \& my $SH = new IO::Scalar \e$data;
266 \& print $SH "Hello, ";
267 \& print $SH "world!";
268 \& print "I printed: $SH\en";
271 .IX Header "DESCRIPTION"
272 This class is part of the IO::Stringy distribution;
273 see IO::Stringy for change log and general information.
275 The IO::Scalar class implements objects which behave just like
276 IO::Handle (or FileHandle) objects, except that you may use them
277 to write to (or read from) scalars. These handles are
278 automatically tiehandle'd (though please see \*(L"\s-1WARNINGS\s0\*(R"
279 for information relevant to your Perl version).
285 \& $SH = new IO::Scalar \e$s;
286 \& $SH\->print("Hel", "lo, "); ### OO style
287 \& $SH\->print("world!\en"); ### ditto
294 \& $SH = tie *OUT, 'IO::Scalar', \e$s;
295 \& print OUT "Hel", "lo, "; ### non\-OO style
296 \& print OUT "world!\en"; ### ditto
299 Causes \f(CW$s\fR to be set to:
302 \& "Hello, world!\en"
304 .SH "PUBLIC INTERFACE"
305 .IX Header "PUBLIC INTERFACE"
307 .IX Subsection "Construction"
308 .IP "new [\s-1ARGS\s0...]" 4
309 .IX Item "new [ARGS...]"
310 \&\fIClass method.\fR
311 Return a new, unattached scalar handle.
312 If any arguments are given, they're sent to \fIopen()\fR.
313 .IP "open [\s-1SCALARREF\s0]" 4
314 .IX Item "open [SCALARREF]"
315 \&\fIInstance method.\fR
316 Open the scalar handle on a new scalar, pointed to by \s-1SCALARREF\s0.
317 If no \s-1SCALARREF\s0 is given, a \*(L"private\*(R" scalar is created to hold
320 Returns the self object on success, undefined on error.
323 \&\fIInstance method.\fR
324 Is the scalar handle opened on something?
327 \&\fIInstance method.\fR
328 Disassociate the scalar handle from its underlying scalar.
329 Done automatically on destroy.
330 .Sh "Input and output"
331 .IX Subsection "Input and output"
334 \&\fIInstance method.\fR
335 No\-op, provided for \s-1OO\s0 compatibility.
338 \&\fIInstance method.\fR
339 Return the next character, or undef if none remain.
342 \&\fIInstance method.\fR
343 Return the next line, or undef on end of string.
344 Can safely be called in an array context.
345 Currently, lines are delimited by \*(L"\en\*(R".
348 \&\fIInstance method.\fR
349 Get all remaining lines.
350 It will \fIcroak()\fR if accidentally called in a scalar context.
351 .IP "print \s-1ARGS\s0..." 4
352 .IX Item "print ARGS..."
353 \&\fIInstance method.\fR
354 Print \s-1ARGS\s0 to the underlying scalar.
356 \&\fBWarning:\fR this continues to always cause a seek to the end
357 of the string, but if you perform \fIseek()\fRs and \fItell()\fRs, it is
358 still safer to explicitly seek-to-end before subsequent \fIprint()\fRs.
359 .IP "read \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
360 .IX Item "read BUF, NBYTES, [OFFSET]"
361 \&\fIInstance method.\fR
362 Read some bytes from the scalar.
363 Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
364 .IP "write \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
365 .IX Item "write BUF, NBYTES, [OFFSET]"
366 \&\fIInstance method.\fR
367 Write some bytes to the scalar.
368 .IP "sysread \s-1BUF\s0, \s-1LEN\s0, [\s-1OFFSET\s0]" 4
369 .IX Item "sysread BUF, LEN, [OFFSET]"
370 \&\fIInstance method.\fR
371 Read some bytes from the scalar.
372 Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
373 .IP "syswrite \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
374 .IX Item "syswrite BUF, NBYTES, [OFFSET]"
375 \&\fIInstance method.\fR
376 Write some bytes to the scalar.
377 .Sh "Seeking/telling and other attributes"
378 .IX Subsection "Seeking/telling and other attributes"
381 \&\fIInstance method.\fR
382 No\-op, provided for \s-1OO\s0 compatibility.
385 \&\fIInstance method.\fR
386 No\-op, provided for \s-1OO\s0 compatibility.
389 \&\fIInstance method.\fR Clear the error and \s-1EOF\s0 flags. A no\-op.
392 \&\fIInstance method.\fR Are we at end of file?
393 .IP "seek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
394 .IX Item "seek OFFSET, WHENCE"
395 \&\fIInstance method.\fR Seek to a given position in the stream.
396 .IP "sysseek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
397 .IX Item "sysseek OFFSET, WHENCE"
398 \&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR
401 \&\fIInstance method.\fR
402 Return the current position in the stream, as a numeric offset.
403 .IP "setpos \s-1POS\s0" 4
404 .IX Item "setpos POS"
405 \&\fIInstance method.\fR
406 Set the current position, using the opaque value returned by \f(CW\*(C`getpos()\*(C'\fR.
409 \&\fIInstance method.\fR
410 Return the current position in the string, as an opaque object.
413 \&\fIInstance method.\fR
414 Return a reference to the underlying scalar.
416 .IX Header "WARNINGS"
417 Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
418 it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
419 Attempting to use these functions with an IO::Scalar will not work
420 prior to 5.005_57. IO::Scalar will not have the relevant methods
421 invoked; and even worse, this kind of bug can lie dormant for a while.
422 If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
423 and you see something like this...
426 \& attempt to seek on unopened filehandle
429 \&...then you are probably trying to use one of these functions
430 on an IO::Scalar with an old Perl. The remedy is to simply
431 use the \s-1OO\s0 version; e.g.:
434 \& $SH\->seek(0,0); ### GOOD: will work on any 5.005
435 \& seek($SH,0,0); ### WARNING: will only work on 5.005_57 and beyond
439 $Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
442 .Sh "Primary Maintainer"
443 .IX Subsection "Primary Maintainer"
444 David F. Skoll (\fIdfs@roaringpenguin.com\fR).
445 .Sh "Principal author"
446 .IX Subsection "Principal author"
447 Eryq (\fIeryq@zeegee.com\fR).
448 President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
449 .Sh "Other contributors"
450 .IX Subsection "Other contributors"
451 The full set of contributors always includes the folks mentioned
452 in \*(L"\s-1CHANGE\s0 \s-1LOG\s0\*(R" in IO::Stringy. But just the same, special
453 thanks to the following individuals for their invaluable contributions
454 (if I've forgotten or misspelled your name, please email me!):
457 for contributing \f(CW\*(C`getc()\*(C'\fR.
459 \&\fIBrandon Browning,\fR
460 for suggesting \f(CW\*(C`opened()\*(C'\fR.
462 \&\fIDavid Richter,\fR
463 for finding and fixing the bug in \f(CW\*(C`PRINTF()\*(C'\fR.
465 \&\fIEric L. Brine,\fR
466 for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
468 \&\fIRichard Jones,\fR
469 for his patches to massively improve the performance of \f(CW\*(C`getline()\*(C'\fR
470 and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR.
472 \&\fIB. K. Oxley (binkley),\fR
473 for stringification and inheritance improvements,
474 and sundry good ideas.
477 for the IO::Handle inheritance and automatic tie\-ing.
479 .IX Header "SEE ALSO"
480 IO::String, which is quite similar but which was designed
481 more-recently and with an IO::Handle\-like interface in mind,
482 so you could mix \s-1OO\-\s0 and native-filehandle usage without using \fItied()\fR.
484 \&\fINote:\fR as of version 2.x, these classes all work like
485 their IO::Handle counterparts, so we have comparable
486 functionality to IO::String.