NAME

POE::Filter::Line - filter data as lines

SYNOPSIS

  $filter = POE::Filter::Line->new();
  $arrayref_of_lines =
    $filter->get($arrayref_of_raw_chunks_from_driver);
  $arrayref_of_streamable_chunks_for_driver =
    $filter->put($arrayref_of_lines);
  $arrayref_of_leftovers =
    $filter->get_pending();

  # Use a literal newline terminator for input and output:
  $filter = POE::Filter::Line->new( Literal => "\x0D\x0A" );

  # Terminate input lines with a string regexp:
  $filter = POE::Filter::Line->new( InputRegexp   => '[!:]',
                                    OutputLiteral => "!"
                                  );

  # Terminate input lines with a compiled regexp (requires perl 5.005
  # or newer):
  $filter = POE::Filter::Line->new( InputRegexp   => qr/[!:]/,
                                    OutputLiteral => "!"
                                  );

  # Autodetect the input line terminator:
  $filter = POE::Filter::Line->new( InputLiteral => undef );

DESCRIPTION

The Line filter translates streams to and from separated lines. The lines it returns do not include the line separator (usually newlines). Neither should the lines given to it.

Incoming newlines are recognized with a simple regular expression by default: /(\x0D\x0A?|\x0A\x0D?)/. This regexp encompasses all the variations of CR and/or LF, but it has a race condition.

Consider a CRLF newline is broken into two stream chunks, one which ends with CR and the other which begins with LF:

   some stream dataCR
   LFother stream data

The default regexp will recognize the CR as one end-of-line marker and the LF as another. The line filter will emit two lines: "some stream data" and a blank line. People are advised to specify custom literal newlines or autodetect the newline style in applications where blank lines are significant.

Outgoing lines have traditional network newlines (CRLF) appended to them by default.

PUBLIC FILTER METHODS

Please see POE::Filter.

SEE ALSO

POE::Filter.

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

BUGS

The default input newline regexp has a race condition where incomplete newlines can generate spurious blank input lines.

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.