NAME

       POE::Filter::Block - translate data between streams and blocks

SYNOPSIS

         #!perl

         use warnings;
         use strict;
         use POE::Filter::Block;

         my $filter = POE::Filter::Block->new( BlockSize => 8 );

         # Prints three lines: abcdefgh, ijklmnop, qrstuvwx.
         # Bytes "y" and "z" remain in the buffer and await completion of the
         # next 8-byte block.

         $filter->get_one_start([ "abcdefghijklmnopqrstuvwxyz" ]);
         while (1) {
           my $block = $filter->get_one();
           last unless @$block;
           print $block->[0], "\n";
         }

         # Print one line: yz123456

         $filter->get_one_start([ "123456" ]);
         while (1) {
           my $block = $filter->get_one();
           last unless @$block;
           print $block->[0], "\n";
         }

DESCRIPTION

       POE::Filter::Block translates data between serial streams and blocks.  It can handle
       fixed-length and length-prepended blocks, and it may be extended to handle other block
       types.

       Fixed-length blocks are used when Block's constructor is called with a BlockSize value.
       Otherwise the Block filter uses length-prepended blocks.

       Users who specify block sizes less than one deserve what they get.

       In variable-length mode, a LengthCodec parameter may be specified.  The LengthCodec value
       should be a reference to a list of two functions: the length encoder, and the length
       decoder:

         LengthCodec => [ \&encoder, \&decoder ]

       The encoder takes a reference to a buffer and prepends the buffer's length to it.  The
       default encoder prepends the ASCII representation of the buffer's length and a chr(0) byte
       to separate the length from the actual data:

         sub _default_encoder {
           my $stuff = shift;
           substr($$stuff, 0, 0) = length($$stuff) . "\0";
           return;
         }

       The corresponding decoder returns the block length after removing it and the separator
       from the buffer.  It returns nothing if no length can be determined.

         sub _default_decoder {
           my $stuff = shift;
           unless ($$stuff =~ s/^(\d+)\0//s) {
             warn length($1), " strange bytes removed from stream"
               if $$stuff =~ s/^(\D+)//s;
             return;
           }
           return $1;
         }

       This filter holds onto incomplete blocks until they are completed.

PUBLIC FILTER METHODS

       POE::Filter::Block has no additional public methods.

SEE ALSO

       Please see POE::Filter for documentation regarding the base interface.

       The SEE ALSO section in POE contains a table of contents covering the entire POE
       distribution.

BUGS

       The put() method doesn't verify block sizes.

AUTHORS & COPYRIGHTS

       The Block filter was contributed by Dieter Pearcey, with changes by Rocco Caputo.

       Please see POE for more information about authors and contributors.