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

💅 POE::F...r::Grep — like, the manual page bestie 💅

okay so. welcome to POE::F...r::Grep(3pm), from the User Contributed Perl Documentation section of the manual, and babes this one is a whole mood. it's giving "tiny filter, huge main character energy." let's get into it 🫶

---

✨ NAME ✨

POE::Filter::Grep — select or remove items based on simple rules. literally that's the whole job. it picks stuff or it yeets stuff. no cap.

---

🌸 SYNOPSIS 🌸

okay here's the vibe, and yes i'm pasting this exactly because it's code and code is sacred:

  #!perl

  use POE qw(
    Wheel::FollowTail
    Filter::Line Filter::Grep Filter::Stackable
  );

  POE::Session->create(
    inline_states => {
      _start => sub {
        my $parse_input_as_lines = POE::Filter::Line->new();

        my $select_sudo_log_lines = POE::Filter::Grep->new(
          Put => sub { 1 },
          Get => sub {
            my $input = shift;
            return $input =~ /sudo\[\d+\]/i;
          },
        );

        my $filter_stack = POE::Filter::Stackable->new(
          Filters => [
            $parse_input_as_lines, # first on get, last on put
            $select_sudo_log_lines, # first on put, last on get
          ]
        );

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

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

like… the way this little stack tails /var/log/system.log, splits it into lines, and then only keeps the sudo ones? obsessed. 💖

---

🦋 DESCRIPTION 🦋

POE::Filter::Grep selects or removes items based on simple tests. it can filter input, output, or both — dealer's choice, bestie, it's flexible like that. and yeah, it's named after and modeled after Perl's built-in grep() function, so if you already know grep() you're basically already fluent. iykyk.

it's designed to be combined with other filters through POE::Filter::Stackable. in the "SYNOPSIS" example up there, a filter stack gets created to parse logs as lines and then remove every entry that doesn't pertain to a sudo process. (or, if your glass is half full: the stack only selects entries that DO mention sudo. optimistic queen behavior 👑)

---

🌈 PUBLIC FILTER METHODS 🌈

so besides the usual POE::Filter methods, POE::Filter::Grep also supports these. yes ma'am. 💅

⭐ new

new() constructs a brand new POE::Filter::Grep object. and here's the rule, don't skip it: it must either be called with a single Code parameter, or both a Put and a Get parameter. no half-effort builds around here.

the values for Code, Put, and Get are code references that, when invoked, return true to select an item or false to reject it. a Code function gets used for both input and output, while Get and Put functions let input and output be filtered in different ways. and the item in question gets passed as the function's sole parameter. one arg, one job, periodt.

  sub reject_bidoofs {
    my $pokemon = shift;
    return 1 if $pokemon ne "bidoof";
    return;
  }

  my $gotta_catch_nearly_all = POE::Filter::Grep->new(
    Code => \&reject_bidoofs,
  );

"nearly all" because we're out here rejecting the bidoofs, obviously. 😭 iconic.

want to enforce read-only behavior? say less:

  my $read_only = POE::Filter::Grep->new(
    Get => sub { 1 },
    Put => sub { 0 },
  );

Get says yes to everything, Put says no to everything. the filter is now just a vibes-only observer. ✨

🎀 modify

modify() changes a POE::Filter::Grep object's behavior at run-time. it accepts the same parameters as new(), and it replaces the existing tests with new ones. glow-up, but for filters.

  # Don't give away our Dialgas.
  $gotta_catch_nearly_all->modify(
    Get => sub { 1 },
    Put => sub { return shift() ne "dialga" },
  );

we protect the Dialgas in this house. 🫡

---

👀 SEE ALSO 👀

• POE::Filter — for more information about filters in general.
• POE::Filter::Stackable — for more details on stacking filters.

---

💀 BUGS 💀

none known. not me checking twice. not a single one. slay.

---

🍓 AUTHORS & COPYRIGHTS 🍓

the Grep filter was contributed by Dieter Pearcey. documentation is provided by Rocco Caputo. thank you both, we love you fr fr. 🫶

please see the POE manpage for more information about authors and contributors.

---

and that's the whole page bestie!! this one came from the User Contributed Perl Documentation corner of the manual, tagged perl v5.34.0 and dated 2022-03-25 — so yeah, a little vintage, still absolutely eating. go filter something. 💖✨🎀🦋🌸💅