Stream::Reader 0.09

Stream::Reader is a stream reader Perl class.

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 SCALARs.
# 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

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.