.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Scalar 3"
.TH IO::Scalar 3 "2015-04-22" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Scalar \- IO:: interface for reading/writing a scalar
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Perform I/O on strings, using the basic \s-1OO\s0 interface...
.PP
.Vb 3
\& use 5.005;
\& use IO::Scalar;
\& $data = "My message:\en";
\&
\& ### Open a handle on a string, and append to it:
\& $SH = new IO::Scalar \e$data;
\& $SH\->print("Hello");
\& $SH\->print(", world!\enBye now!\en");
\& print "The string is now: ", $data, "\en";
\&
\& ### Open a handle on a string, read it line\-by\-line, then close it:
\& $SH = new IO::Scalar \e$data;
\& while (defined($_ = $SH\->getline)) {
\& print "Got line: $_";
\& }
\& $SH\->close;
\&
\& ### Open a handle on a string, and slurp in all the lines:
\& $SH = new IO::Scalar \e$data;
\& print "All lines:\en", $SH\->getlines;
\&
\& ### Get the current position (either of two ways):
\& $pos = $SH\->getpos;
\& $offset = $SH\->tell;
\&
\& ### Set the current position (either of two ways):
\& $SH\->setpos($pos);
\& $SH\->seek($offset, 0);
\&
\& ### Open an anonymous temporary scalar:
\& $SH = new IO::Scalar;
\& $SH\->print("Hi there!");
\& print "I printed: ", ${$SH\->sref}, "\en"; ### get at value
.Ve
.PP
Don't like \s-1OO\s0 for your I/O? No problem.
Thanks to the magic of an invisible \fItie()\fR, the following now
works out of the box, just as it does with IO::Handle:
.PP
.Vb 3
\& use 5.005;
\& use IO::Scalar;
\& $data = "My message:\en";
\&
\& ### Open a handle on a string, and append to it:
\& $SH = new IO::Scalar \e$data;
\& print $SH "Hello";
\& print $SH ", world!\enBye now!\en";
\& print "The string is now: ", $data, "\en";
\&
\& ### Open a handle on a string, read it line\-by\-line, then close it:
\& $SH = new IO::Scalar \e$data;
\& while (<$SH>) {
\& print "Got line: $_";
\& }
\& close $SH;
\&
\& ### Open a handle on a string, and slurp in all the lines:
\& $SH = new IO::Scalar \e$data;
\& print "All lines:\en", <$SH>;
\&
\& ### Get the current position (WARNING: requires 5.6):
\& $offset = tell $SH;
\&
\& ### Set the current position (WARNING: requires 5.6):
\& seek $SH, $offset, 0;
\&
\& ### Open an anonymous temporary scalar:
\& $SH = new IO::Scalar;
\& print $SH "Hi there!";
\& print "I printed: ", ${$SH\->sref}, "\en"; ### get at value
.Ve
.PP
And for you folks with 1.x code out there: the old \fItie()\fR style still works,
though this is \fIunnecessary and deprecated\fR:
.PP
.Vb 1
\& use IO::Scalar;
\&
\& ### Writing to a scalar...
\& my $s;
\& tie *OUT, \*(AqIO::Scalar\*(Aq, \e$s;
\& print OUT "line 1\enline 2\en", "line 3\en";
\& print "String is now: $s\en"
\&
\& ### Reading and writing an anonymous scalar...
\& tie *OUT, \*(AqIO::Scalar\*(Aq;
\& print OUT "line 1\enline 2\en", "line 3\en";
\& tied(OUT)\->seek(0,0);
\& while (<OUT>) {
\& print "Got line: ", $_;
\& }
.Ve
.PP
Stringification works, too!
.PP
.Vb 4
\& my $SH = new IO::Scalar \e$data;
\& print $SH "Hello, ";
\& print $SH "world!";
\& print "I printed: $SH\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is part of the IO::Stringy distribution;
see IO::Stringy for change log and general information.
.PP
The IO::Scalar class implements objects which behave just like
IO::Handle (or FileHandle) objects, except that you may use them
to write to (or read from) scalars. These handles are
automatically tiehandle'd (though please see \*(L"\s-1WARNINGS\*(R"\s0
for information relevant to your Perl version).
.PP
Basically, this:
.PP
.Vb 4
\& my $s;
\& $SH = new IO::Scalar \e$s;
\& $SH\->print("Hel", "lo, "); ### OO style
\& $SH\->print("world!\en"); ### ditto
.Ve
.PP
Or this:
.PP
.Vb 4
\& my $s;
\& $SH = tie *OUT, \*(AqIO::Scalar\*(Aq, \e$s;
\& print OUT "Hel", "lo, "; ### non\-OO style
\& print OUT "world!\en"; ### ditto
.Ve
.PP
Causes \f(CW$s\fR to be set to:
.PP
.Vb 1
\& "Hello, world!\en"
.Ve
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "Construction"
.IX Subsection "Construction"
.IP "new [\s-1ARGS...\s0]" 4
.IX Item "new [ARGS...]"
\&\fIClass method.\fR
Return a new, unattached scalar handle.
If any arguments are given, they're sent to \fIopen()\fR.
.IP "open [\s-1SCALARREF\s0]" 4
.IX Item "open [SCALARREF]"
\&\fIInstance method.\fR
Open the scalar handle on a new scalar, pointed to by \s-1SCALARREF.\s0
If no \s-1SCALARREF\s0 is given, a \*(L"private\*(R" scalar is created to hold
the file data.
.Sp
Returns the self object on success, undefined on error.
.IP "opened" 4
.IX Item "opened"
\&\fIInstance method.\fR
Is the scalar handle opened on something?
.IP "close" 4
.IX Item "close"
\&\fIInstance method.\fR
Disassociate the scalar handle from its underlying scalar.
Done automatically on destroy.
.SS "Input and output"
.IX Subsection "Input and output"
.IP "flush" 4
.IX Item "flush"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "fileno" 4
.IX Item "fileno"
\&\fIInstance method.\fR
No-op, returns undef
.IP "getc" 4
.IX Item "getc"
\&\fIInstance method.\fR
Return the next character, or undef if none remain.
.IP "getline" 4
.IX Item "getline"
\&\fIInstance method.\fR
Return the next line, or undef on end of string.
Can safely be called in an array context.
Currently, lines are delimited by \*(L"\en\*(R".
.IP "getlines" 4
.IX Item "getlines"
\&\fIInstance method.\fR
Get all remaining lines.
It will \fIcroak()\fR if accidentally called in a scalar context.
.IP "print \s-1ARGS...\s0" 4
.IX Item "print ARGS..."
\&\fIInstance method.\fR
Print \s-1ARGS\s0 to the underlying scalar.
.Sp
\&\fBWarning:\fR this continues to always cause a seek to the end
of the string, but if you perform \fIseek()\fRs and \fItell()\fRs, it is
still safer to explicitly seek-to-end before subsequent \fIprint()\fRs.
.IP "read \s-1BUF, NBYTES,\s0 [\s-1OFFSET\s0]" 4
.IX Item "read BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
.IP "write \s-1BUF, NBYTES,\s0 [\s-1OFFSET\s0]" 4
.IX Item "write BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.IP "sysread \s-1BUF, LEN,\s0 [\s-1OFFSET\s0]" 4
.IX Item "sysread BUF, LEN, [OFFSET]"
\&\fIInstance method.\fR
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
.IP "syswrite \s-1BUF, NBYTES,\s0 [\s-1OFFSET\s0]" 4
.IX Item "syswrite BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.SS "Seeking/telling and other attributes"
.IX Subsection "Seeking/telling and other attributes"
.IP "autoflush" 4
.IX Item "autoflush"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "binmode" 4
.IX Item "binmode"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "clearerr" 4
.IX Item "clearerr"
\&\fIInstance method.\fR Clear the error and \s-1EOF\s0 flags. A no-op.
.IP "eof" 4
.IX Item "eof"
\&\fIInstance method.\fR Are we at end of file?
.IP "seek \s-1OFFSET, WHENCE\s0" 4
.IX Item "seek OFFSET, WHENCE"
\&\fIInstance method.\fR Seek to a given position in the stream.
.IP "sysseek \s-1OFFSET, WHENCE\s0" 4
.IX Item "sysseek OFFSET, WHENCE"
\&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR
.IP "tell" 4
.IX Item "tell"
\&\fIInstance method.\fR
Return the current position in the stream, as a numeric offset.
.IP "setpos \s-1POS\s0" 4
.IX Item "setpos POS"
\&\fIInstance method.\fR
Set the current position, using the opaque value returned by \f(CW\*(C`getpos()\*(C'\fR.
.IP "getpos" 4
.IX Item "getpos"
\&\fIInstance method.\fR
Return the current position in the string, as an opaque object.
.IP "sref" 4
.IX Item "sref"
\&\fIInstance method.\fR
Return a reference to the underlying scalar.
.SH "WARNINGS"
.IX Header "WARNINGS"
Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
Attempting to use these functions with an IO::Scalar will not work
prior to 5.005_57. IO::Scalar will not have the relevant methods
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
and you see something like this...
.PP
.Vb 1
\& attempt to seek on unopened filehandle
.Ve
.PP
\&...then you are probably trying to use one of these functions
on an IO::Scalar with an old Perl. The remedy is to simply
use the \s-1OO\s0 version; e.g.:
.PP
.Vb 2
\& $SH\->seek(0,0); ### GOOD: will work on any 5.005
\& seek($SH,0,0); ### WARNING: will only work on 5.005_57 and beyond
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
.SH "AUTHORS"
.IX Header "AUTHORS"
.SS "Primary Maintainer"
.IX Subsection "Primary Maintainer"
Dianne Skoll (\fIdfs@roaringpenguin.com\fR).
.SS "Principal author"
.IX Subsection "Principal author"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SS "Other contributors"
.IX Subsection "Other contributors"
The full set of contributors always includes the folks mentioned
in \*(L"\s-1CHANGE LOG\*(R"\s0 in IO::Stringy. But just the same, special
thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):
.PP
\&\fIAndy Glew,\fR
for contributing \f(CW\*(C`getc()\*(C'\fR.
.PP
\&\fIBrandon Browning,\fR
for suggesting \f(CW\*(C`opened()\*(C'\fR.
.PP
\&\fIDavid Richter,\fR
for finding and fixing the bug in \f(CW\*(C`PRINTF()\*(C'\fR.
.PP
\&\fIEric L. Brine,\fR
for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
.PP
\&\fIRichard Jones,\fR
for his patches to massively improve the performance of \f(CW\*(C`getline()\*(C'\fR
and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR.
.PP
\&\fIB. K. Oxley (binkley),\fR
for stringification and inheritance improvements,
and sundry good ideas.
.PP
\&\fIDoug Wilson,\fR
for the IO::Handle inheritance and automatic tie-ing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::String, which is quite similar but which was designed
more-recently and with an IO::Handle\-like interface in mind,
so you could mix \s-1OO\-\s0 and native-filehandle usage without using \fItied()\fR.
.PP
\&\fINote:\fR as of version 2.x, these classes all work like
their IO::Handle counterparts, so we have comparable
functionality to IO::String.