Stream::Reader - is a stream reader
# 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
This is utility intended for reading data from streams. Can be used for "on the fly" parsing big volumes data.
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.
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!
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.
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.
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.
Out - the same as in readto() method.
A - the same as in readto() method.
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.
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.
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!
Please visit catalogue examples/ in this module distribution.
Good example is module PCGI
Special thanks to:
Andrey Fimushkin, <plohaja@mail.ru>
Andrian Zubko aka Ondr, <ondr@cpan.org>
To install Stream::Reader, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Stream::Reader
CPAN shell
perl -MCPAN -e shell install Stream::Reader
For more information on module installation, please visit the detailed CPAN module installation guide.