/ 
IO-Buffered-1.00
River stage zero No dependents
/ IO::Buffered

NAME

IO::Buffered - A simple buffer class for dealing with different data types

SYNOPSIS

my $buf = new IO::Buffered(Split => qr/,/);
$buf->write("record1,reco")
$buf->write("rd2,record3");

my @records = $buf->read(); # @records is now ("record1", "record2")
@records = $buf->read_last(); # @records is now ("record3")

DESCRIPTION

IO::Buffered provides a simple unified way of dealing with buffering. This is done by providing a set of buffering types each with an understanding of what they are buffering. All buffering types share a common set of function for working with the buffer.

write($str,..)

write() appends more data to the buffer if the buffer type allows it. Different types might have rules that prohibit the buffer for growing over a certain limit or mandates that only certain types of data be written to the buffer.

In case of error the number of bytes written to the buffer is returned and the function croaks.

read($alt_size)

read() returns the number of ready records as defined by the buffer type or returns an empty array when no records are available. Read records will be cleared from the buffer. $alt_size defines alternative size of the next record in the buffer if the buffer type does not know how much data to buffer before returning the record. This is currently used by the HTTP buffer type when it is in HeaderOnly mode and needs to return the data part of a http request.

read_last()

read_last() returns the number of ready records as defined by the buffer type and the rest of the buffer as the last record. Or returns an empty array when no records are available. After read_last is called the buffer will be empty.

flush($str, ...)

flush() flushes the buffer if no input or replace the buffer with the input.

buffer()

buffer() returns a copy of the buffer.

returns_last()

returns_last() tells if the buffer type knows if it's dealing with a complete record or not. Or a call to <read_last()> is need to get all valid records. An example of this is the "Split" buffer type where record delimiter does not have to be at the end of every record:

my $buffer = new IO::Buffered::Split(qr/\n/);
$buffer->write("Hello\nHello");

if($buffer->returns_last) {
    my @records = $buffer->read(); # @records would be ('Hello')
} else {
    my @records = $buffer->read_last(); # @records is ('Hello', 'Hello')
}

BUFFER TYPES

Regexp

The Regexp buffer type takes a regular expression as input and splits records based on that. Only the match defined in the () is returned and not the complete match.

An example would be qr/^(.+)\n/ that would work as line buffing:

my $buf = IO::Buffered(Regexp => qr/^(.+)\n/);

Read more here: IO::Buffered::Regexp

Split

Split is special case of the Regexp buffer type and is in essence just /(.*?)$split/. Here only the non matching part of $split is returned.

An example would be qr/\n/ that also works as line buffering or qr/\0/ for C strings.

my $buf = IO::Buffered(Split => qr/\n/);

Read more here: IO::Buffered::Split

Size

The Size buffering type reads the size from the data to determine where record boundaries are. Only the data is returned not the bytes that hold the length information. Size buffering takes two arguments, a pack template and a offset for the numbers of bytes to add to the length that was unpacked with the template.

An example would be a template of "n" and a offset of 0 that could be used to handle DNS tcp requests. Offset defaults to 0 if not set.

my $buf = IO::Buffered(Size => ["n", 0]);

Read more here: IO::Buffered::Size

FixedSize

FixedSize buffering returns records in fixed size chunks.

An example would to return 100 bytes at a time:

my $buf = IO::Buffered(FixedSize => 100);

Read more here: IO::Buffered::FixedSize

Last

Last buffering simple only returns one record when read_last is called. All calls to read will return an empty array.

An example would be:

my $buf = IO::Buffered(Last => 1);

Read more here: IO::Buffered::Last

HTTP

HTTP buffering provides a simple buffering for HTTP traffic by looking for "Content-Length:" in the HTTP header. If one is found this will be used to split records. If not only the header will be returned.

An example would be:

my $buf = IO::Buffered(HTTP => 1);

Read more here: IO::Buffered::HTTP

GENERIC OPTIONS

MaxSize

MaxSize provides a limit on how big a buffer can grow, when the limit is hit an exception is thrown.

The default value for MaxSize is 0, meaning that there is no size limit on the buffer.

METHODS

new()

IO::Buffered simple provides a wrapper for the different buffering types. The argument given to the buffer type is simply given as first argument to the constructor of the buffer type, as show below:

$buf = Buffered::IO(Split => qr/\n/);

# is the same as

$buf = Buffered::IO::Split(qr/\n/);

Extra options are passed along as an array after first argument, as show below:

$buf = Buffered::IO(Split => qr/\n/, MaxSize => 1000_000);

# is the same as

$buf = Buffered::IO::Split(qr/\n/, MaxSize => 1000_000);

Buffered::IO recasts exceptions so there is no differences in using either interface.

recroak()

Helper function to rethrow croaks

AUTHOR

Troels Liebe Bentsen <tlb@rapanden.dk>

COPYRIGHT

Copyright(C) 2008 Troels Liebe Bentsen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.