Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::ScalarArray(3)    User Contributed Perl Documentation   IO::ScalarArray(3)

NAME
       IO::ScalarArray - IO:: interface	for reading/writing an array of
       scalars

SYNOPSIS
       Perform I/O on strings, using the basic OO interface...

	   use IO::ScalarArray;
	   @data = ("My	mes", "sage:\n");

	   ### Open a handle on	an array, and append to	it:
	   $AH = new IO::ScalarArray \@data;
	   $AH->print("Hello");
	   $AH->print(", world!\nBye now!\n");
	   print "The array is now: ", @data, "\n";

	   ### Open a handle on	an array, read it line-by-line,	then close it:
	   $AH = new IO::ScalarArray \@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 \@data;
	   print "All lines:\n", $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}, "\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 IO::ScalarArray;
	   @data = ("My	mes", "sage:\n");

	   ### Open a handle on	an array, and append to	it:
	   $AH = new IO::ScalarArray \@data;
	   print $AH "Hello";
	   print $AH ",	world!\nBye now!\n";
	   print "The array is now: ", @data, "\n";

	   ### Open a handle on	a string, read it line-by-line,	then close it:
	   $AH = new IO::ScalarArray \@data;
	   while (<$AH>) {
	       print "Got line:	$_";
	   }
	   close $AH;

	   ### Open a handle on	a string, and slurp in all the lines:
	   $AH = new IO::ScalarArray \@data;
	   print "All lines:\n", <$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}, "\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::ScalarArray;

	   ### Writing to a scalar...
	   my @a;
	   tie *OUT, 'IO::ScalarArray',	\@a;
	   print OUT "line 1\nline 2\n", "line 3\n";
	   print "Array	is now:	", @a, "\n"

	   ### Reading and writing an anonymous	scalar...
	   tie *OUT, 'IO::ScalarArray';
	   print OUT "line 1\nline 2\n", "line 3\n";
	   tied(OUT)->seek(0,0);
	   while (<OUT>) {
	       print "Got line:	", $_;
	   }

DESCRIPTION
       This class is part of the IO::Stringy distribution; see IO::Stringy for
       change log and general information.

       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 "file" whose contents	are the	concatenation
       of the scalars in the array.  The handles created by this class are
       automatically "tiehandle"d (though please see "WARNINGS"	for
       information relevant to your Perl version).

       For writing large amounts of data with individual print() statements,
       this class is likely to be more efficient than IO::Scalar.

       Basically, this:

	   my @a;
	   $AH = new IO::ScalarArray \@a;
	   $AH->print("Hel", "lo, ");	      ### OO style
	   $AH->print("world!\n");	      ### ditto

       Or this:

	   my @a;
	   $AH = new IO::ScalarArray \@a;
	   print $AH "Hel", "lo, ";	      ### non-OO style
	   print $AH "world!\n";	      ### ditto

       Causes @a to be set to the following array of 3 strings:

	   ( "Hel" ,
	     "lo, " ,
	     "world!\n"	)

       See IO::Scalar and compare with this class.

PUBLIC INTERFACE
   Construction
       new [ARGS...]
	   Class method.  Return a new,	unattached array handle.  If any
	   arguments are given,	they're	sent to	open().

       open [ARRAYREF]
	   Instance method.  Open the array handle on a	new array, pointed to
	   by ARRAYREF.	 If no ARRAYREF	is given, a "private" array is created
	   to hold the file data.

	   Returns the self object on success, undefined on error.

       opened
	   Instance method.  Is	the array handle opened	on something?

       close
	   Instance method.  Disassociate the array handle from	its underlying
	   array.  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.  This does a	read(1), which is somewhat costly.

       getline
	   Instance method.  Return the	next line, or undef on end of data.
	   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 array.

	   Currently, this always causes a "seek to the	end of the array" and
	   generates a new array entry.	 This may change in the	future.

       read BUF, NBYTES, [OFFSET];
	   Instance method.  Read some bytes from the array.  Returns the
	   number of bytes actually read, 0 on end-of-file, undef on error.

       write BUF, NBYTES, [OFFSET];
	   Instance method.  Write some	bytes into the array.

   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 POS,WHENCE
	   Instance method.  Seek to a given position in the stream.  Only a
	   WHENCE of 0 (SEEK_SET) is supported.

       tell
	   Instance method.  Return the	current	position in the	stream,	as a
	   numeric offset.

       setpos POS
	   Instance method.  Seek to a given position in the array, using the
	   opaque getpos() value.  Don't expect	this to	be a number.

       getpos
	   Instance method.  Return the	current	position in the	array, as an
	   opaque value.  Don't	expect this to be a number.

       aref
	   Instance method.  Return a reference	to the underlying array.

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.

perl v5.32.0			  2020-01-17		    IO::ScalarArray(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC INTERFACE | AUTHOR | CONTRIBUTORS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::ScalarArray&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help