<HTML> <HEAD> <TITLE>IO::Scalar 2.105</TITLE> </HEAD> <BODY bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666"> <FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::Scalar 2.105</H1> </A><UL> <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A> <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A> <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A> <LI> <A NAME="menu:PUBLIC_INTERFACE"><A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A></A> <UL> <LI> <A NAME="menu:Construction"><A HREF="#Construction">Construction</A></A> <UL> <LI> <A NAME="menu:item:new_ARGS"><A HREF="#item:new_ARGS">new [ARGS...]</A></A> <LI> <A NAME="menu:item:open_SCALARREF"><A HREF="#item:open_SCALARREF">open [SCALARREF]</A></A> <LI> <A NAME="menu:item:opened"><A HREF="#item:opened">opened</A></A> <LI> <A NAME="menu:item:close"><A HREF="#item:close">close</A></A> </UL> <LI> <A NAME="menu:Input_and_output"><A HREF="#Input_and_output">Input and output</A></A> <UL> <LI> <A NAME="menu:item:flush"><A HREF="#item:flush">flush</A></A> <LI> <A NAME="menu:item:getc"><A HREF="#item:getc">getc</A></A> <LI> <A NAME="menu:item:getline"><A HREF="#item:getline">getline</A></A> <LI> <A NAME="menu:item:getlines"><A HREF="#item:getlines">getlines</A></A> <LI> <A NAME="menu:item:print_ARGS"><A HREF="#item:print_ARGS">print ARGS...</A></A> <LI> <A NAME="menu:item:read_BUF_NBYTES_OFFSET"><A HREF="#item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET]</A></A> <LI> <A NAME="menu:item:write_BUF_NBYTES_OFFSET"><A HREF="#item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET]</A></A> <LI> <A NAME="menu:item:sysread_BUF_LEN_OFFSET"><A HREF="#item:sysread_BUF_LEN_OFFSET">sysread BUF, LEN, [OFFSET]</A></A> <LI> <A NAME="menu:item:syswrite_BUF_NBYTES_OFFSET"><A HREF="#item:syswrite_BUF_NBYTES_OFFSET">syswrite BUF, NBYTES, [OFFSET]</A></A> </UL> <LI> <A NAME="menu:Seeking_telling_and_other_attributes"><A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A></A> <UL> <LI> <A NAME="menu:item:autoflush"><A HREF="#item:autoflush">autoflush</A></A> <LI> <A NAME="menu:item:binmode"><A HREF="#item:binmode">binmode</A></A> <LI> <A NAME="menu:item:clearerr"><A HREF="#item:clearerr">clearerr</A></A> <LI> <A NAME="menu:item:eof"><A HREF="#item:eof">eof</A></A> <LI> <A NAME="menu:item:seek_OFFSET_WHENCE"><A HREF="#item:seek_OFFSET_WHENCE">seek OFFSET, WHENCE</A></A> <LI> <A NAME="menu:item:sysseek_OFFSET_WHENCE"><A HREF="#item:sysseek_OFFSET_WHENCE">sysseek OFFSET, WHENCE</A></A> <LI> <A NAME="menu:item:tell"><A HREF="#item:tell">tell</A></A> <LI> <A NAME="menu:item:setpos_POS"><A HREF="#item:setpos_POS">setpos POS</A></A> <LI> <A NAME="menu:item:getpos"><A HREF="#item:getpos">getpos</A></A> <LI> <A NAME="menu:item:sref"><A HREF="#item:sref">sref</A></A> </UL> </UL> <LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A> <LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A> <LI> <A NAME="menu:AUTHORS"><A HREF="#AUTHORS">AUTHORS</A></A> <UL> <LI> <A NAME="menu:Principal_author"><A HREF="#Principal_author">Principal author</A></A> <LI> <A NAME="menu:Other_contributors"><A HREF="#Other_contributors">Other contributors</A></A> </UL> <LI> <A NAME="menu:SEE_ALSO"><A HREF="#SEE_ALSO">SEE ALSO</A></A> </UL> <P><HR> <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> <P>IO::Scalar - IO:: interface for reading/writing a scalar <P><HR> <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> <P>Perform I/O on strings, using the basic OO interface... <FONT SIZE=3 FACE="courier"><PRE> use 5.005; use IO::Scalar; $data = "My message:\n"; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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"; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Open a handle on a string, and slurp in all the lines: $SH = new IO::Scalar \$data; print "All lines:\n", $SH->getlines; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Get the current position (either of two ways): $pos = $SH->getpos; $offset = $SH->tell; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Set the current position (either of two ways): $SH->setpos($pos); $SH->seek($offset, 0); </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Open an anonymous temporary scalar: $SH = new IO::Scalar; $SH->print("Hi there!"); print "I printed: ", ${$SH->sref}, "\n"; ### get at value </PRE></FONT> <P>Don't like OO for your I/O? No problem. Thanks to the magic of an invisible tie(), the following now works out of the box, just as it does with IO::Handle: <FONT SIZE=3 FACE="courier"><PRE> use 5.005; use IO::Scalar; $data = "My message:\n"; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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"; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Open a handle on a string, and slurp in all the lines: $SH = new IO::Scalar \$data; print "All lines:\n", <$SH>; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Get the current position (WARNING: requires 5.6): $offset = tell $SH; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Set the current position (WARNING: requires 5.6): seek $SH, $offset, 0; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### Open an anonymous temporary scalar: $SH = new IO::Scalar; print $SH "Hi there!"; print "I printed: ", ${$SH->sref}, "\n"; ### get at value </PRE></FONT> <P>And for you folks with 1.x code out there: the old tie() style still works, though this is <I>unnecessary and deprecated</I>: <FONT SIZE=3 FACE="courier"><PRE> use IO::Scalar; </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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" </PRE></FONT> <FONT SIZE=3 FACE="courier"><PRE> ### 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></FONT> <P>Stringification works, too! <FONT SIZE=3 FACE="courier"><PRE> my $SH = new IO::Scalar \$data; print $SH "Hello, "; print $SH "world!"; print "I printed: $SH\n"; </PRE></FONT> <P><HR> <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> <P>This class is part of the IO::Stringy distribution; see <A HREF="../IO/Stringy.pm.html">IO::Stringy</A> 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 <A HREF="#WARNINGS">WARNINGS</A> for information relevant to your Perl version). <P>Basically, this: <FONT SIZE=3 FACE="courier"><PRE> my $s; $SH = new IO::Scalar \$s; $SH->print("Hel", "lo, "); ### OO style $SH->print("world!\n"); ### ditto </PRE></FONT> <P>Or this: <FONT SIZE=3 FACE="courier"><PRE> my $s; $SH = tie *OUT, 'IO::Scalar', \$s; print OUT "Hel", "lo, "; ### non-OO style print OUT "world!\n"; ### ditto </PRE></FONT> <P>Causes $s to be set to: <FONT SIZE=3 FACE="courier"><PRE> "Hello, world!\n" </PRE></FONT> <P><HR> <A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> <P><HR> <A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A> <DL> <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:new"><A NAME="item:new_ARGS">new [ARGS...]</A></A></B></DT> <DD> <I>Class method.</I> Return a new, unattached scalar handle. If any arguments are given, they're sent to open(). <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:open"><A NAME="item:open_SCALARREF">open [SCALARREF]</A></A></B></DT> <DD> <I>Instance method.</I> Open the scalar handle on a new scalar, pointed to by SCALARREF. If no SCALARREF is given, a "private" scalar is created to hold the file data. <P>Returns the self object on success, undefined on error. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:opened">opened</A></B></DT> <DD> <I>Instance method.</I> Is the scalar handle opened on something? <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:close">close</A></B></DT> <DD> <I>Instance method.</I> Disassociate the scalar handle from its underlying scalar. Done automatically on destroy. </DL> <P><HR> <A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A> <DL> <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:flush">flush</A></B></DT> <DD> <I>Instance method.</I> No-op, provided for OO compatibility. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getc">getc</A></B></DT> <DD> <I>Instance method.</I> Return the next character, or undef if none remain. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getline">getline</A></B></DT> <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". <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getlines">getlines</A></B></DT> <DD> <I>Instance method.</I> Get all remaining lines. It will croak() if accidentally called in a scalar context. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:print"><A NAME="item:print_ARGS">print ARGS...</A></A></B></DT> <DD> <I>Instance method.</I> Print ARGS 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 seek()s and tell()s, it is still safer to explicitly seek-to-end before subsequent print()s. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:read"><A NAME="item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET]</A></A></B></DT> <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. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:write"><A NAME="item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET]</A></A></B></DT> <DD> <I>Instance method.</I> Write some bytes to the scalar. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:sysread"><A NAME="item:sysread_BUF_LEN_OFFSET">sysread BUF, LEN, [OFFSET]</A></A></B></DT> <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. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:syswrite"><A NAME="item:syswrite_BUF_NBYTES_OFFSET">syswrite BUF, NBYTES, [OFFSET]</A></A></B></DT> <DD> <I>Instance method.</I> Write some bytes to the scalar. </DL> <P><HR> <A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A> <DL> <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:autoflush">autoflush</A></B></DT> <DD> <I>Instance method.</I> No-op, provided for OO compatibility. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:binmode">binmode</A></B></DT> <DD> <I>Instance method.</I> No-op, provided for OO compatibility. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:clearerr">clearerr</A></B></DT> <DD> <I>Instance method.</I> Clear the error and EOF flags. A no-op. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:eof">eof</A></B></DT> <DD> <I>Instance method.</I> Are we at end of file? <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:seek"><A NAME="item:seek_OFFSET_WHENCE">seek OFFSET, WHENCE</A></A></B></DT> <DD> <I>Instance method.</I> Seek to a given position in the stream. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:sysseek"><A NAME="item:sysseek_OFFSET_WHENCE">sysseek OFFSET, WHENCE</A></A></B></DT> <DD> <I>Instance method.</I> Identical to <CODE>seek OFFSET, WHENCE</CODE>, <I>q.v.</I> <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tell">tell</A></B></DT> <DD> <I>Instance method.</I> Return the current position in the stream, as a numeric offset. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:setpos"><A NAME="item:setpos_POS">setpos POS</A></A></B></DT> <DD> <I>Instance method.</I> Set the current position, using the opaque value returned by <CODE>getpos()</CODE>. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getpos">getpos</A></B></DT> <DD> <I>Instance method.</I> Return the current position in the string, as an opaque object. <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:sref">sref</A></B></DT> <DD> <I>Instance method.</I> Return a reference to the underlying scalar. </DL> <P><HR> <A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A> <P>Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing support for <CODE>seek()</CODE>, <CODE>tell()</CODE>, and <CODE>eof()</CODE>. 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 <CODE>$^W</CODE> or <CODE>perl -w</CODE>), and you see something like this... <FONT SIZE=3 FACE="courier"><PRE> attempt to seek on unopened filehandle </PRE></FONT> <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 OO version; e.g.: <FONT SIZE=3 FACE="courier"><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></FONT> <P><HR> <A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> <P>$Id: Scalar.pm.html,v 1.1 2004/04/09 17:04:45 dasenbro Exp $ <P><HR> <A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A> <P><HR> <A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A> <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>). President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). <P><HR> <A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A> <P>The full set of contributors always includes the folks mentioned in <A HREF="../IO/Stringy.pm.html#CHANGE_LOG">CHANGE LOG</A>. 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 <CODE>getc()</CODE>. <P><I>Brandon Browning,</I> for suggesting <CODE>opened()</CODE>. <P><I>David Richter,</I> for finding and fixing the bug in <CODE>PRINTF()</CODE>. <P><I>Eric L. Brine,</I> for his offset-using read() and write() implementations. <P><I>Richard Jones,</I> for his patches to massively improve the performance of <CODE>getline()</CODE> and add <CODE>sysread</CODE> and <CODE>syswrite</CODE>. <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. <P><HR> <A NAME="SEE_ALSO"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SEE ALSO</H2></A> <P><A HREF="../IO/String.pm.html">IO::String</A>, which is quite similar but which was designed more-recently and with an IO::Handle-like interface in mind, so you could mix OO- and native-filehandle usage without using tied(). <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> <ADDRESS><FONT SIZE=-1> Generated Sun Dec 21 13:54:37 2003 by cvu_pod2html </FONT></ADDRESS> </FONT></BODY> </HTML>