# POE::Filter::Line - phpMan

## NAME
    [POE::Filter::Line] - serialize and parse terminated records (lines)

## SYNOPSIS
      #!perl

      use POE qw([Wheel::FollowTail] [Filter::Line]);

      [POE::Session]->create(
        inline_states => {
          _start => sub {
            $_[HEAP]{tailor} = [POE::Wheel::FollowTail]->new(
              Filename => "/var/log/system.log",
              InputEvent => "got_log_line",
              Filter => [POE::Filter::Line]->new(),
            );
          },
          got_log_line => sub {
            print "Log: $_[ARG0]\n";
          }
        }
      );

      [POE::Kernel]->run();
      exit;

## DESCRIPTION
    [POE::Filter::Line] parses stream data into terminated records. The
    default parser interprets newlines as the record terminator, and the
    default serializer appends network newlines (CR/LF, or "\x0D\x0A") to
    outbound records.

    Record terminators are removed from the data [POE::Filter::Line] returns.

    [POE::Filter::Line] supports a number of other ways to parse lines.
    Constructor parameters may specify literal newlines, regular
    expressions, or that the filter should detect newlines on its own.

## PUBLIC FILTER METHODS
    [POE::Filter::Line]'s new() method has some interesting parameters.

  new
    new() accepts a list of named parameters.

    In all cases, the data interpreted as the record terminator is stripped
    from the data [POE::Filter::Line] returns.

    "InputLiteral" may be used to parse records that are terminated by some
    literal string. For example, [POE::Filter::Line] may be used to parse and
    emit C-style lines, which are terminated with an ASCII NUL:

      my $c_line_filter = [POE::Filter::Line]->new(
        InputLiteral => [chr(0)],
        OutputLiteral => [chr(0)],
      );

    "OutputLiteral" allows a filter to put() records with a different record
    terminator than it parses. This can be useful in applications that must
    translate record terminators.

    "Literal" is a shorthand for the common case where the input and output
    literals are identical. The previous example may be written as:

      my $c_line_filter = [POE::Filter::Line]->new(
        Literal => [chr(0)],
      );

    An application can also allow [POE::Filter::Line] to figure out which
    newline to use. This is done by specifying "InputLiteral" to be undef:

      my $whichever_line_filter = [POE::Filter::Line]->new(
        InputLiteral => undef,
        OutputLiteral => "\n",
      );

    "InputRegexp" may be used in place of "InputLiteral" to recognize line
    terminators based on a regular expression. In this example, input is
    terminated by two or more consecutive newlines. On output, the paragraph
    separator is "---" on a line by itself.

      my $paragraph_filter = [POE::Filter::Line]->new(
        InputRegexp => "([\x0D\x0A]{2,})",
        OutputLiteral => "\n---\n",
      );

    "MaxBuffer" sets the maximum amount of data that the filter will hold
    onto while trying to find a line ending. Defaults to 512 MB.

    "MaxLength" sets the maximum length of a line. Defaults to 64 MB.

    If either the "MaxLength" or "MaxBuffer" constraint is exceeded,
    "[POE::Filter::Line]" will throw an exception.

## PUBLIC FILTER METHODS
    [POE::Filter::Line] has no additional public methods.

## SUBCLASSING
    [POE::Filter::Line] exports the FIRST_UNUSED constant. This points to the
    first unused element in the $self array reference. Subclasses should
    store their own data beginning here, and they should export their own
    FIRST_UNUSED constants to help future subclassers.

## 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 default input newline parser is a regexp that has an unfortunate
    race condition. First the regular expression:

      /(\x0D\x0A?|\x0A\x0D?)/

    While it quickly recognizes most forms of newline, it can sometimes
    detect an extra blank line. This happens when a two-byte newline
    character is broken between two reads. Consider this situation:

      some stream dataCR
      LFother stream data

    The regular expression will see the first CR without its corresponding
    LF. The filter will properly return "some stream data" as a line. When
    the next packet arrives, the leading "LF" will be treated as the
    terminator for a 0-byte line. The filter will faithfully return this
    empty line.

    It is advised to specify literal newlines or use the autodetect feature
    in applications where blank lines are significant.

AUTHORS & COPYRIGHTS
    Please see POE for more information about authors and contributors.