---
name: "POE::Filter::Line"
section: "3pm"
platform: "linux"
package: "perl-poe"
version: "1.370-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/POE::Filter::Line"
---

# POE::Filter::Line(3pm)

serialize and parse terminated records (lines)

## 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.