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

FreeBSD Manual Pages

  
 
  

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

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.

perl v5.32.0			  2020-01-17			 IO::Scalar(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::Scalar&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help