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.