NAME

Data::Transform::Block - translate data between streams and blocks

SYNOPSIS

#!perl

use warnings;
use strict;
use Data::Transform::Block;

my $filter = Data::Transform::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

Data::Transform::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.

METHODS

Data::Transform::Block implements the Data::Transform API. Only differences and additions are documented here.

SEE ALSO

Please see Data::Transform 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.