NAME

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

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):

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):

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):

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

WARNINGS

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

• Please visit catalogue examples/ in this module distribution.
• Good example is module PCGI

CREDITS

•

Andrey Fimushkin, <plohaja@mail.ru>

AUTHOR