Editing: IO::ScalarArray.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" 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" '' . ds C` . ds C' '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 >0, 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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "IO::ScalarArray 3" .TH IO::ScalarArray 3 "2020-01-17" "perl v5.26.3" "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::ScalarArray \- IO:: interface for reading/writing an array of scalars .SH "SYNOPSIS" .IX Header "SYNOPSIS" Perform I/O on strings, using the basic \s-1OO\s0 interface... .PP .Vb 2 \& use IO::ScalarArray; \& @data = ("My mes", "sage:\en"); \& \& ### Open a handle on an array, and append to it: \& $AH = new IO::ScalarArray \e@data; \& $AH\->print("Hello"); \& $AH\->print(", world!\enBye now!\en"); \& print "The array is now: ", @data, "\en"; \& \& ### Open a handle on an array, read it line\-by\-line, then close it: \& $AH = new IO::ScalarArray \e@data; \& while (defined($_ = $AH\->getline)) { \& print "Got line: $_"; \& } \& $AH\->close; \& \& ### Open a handle on an array, and slurp in all the lines: \& $AH = new IO::ScalarArray \e@data; \& print "All lines:\en", $AH\->getlines; \& \& ### Get the current position (either of two ways): \& $pos = $AH\->getpos; \& $offset = $AH\->tell; \& \& ### Set the current position (either of two ways): \& $AH\->setpos($pos); \& $AH\->seek($offset, 0); \& \& ### Open an anonymous temporary array: \& $AH = new IO::ScalarArray; \& $AH\->print("Hi there!"); \& print "I printed: ", @{$AH\->aref}, "\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 \fBtie()\fR, the following now works out of the box, just as it does with IO::Handle: .PP .Vb 2 \& use IO::ScalarArray; \& @data = ("My mes", "sage:\en"); \& \& ### Open a handle on an array, and append to it: \& $AH = new IO::ScalarArray \e@data; \& print $AH "Hello"; \& print $AH ", world!\enBye now!\en"; \& print "The array is now: ", @data, "\en"; \& \& ### Open a handle on a string, read it line\-by\-line, then close it: \& $AH = new IO::ScalarArray \e@data; \& while (<$AH>) { \& print "Got line: $_"; \& } \& close $AH; \& \& ### Open a handle on a string, and slurp in all the lines: \& $AH = new IO::ScalarArray \e@data; \& print "All lines:\en", <$AH>; \& \& ### Get the current position (WARNING: requires 5.6): \& $offset = tell $AH; \& \& ### Set the current position (WARNING: requires 5.6): \& seek $AH, $offset, 0; \& \& ### Open an anonymous temporary scalar: \& $AH = new IO::ScalarArray; \& print $AH "Hi there!"; \& print "I printed: ", @{$AH\->aref}, "\en"; ### get at value .Ve .PP And for you folks with 1.x code out there: the old \fBtie()\fR style still works, though this is \fIunnecessary and deprecated\fR: .PP .Vb 1 \& use IO::ScalarArray; \& \& ### Writing to a scalar... \& my @a; \& tie *OUT, \*(AqIO::ScalarArray\*(Aq, \e@a; \& print OUT "line 1\enline 2\en", "line 3\en"; \& print "Array is now: ", @a, "\en" \& \& ### Reading and writing an anonymous scalar... \& tie *OUT, \*(AqIO::ScalarArray\*(Aq; \& print OUT "line 1\enline 2\en", "line 3\en"; \& tied(OUT)\->seek(0,0); \& while (<OUT>) { \& print "Got line: ", $_; \& } .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::ScalarArray class implements objects which behave just like IO::Handle (or FileHandle) objects, except that you may use them to write to (or read from) arrays of scalars. Logically, an array of scalars defines an in-core \*(L"file\*(R" whose contents are the concatenation of the scalars in the array. The handles created by this class are automatically \f(CW\*(C`tiehandle\*(C'\fRd (though please see \*(L"\s-1WARNINGS\*(R"\s0 for information relevant to your Perl version). .PP For writing large amounts of data with individual \fBprint()\fR statements, this class is likely to be more efficient than IO::Scalar. .PP Basically, this: .PP .Vb 4 \& my @a; \& $AH = new IO::ScalarArray \e@a; \& $AH\->print("Hel", "lo, "); ### OO style \& $AH\->print("world!\en"); ### ditto .Ve .PP Or this: .PP .Vb 4 \& my @a; \& $AH = new IO::ScalarArray \e@a; \& print $AH "Hel", "lo, "; ### non\-OO style \& print $AH "world!\en"; ### ditto .Ve .PP Causes \f(CW@a\fR to be set to the following array of 3 strings: .PP .Vb 3 \& ( "Hel" , \& "lo, " , \& "world!\en" ) .Ve .PP See IO::Scalar and compare with this class. .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 array handle. If any arguments are given, they're sent to \fBopen()\fR. .IP "open [\s-1ARRAYREF\s0]" 4 .IX Item "open [ARRAYREF]" \&\fIInstance method.\fR Open the array handle on a new array, pointed to by \s-1ARRAYREF.\s0 If no \s-1ARRAYREF\s0 is given, a \*(L"private\*(R" array 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 array handle opened on something? .IP "close" 4 .IX Item "close" \&\fIInstance method.\fR Disassociate the array handle from its underlying array. 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 "fileno" 4 .IX Item "fileno" \&\fIInstance method.\fR No-op, returns undef .IP "getc" 4 .IX Item "getc" \&\fIInstance method.\fR Return the next character, or undef if none remain. This does a \fBread\fR\|(1), which is somewhat costly. .IP "getline" 4 .IX Item "getline" \&\fIInstance method.\fR Return the next line, or undef on end of data. 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 \fBcroak()\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 array. .Sp Currently, this always causes a \*(L"seek to the end of the array\*(R" and generates a new array entry. This may change in the future. .IP "read \s-1BUF, NBYTES,\s0 [\s-1OFFSET\s0];" 4 .IX Item "read BUF, NBYTES, [OFFSET];" \&\fIInstance method.\fR Read some bytes from the array. Returns the number of bytes actually read, 0 on end-of-file, undef on error. .IP "write \s-1BUF, NBYTES,\s0 [\s-1OFFSET\s0];" 4 .IX Item "write BUF, NBYTES, [OFFSET];" \&\fIInstance method.\fR Write some bytes into the array. .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-1POS,WHENCE\s0" 4 .IX Item "seek POS,WHENCE" \&\fIInstance method.\fR Seek to a given position in the stream. Only a \s-1WHENCE\s0 of 0 (\s-1SEEK_SET\s0) is supported. .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 Seek to a given position in the array, using the opaque \fBgetpos()\fR value. Don't expect this to be a number. .IP "getpos" 4 .IX Item "getpos" \&\fIInstance method.\fR Return the current position in the array, as an opaque value. Don't expect this to be a number. .IP "aref" 4 .IX Item "aref" \&\fIInstance method.\fR Return a reference to the underlying array. .SH "AUTHOR" .IX Header "AUTHOR" Eryq (\fIeryq@zeegee.com\fR). President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR). .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Dianne Skoll (\fIdfs@roaringpenguin.com\fR). .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Save
Back