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.