-
-
17 Jan 2020 03:53:55 UTC
- Distribution: IO-Stringy
- Module version: 2.113
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues
- Testers (4885 / 0 / 0)
- Kwalitee
Bus factor: 3- 68.01% Coverage
- License: perl_5
- Perl: v5.8.0
- Activity
24 month- Tools
- Download (46.64KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
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 (eryq@zeegee.com). President, ZeeGee Software Inc (http://www.zeegee.com).
CONTRIBUTORS
Dianne Skoll (dfs@roaringpenguin.com).
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.
Module Install Instructions
To install IO::Stringy, copy and paste the appropriate command in to your terminal.
cpanm IO::Stringy
perl -MCPAN -e shell install IO::Stringy
For more information on module installation, please visit the detailed CPAN module installation guide.