NAME¶

POE::Filter::Stackable - combine multiple POE::Filter objects

SYNOPSIS¶

  #!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;

DESCRIPTION¶

POE::Filter::Stackable combines multiple filters together in such a way that they appear to be a single filter. All the usual POE::Filter methods work, but data is secretly passed through the stacked filters before it is returned. POE::Wheel objects and stand-alone programs need no modifications to work with a filter stack.

In the "SYNOPSIS", POE::Filter::Line and POE::Filter::Grep are combined into one filter that only returns a particular kind of line. This can be more efficient than filtering lines in application space, as fewer events may need to be dispatched and handled.

Internally, filters are stored in an array.

Data added by get_one_start() will flow through the filter array in increasing index order. Filter #0 will have first crack at it, followed by filter #1 and so. The get_one() call will return an item after it has passed through the last filter.

put() passes data through the filters in descending index order. Data will go through the filter with the highest index first, and put() will return the results after data has passed through filter #0.

PUBLIC FILTER METHODS¶

In addition to the usual POE::Filter methods, POE::Filter::Stackable also supports the following.

  my $sudo_lines = POE::Filter::Stackable->new(
    Filters => [
      POE::Filter::Line->new(),
      POE::Filter::Grep->new(
        Put => sub { 1 }, # put all items
        Get => sub { shift() =~ /sudo\[\d+\]/i },
      ),
    ]
  );

  my $last_filter = $stackable->pop();
  my $last_buffer = $last_filter->get_pending();

  my $first_filter = $stackable->shift();
  my $first_buffer = $first_filter->get_pending();

  # Reverse data read through the stack.
  # rot13 encode data sent through the stack.
  $stackable->push(
    POE::Filter::Map->(
      Get => sub { return scalar reverse shift() },
      Put => sub { local $_ = shift(); tr[a-zA-Z][n-za-mN-ZA-M]; $_ },
    )
  );

  POE::Filter::Line=ARRAY(0x8b5ee0)
  POE::Filter::Grep=ARRAY(0x8b5f7c)

  POE::FIlter::Line
  POE::Filter::Grep

  my @filter_types = map { ref } $filter_stack->filters;

SEE ALSO¶

POE::Filter for more information about filters in general.

Specific filters, amongst which are: POE::Filter::Block, POE::Filter::Grep, POE::Filter::HTTPD, POE::Filter::Line, POE::Filter::Map, POE::Filter::RecordBlock, POE::Filter::Reference, POE::Filter::Stream

BUGS¶

None currently known.

AUTHORS & COPYRIGHTS¶

The Stackable filter was contributed by Dieter Pearcey. Documentation provided by Rocco Caputo.

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