NAME
IO::Scalar - IO:: interface for reading/writing a scalar
SYNOPSIS
Perform I/O on strings, using the basic OO interface...
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
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:
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
And for you folks with 1.x code out there: the old tie() style still works, though this is unnecessary and deprecated:
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: ", $_;
}
Stringification works, too!
my $SH = new IO::Scalar \$data;
print $SH "Hello, ";
print $SH "world!";
print "I printed: $SH\n";
DESCRIPTION
This class is part of the IO::Stringy distribution; see IO::Stringy for change log and general information.
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 "WARNINGS" for information relevant to your Perl version).
Basically, this:
my $s;
$SH = new IO::Scalar \$s;
$SH->print("Hel", "lo, "); ### OO style
$SH->print("world!\n"); ### ditto
Or this:
my $s;
$SH = tie *OUT, 'IO::Scalar', \$s;
print OUT "Hel", "lo, "; ### non-OO style
print OUT "world!\n"; ### ditto
Causes $s to be set to:
"Hello, world!\n"
PUBLIC INTERFACE
Construction
- new [ARGS...]
-
Class method. Return a new, unattached scalar handle. If any arguments are given, they're sent to open().
- open [SCALARREF]
-
Instance method. 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.
Returns the self object on success, undefined on error.
- opened
-
Instance method. Is the scalar handle opened on something?
- close
-
Instance method. Disassociate the scalar handle from its underlying scalar. Done automatically on destroy.
Input and output
- flush
-
Instance method. No-op, provided for OO compatibility.
- fileno
-
Instance method. No-op, returns undef
- getc
-
Instance method. Return the next character, or undef if none remain.
- getline
-
Instance method. Return the next line, or undef on end of string. Can safely be called in an array context. Currently, lines are delimited by "\n".
- getlines
-
Instance method. Get all remaining lines. It will croak() if accidentally called in a scalar context.
- print ARGS...
-
Instance method. Print ARGS to the underlying scalar.
Warning: 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.
- read BUF, NBYTES, [OFFSET]
-
Instance method. Read some bytes from the scalar. Returns the number of bytes actually read, 0 on end-of-file, undef on error.
- write BUF, NBYTES, [OFFSET]
-
Instance method. Write some bytes to the scalar.
- sysread BUF, LEN, [OFFSET]
-
Instance method. Read some bytes from the scalar. Returns the number of bytes actually read, 0 on end-of-file, undef on error.
- syswrite BUF, NBYTES, [OFFSET]
-
Instance method. Write some bytes to the scalar.
Seeking/telling and other attributes
- autoflush
-
Instance method. No-op, provided for OO compatibility.
- binmode
-
Instance method. No-op, provided for OO compatibility.
- clearerr
-
Instance method. Clear the error and EOF flags. A no-op.
- eof
-
Instance method. Are we at end of file?
- seek OFFSET, WHENCE
-
Instance method. Seek to a given position in the stream.
- sysseek OFFSET, WHENCE
-
Instance method. Identical to
seek OFFSET, WHENCE
, q.v. - tell
-
Instance method. Return the current position in the stream, as a numeric offset.
- setpos POS
-
Instance method. Set the current position, using the opaque value returned by
getpos()
. - getpos
-
Instance method. Return the current position in the string, as an opaque object.
- sref
-
Instance method. Return a reference to the underlying scalar.
AUTHOR
Eryq ([email protected]). President, ZeeGee Software Inc (http://www.zeegee.com).
CONTRIBUTORS
Dianne Skoll ([email protected]).
COPYRIGHT & LICENSE
Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.