POE::F...r::Line(3pm)

🌸 NAME 🌸

POE::Filter::Line — bestie, this one serializes and parses terminated records, aka lines. That's the whole vibe. From the User Contributed Perl Documentation, this is the page for POE::F...r::Line(3pm) 💖

---

✨ 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 💅

okay so POE::Filter::Line parses stream data into terminated records. The default parser is like, newlines = the record terminator, periodt. And the default serializer appends network newlines (CR/LF, or "\x0D\x0A") to outbound records. No cap.

The record terminators get removed from the data POE::Filter::Line hands back to you, so don't go looking for them. 🫶

But wait, there's more — POE::Filter::Line supports a whole bunch of other ways to parse lines. Constructor parameters can specify literal newlines, regular expressions, or just let the filter detect newlines on its own. Iconic behaviour honestly. ✨

---

🎀 PUBLIC FILTER METHODS 🎀

POE::Filter::Line's new() method has some interesting parameters. Strap in.

🦋 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. Every single time. 💯

"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" lets a filter put() records with a different record terminator than the one it parses. Which is lowkey so useful in applications that must translate record terminators. 🔥

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

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

An application can also just let POE::Filter::Line figure out which newline to use. You do this 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. So like, don't test it for fun bestie, it WILL yell at you. 😭

---

💜 PUBLIC FILTER METHODS 💜

POE::Filter::Line has no additional public methods. That's it. That's the section. Short king energy. 👑

---

🧚 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. Pay it forward, babe. 🫶

---

🌈 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. Go explore, it's giving library. 📚

---

💀 BUGS 💀

okay so this is the part where we hold hands. 🤝

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. fr fr, don't get caught out.

---

👑 AUTHORS & COPYRIGHTS 👑

Please see POE for more information about authors and contributors.

---

aaaand that's the whole page bestie, you ate it 💅✨ this was the User Contributed Perl Documentation page POE::F...r::Line(3pm), from perl v5.34.0, dated 2022-03-25. go forth and parse some lines, ily 🎀🦋💖