524 lines
12 KiB
HTML
524 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of IO::Scalar</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>IO::Scalar</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-02-28<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
IO::Scalar - IO:: interface for reading/writing a scalar
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
Perform I/O on strings, using the basic <FONT SIZE="-1">OO</FONT> interface...
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use 5.005;
|
|
use IO::Scalar;
|
|
$data = "My message:\n";
|
|
|
|
### Open a handle on a string, and append to it:
|
|
$SH = new IO::Scalar \$data;
|
|
$SH->print("Hello");
|
|
$SH->print(", world!\nBye now!\n");
|
|
print "The string is now: ", $data, "\n";
|
|
|
|
### Open a handle on a string, read it line-by-line, then close it:
|
|
$SH = new IO::Scalar \$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 \$data;
|
|
print "All lines:\n", $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}, "\n"; ### get at value
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Don't like <FONT SIZE="-1">OO</FONT> for your I/O? No problem.
|
|
Thanks to the magic of an invisible <B>tie()</B>, the following now
|
|
works out of the box, just as it does with IO::Handle:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use 5.005;
|
|
use IO::Scalar;
|
|
$data = "My message:\n";
|
|
|
|
### Open a handle on a string, and append to it:
|
|
$SH = new IO::Scalar \$data;
|
|
print $SH "Hello";
|
|
print $SH ", world!\nBye now!\n";
|
|
print "The string is now: ", $data, "\n";
|
|
|
|
### Open a handle on a string, read it line-by-line, then close it:
|
|
$SH = new IO::Scalar \$data;
|
|
while (<$SH>) {
|
|
print "Got line: $_";
|
|
}
|
|
close $SH;
|
|
|
|
### Open a handle on a string, and slurp in all the lines:
|
|
$SH = new IO::Scalar \$data;
|
|
print "All lines:\n", <$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}, "\n"; ### get at value
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And for you folks with 1.x code out there: the old <B>tie()</B> style still works,
|
|
though this is <I>unnecessary and deprecated</I>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use IO::Scalar;
|
|
|
|
### Writing to a scalar...
|
|
my $s;
|
|
tie *OUT, 'IO::Scalar', \$s;
|
|
print OUT "line 1\nline 2\n", "line 3\n";
|
|
print "String is now: $s\n"
|
|
|
|
### Reading and writing an anonymous scalar...
|
|
tie *OUT, 'IO::Scalar';
|
|
print OUT "line 1\nline 2\n", "line 3\n";
|
|
tied(OUT)->seek(0,0);
|
|
while (<OUT>) {
|
|
print "Got line: ", $_;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Stringification works, too!
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $SH = new IO::Scalar \$data;
|
|
print $SH "Hello, ";
|
|
print $SH "world!";
|
|
print "I printed: $SH\n";
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This class is part of the IO::Stringy distribution;
|
|
see IO::Stringy for change log and general information.
|
|
<P>
|
|
|
|
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 ``<FONT SIZE="-1">WARNINGS''</FONT>
|
|
for information relevant to your Perl version).
|
|
<P>
|
|
|
|
Basically, this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $s;
|
|
$SH = new IO::Scalar \$s;
|
|
$SH->print("Hel", "lo, "); ### OO style
|
|
$SH->print("world!\n"); ### ditto
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Or this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $s;
|
|
$SH = tie *OUT, 'IO::Scalar', \$s;
|
|
print OUT "Hel", "lo, "; ### non-OO style
|
|
print OUT "world!\n"; ### ditto
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Causes <TT>$s</TT> to be set to:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
"Hello, world!\n"
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>PUBLIC INTERFACE</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Construction</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">new [<FONT SIZE="-1">ARGS...</FONT>]<DD>
|
|
|
|
|
|
<I>Class method.</I>
|
|
Return a new, unattached scalar handle.
|
|
If any arguments are given, they're sent to <B>open()</B>.
|
|
<DT id="2">open [<FONT SIZE="-1">SCALARREF</FONT>]<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Open the scalar handle on a new scalar, pointed to by <FONT SIZE="-1">SCALARREF.</FONT>
|
|
If no <FONT SIZE="-1">SCALARREF</FONT> is given, a ``private'' scalar is created to hold
|
|
the file data.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Returns the self object on success, undefined on error.
|
|
<DT id="3">opened<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Is the scalar handle opened on something?
|
|
<DT id="4">close<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Disassociate the scalar handle from its underlying scalar.
|
|
Done automatically on destroy.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Input and output</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="5">flush<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
No-op, provided for <FONT SIZE="-1">OO</FONT> compatibility.
|
|
<DT id="6">fileno<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
No-op, returns undef
|
|
<DT id="7">getc<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Return the next character, or undef if none remain.
|
|
<DT id="8">getline<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Return the next line, or undef on end of string.
|
|
Can safely be called in an array context.
|
|
Currently, lines are delimited by ``\n''.
|
|
<DT id="9">getlines<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Get all remaining lines.
|
|
It will <B>croak()</B> if accidentally called in a scalar context.
|
|
<DT id="10">print <FONT SIZE="-1">ARGS...</FONT><DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Print <FONT SIZE="-1">ARGS</FONT> to the underlying scalar.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>Warning:</B> this continues to always cause a seek to the end
|
|
of the string, but if you perform <B>seek()</B>s and <B>tell()</B>s, it is
|
|
still safer to explicitly seek-to-end before subsequent <B>print()</B>s.
|
|
<DT id="11">read <FONT SIZE="-1">BUF, NBYTES,</FONT> [<FONT SIZE="-1">OFFSET</FONT>]<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Read some bytes from the scalar.
|
|
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
|
|
<DT id="12">write <FONT SIZE="-1">BUF, NBYTES,</FONT> [<FONT SIZE="-1">OFFSET</FONT>]<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Write some bytes to the scalar.
|
|
<DT id="13">sysread <FONT SIZE="-1">BUF, LEN,</FONT> [<FONT SIZE="-1">OFFSET</FONT>]<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Read some bytes from the scalar.
|
|
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
|
|
<DT id="14">syswrite <FONT SIZE="-1">BUF, NBYTES,</FONT> [<FONT SIZE="-1">OFFSET</FONT>]<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Write some bytes to the scalar.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Seeking/telling and other attributes</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="15">autoflush<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
No-op, provided for <FONT SIZE="-1">OO</FONT> compatibility.
|
|
<DT id="16">binmode<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
No-op, provided for <FONT SIZE="-1">OO</FONT> compatibility.
|
|
<DT id="17">clearerr<DD>
|
|
|
|
|
|
<I>Instance method.</I> Clear the error and <FONT SIZE="-1">EOF</FONT> flags. A no-op.
|
|
<DT id="18">eof<DD>
|
|
|
|
|
|
<I>Instance method.</I> Are we at end of file?
|
|
<DT id="19">seek <FONT SIZE="-1">OFFSET, WHENCE</FONT><DD>
|
|
|
|
|
|
<I>Instance method.</I> Seek to a given position in the stream.
|
|
<DT id="20">sysseek <FONT SIZE="-1">OFFSET, WHENCE</FONT><DD>
|
|
|
|
|
|
<I>Instance method.</I> Identical to <TT>"seek OFFSET, WHENCE"</TT>, <I>q.v.</I>
|
|
<DT id="21">tell<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Return the current position in the stream, as a numeric offset.
|
|
<DT id="22">setpos <FONT SIZE="-1">POS</FONT><DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Set the current position, using the opaque value returned by <TT>"getpos()"</TT>.
|
|
<DT id="23">getpos<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Return the current position in the string, as an opaque object.
|
|
<DT id="24">sref<DD>
|
|
|
|
|
|
<I>Instance method.</I>
|
|
Return a reference to the underlying scalar.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>WARNINGS</H2>
|
|
|
|
|
|
|
|
Perl's <FONT SIZE="-1">TIEHANDLE</FONT> spec was incomplete prior to 5.005_57;
|
|
it was missing support for <TT>"seek()"</TT>, <TT>"tell()"</TT>, and <TT>"eof()"</TT>.
|
|
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 <TT>$^W</TT> or <TT>"perl -w"</TT>),
|
|
and you see something like this...
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
attempt to seek on unopened filehandle
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
...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 <FONT SIZE="-1">OO</FONT> version; e.g.:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$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
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
<TT>$Id:</TT> Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Primary Maintainer</H3>
|
|
|
|
|
|
|
|
Dianne Skoll (<I><A HREF="mailto:dfs@roaringpenguin.com">dfs@roaringpenguin.com</A></I>).
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Principal author</H3>
|
|
|
|
|
|
|
|
Eryq (<I><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></I>).
|
|
President, ZeeGee Software Inc (<I><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></I>).
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Other contributors</H3>
|
|
|
|
|
|
|
|
The full set of contributors always includes the folks mentioned
|
|
in ``<FONT SIZE="-1">CHANGE LOG''</FONT> 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!):
|
|
<P>
|
|
|
|
<I>Andy Glew,</I>
|
|
for contributing <TT>"getc()"</TT>.
|
|
<P>
|
|
|
|
<I>Brandon Browning,</I>
|
|
for suggesting <TT>"opened()"</TT>.
|
|
<P>
|
|
|
|
<I>David Richter,</I>
|
|
for finding and fixing the bug in <TT>"PRINTF()"</TT>.
|
|
<P>
|
|
|
|
<I>Eric L. Brine,</I>
|
|
for his offset-using <B>read()</B> and <B>write()</B> implementations.
|
|
<P>
|
|
|
|
<I>Richard Jones,</I>
|
|
for his patches to massively improve the performance of <TT>"getline()"</TT>
|
|
and add <TT>"sysread"</TT> and <TT>"syswrite"</TT>.
|
|
<P>
|
|
|
|
<I>B. K. Oxley (binkley),</I>
|
|
for stringification and inheritance improvements,
|
|
and sundry good ideas.
|
|
<P>
|
|
|
|
<I>Doug Wilson,</I>
|
|
for the IO::Handle inheritance and automatic tie-ing.
|
|
<A NAME="lbAO"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
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 <FONT SIZE="-1">OO-</FONT> and native-filehandle usage without using <B>tied()</B>.
|
|
<P>
|
|
|
|
<I>Note:</I> as of version 2.x, these classes all work like
|
|
their IO::Handle counterparts, so we have comparable
|
|
functionality to IO::String.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="25"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="26"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="27"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="28"><A HREF="#lbAE">PUBLIC INTERFACE</A><DD>
|
|
<DL>
|
|
<DT id="29"><A HREF="#lbAF">Construction</A><DD>
|
|
<DT id="30"><A HREF="#lbAG">Input and output</A><DD>
|
|
<DT id="31"><A HREF="#lbAH">Seeking/telling and other attributes</A><DD>
|
|
</DL>
|
|
<DT id="32"><A HREF="#lbAI">WARNINGS</A><DD>
|
|
<DT id="33"><A HREF="#lbAJ">VERSION</A><DD>
|
|
<DT id="34"><A HREF="#lbAK">AUTHORS</A><DD>
|
|
<DL>
|
|
<DT id="35"><A HREF="#lbAL">Primary Maintainer</A><DD>
|
|
<DT id="36"><A HREF="#lbAM">Principal author</A><DD>
|
|
<DT id="37"><A HREF="#lbAN">Other contributors</A><DD>
|
|
</DL>
|
|
<DT id="38"><A HREF="#lbAO">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|