# perldoc > POE::Filter::Block

## NAME
    [POE::Filter::Block](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABlock/markdown) - translate data between streams and blocks

## SYNOPSIS
      #!perl

      use warnings;
      use strict;
      use [POE::Filter::Block](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABlock/markdown);

      my $filter = [POE::Filter::Block](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABlock/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABlock/markdown) 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)](https://www.chedong.com/phpMan.php/man/chr/0/markdown) 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 in a framing buffer. To
    control memory usage, a maximum framing buffer size is imposed. This maximum size defaults to
    512 MB (512*1024*1024 octets). You may change this size limit with the "MaxBuffer" parameter.

        MaxBuffer => 1099511627776  # One terabyte!

    The size of each individual block is also limited. By default, each block may be no more then 64
    MB. You may change this size limit with the "MaxLength" parameter.

        MaxLength => 10             # small blocks

    Remember that MaxBuffer needs to be larger then MaxLength. What's more, it needs to have room
    for the length prefix.

    If either the "MaxLength" or "MaxBuffer" constraint is exceeded, "[POE::Filter::Bock](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABock/markdown)" will throw
    an exception.

## PUBLIC FILTER METHODS
    [POE::Filter::Block](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ABlock/markdown) has no additional public methods.

## SEE ALSO
    Please see [POE::Filter](https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter/markdown) 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.