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

FreeBSD Manual Pages

  
 
  

home | help
Stream::Reader(3)     User Contributed Perl Documentation    Stream::Reader(3)

NAME
       Stream::Reader -	is a stream reader

SYNOPSIS
	 # Input stream	can be reference to TYPEGLOB or	SCALAR,	output stream
	 # can be the same types or undefined

	 # Constructor
	 $stream = Stream::Reader->new(	\*IN,
	   { Limit => $limit, BuffSize => $buffsize, Mode => 'UB' } );

	 # Reading all before delimiter	beginning from current position.
	 # Delimiter is	SCALAR or reference to array with many SCALAR's.
	 # Returns true	value on succesfull matching or	if end of stream
	 # expected at first time
	 $bool = $stream->readto( $delimiter,
	   { Out => \*OUT, Limit => $limit, Mode => 'AIE' } );

	 # Reading fixed number	of chars beginning from	current	position.
	 # Returns true	value if was readed number of chars more then zero or
	 # end of stream was not expected yet
	 $bool = $stream->readsome( $limit, { Out => \*OUT, Mode => 'A'	} );

	 # Mode	is string, what	can contains:
	 #  U -	modificator for	constructor. disable utf-8 checking
	 #  B -	modificator for	constructor. enable second buffer for speed up
	 #	case insensitive search
	 #  A -	modificator for	readto() and readsome(). appending data	to
	 #	output stream, if stream is SCALAR
	 #  I -	modificator for	readto(). enable case insensitive search
	 #  E -	modificator for	readto(). at end of input stream alltimes
	 #	returns	false value

	 $number = $stream->{Total};  #	total number of	readed chars
	 $number = $stream->{Readed}; #	number of readed chars at last
				      #	operation (without matched string
				      #	length at readto() method)
	 $number = $stream->{Stored}; #	number of succesfully stored chars
				      #	at last	operation
	 $string = $stream->{Match};  #	matched	string at last operation
				      #	(actually for readto() only)
	 $bool	 = $stream->{Error};  #	error status. true on error

DESCRIPTION
       This is utility intended	for reading data from streams. Can be used for
       "on the fly" parsing big	volumes	data.

METHODS
       OBJ = Stream::Reader->new( INPUT, { ... Params ... } )
	   The constructor method instantiates a new Stream::Reader object.

	   INPUT - is a	reference to file stream, opened for reading, or
	   reference to	defined	string.	This is	an obligatory parameter.

	   Params (all optionaly):

	     Limit - limit size	of input stream	data in	characters. If this
	     parameter is absent, not defined or less then zero, then all data
	     from input	stream will be available for reading.

	     BuffSize -	size of	buffer in characters. If this parameter	is
	     absent, not defined or less then zero, then will be used default
	     buffer size 32768 characters.

	     Mode - is string with letters-modificators:

	       B - use second buffer. Can really speed up search in case
	       insensitive mode.

	       U - disable UTF-8 data check in UTF-8 mode. Use this flag if
	       you are absolutely sure,	that your UTF-8	data is	valid.

       RESULT =	OBJ->readto( DELIMITER,	{ ... Params ... } )
	   This	method reads all data from input stream	before first found
	   delimiter, beginning	from current position.

	   RESULT - boolean value. True	value if successfuly found delimeter
	   or and of input stream has expected at first	time. False value
	   otherwise, or in case of reading error.

	   DELIMETER - is a string-delimeter or	reference to array with	many
	   delimeters. This is an obligatory parameter and must	be defined.

	   Remember! In	case of	many delimiters, left delimiter	alltimes have
	   more	priority then right!

	   Params (all optionaly):

	     Out - is a	reference to file stream, opened for writing, or
	     reference to string. If this parameter is absent then data	will
	     not stored.

	     Limit - size in characters. Defines, the maximum number of
	     characters	that must be stored in Out. If this paramter is
	     absent, not defined or less then zero, then this method will be
	     trying to store all readed	data.

	     Mode - is string with letters-modificators:

	       A - appendig data to Out	if Out is a reference to string.

	       I - search in case insensitive mode.

	       E - at the end of input stream returns only false value.
	       Without this modificator, if end	of stream expected at first
	       time, then will be returned true	value.

       RESULT =	OBJ->readsome( LIMIT, {	... Params ... } )
	   This	method reads fixed number of characters	from input stream
	   beginning from current position.

	   RESULT - boolean value. True	value, if any characters were read or
	   end of input	stream is not expected yet. False value	otherwise, or
	   in case of reading error.

	   LIMIT - limit size in characters, how many it is necessary to read.
	   If this parameter is	absent,	not defined or less then zero, then
	   will	be read	all available data from	input stream.

	   Params (all optionaly):

	     Out - the same as in readto() method.

	     Mode - is string with letters-modificators:

	       A - the same as in readto() method.

       Statistics:
	   OBJ->{Total}	- total	number of readed characters. Warning! This
	   module using	block reading and real position	in stream is
	   different.

	   OBJ->{Readed} - number of readed characters at last operation
	   (without matched string length at readto() method).

	   OBJ->{Stored} - number of succesfully stored	chars at last
	   operation

	   OBJ->{Match}	- matched string at last operation (actually for
	   readto() only)

	   OBJ->{Error}	- boolen error status. At any reading erorrs all
	   operations will be stopes and this flag turned to true value.

UTF-8 SUPPORT
       Fully supported when using perl version 5.8.1, or higher. Input stream,
       output stream and delimiters should be in UTF-8 mode. If, during
       reading data from input stream in UTF-8 mode, will be detected
       malformed data, then will be stoped any operations and status Error
       turned to true value.

WARNINGS
       Remember! This class is using block reading and before destruct class-
       object, you should work with input stream only through these class
       methods.

       In UTF-8	mode search without case sensitive is very slowly..  It	is
       because operation of changing case on UTF-8 data	has slow speed.

       Remember, in UTF-8 mode all sizes of this module	contain	characters,
       not bytes!

EXAMPLES
       o   Please visit	catalogue examples/ in this module distribution.

       o   Good	example	is module PCGI

CREDITS
       Special thanks to:

       o   Andrey Fimushkin, <plohaja@mail.ru>

AUTHOR
       Andrian Zubko aka Ondr, <ondr@cpan.org>

perl v5.32.0			  2005-05-07		     Stream::Reader(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | UTF-8 SUPPORT | WARNINGS | EXAMPLES | CREDITS | AUTHOR

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

home | help