GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STREAM::READER (3)

.ds Aq ’

NAME

Stream::Reader - is a stream reader

CONTENTS

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



DESCRIPTION

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

METHODS

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

<B>INPUTB> - is a reference to file stream, opened for reading, or reference to defined string. This is an obligatory parameter.

<B>Params (all optionaly):B>

  <B>LimitB> - 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.

<B>BuffSizeB> - 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.

<B>ModeB> - is string with letters-modificators:

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

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

 

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

<B>RESULTB> - 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.

<B>DELIMETERB> - 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!

<B>Params (all optionaly):B>

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

<B>LimitB> - 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.

<B>ModeB> - is string with letters-modificators:

<B>AB> - appendig data to Out if Out is a reference to string.

<B>IB> - search in case insensitive mode.

<B>EB> - 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.

 

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

<B>RESULTB> - 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.

<B>LIMITB> - 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.

<B>Params (all optionaly):B>

  <B>OutB> - the same as in readto() method.

<B>ModeB> - is string with letters-modificators:

<B>AB> - the same as in readto() method.

 

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

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

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

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

<B>OBJ->{Error}B> - 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>
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 STREAM::READER (3) 2005-05-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.