.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Scalar 3pm"
.TH IO::Scalar 3pm "2005-02-10" "perl v5.12.4" "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\s0\*(R"
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 "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\s0, \s-1NBYTES\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\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
.IX Item "write BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.IP "sysread \s-1BUF\s0, \s-1LEN\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\s0, \s-1NBYTES\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\s0, \s-1WHENCE\s0" 4
.IX Item "seek OFFSET, WHENCE"
\&\fIInstance method.\fR  Seek to a given position in the stream.
.IP "sysseek \s-1OFFSET\s0, \s-1WHENCE\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"
David F. 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\s0 \s-1LOG\s0\*(R" 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.