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.
new¶
By default,
new() creates an empty filter stack that behaves like
POE::Filter::Stream. It may be given optional parameters to initialize the
stack with an array of filters.
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 },
),
]
);
pop¶
Behaves like Perl's built-in
pop() for the filter stack. The
highest-indexed filter is removed from the stack and returned. Any data
remaining in the filter's input buffer is lost, but an application may always
call "get_pending" in POE::Filter on the returned filter.
my $last_filter = $stackable->pop();
my $last_buffer = $last_filter->get_pending();
shift¶
Behaves like Perl's built-in
shift() for the filter stack. The 0th filter
is removed from the stack and returned. Any data remaining in the filter's
input buffer is passed to the new head of the stack, or it is lost if the
stack becomes empty. An application may also call "get_pending" in
POE::Filter on the returned filter to examine the filter's input buffer.
my $first_filter = $stackable->shift();
my $first_buffer = $first_filter->get_pending();
push FILTER[, FILTER]¶
push() adds one or more new FILTERs to the end of the stack. The newly
pushed FILTERs will process input last, and they will handle output first.
# 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]; $_ },
)
);
unshift FILTER[, FILTER]¶
unshift() adds one or more new FILTERs to the beginning of the stack. The
newly unshifted FILTERs will process input first, and they will handle output
last.
filters¶
filters() returns a list of the filters inside the Stackable filter, in
the stack's native order.
Calling "<$filter_stack-"
filters()>> in the
"SYNOPSIS" would return a list of two filter objects:
POE::Filter::Line=ARRAY(0x8b5ee0)
POE::Filter::Grep=ARRAY(0x8b5f7c)
filter_types¶
filter_types() returns a list of class names for each filter in the
stack, in the stack's native order.
Calling "<$filter_stack-"
filter_types()>> in the
"SYNOPSIS" would return a list of two class names:
POE::FIlter::Line
POE::Filter::Grep
It could easily be replaced by:
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.