1POE::Filter::Stackable(U3s)er Contributed Perl DocumentatPiOoEn::Filter::Stackable(3)
2
6 POE::Filter::Stackable - combine multiple POE::Filter objects
7
9 #!perl
10 use POE qw(
12 Wheel::FollowTail
13 Filter::Line Filter::Grep Filter::Stackable
14 );
15 POE::Session->create(
17 inline_states => {
18 _start => sub {
19 my $parse_input_as_lines = POE::Filter::Line->new();
20 my $select_sudo_log_lines = POE::Filter::Grep->new(
22 Put => sub { 1 },
23 Get => sub {
24 my $input = shift;
25 return $input =~ /sudo\[\d+\]/i;
26 },
27 );
28 my $filter_stack = POE::Filter::Stackable->new(
30 Filters => [
31 $parse_input_as_lines, # first on get, last on put
32 $select_sudo_log_lines, # first on put, last on get
33 ]
34 );
35 $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
37 Filename => "/var/log/system.log",
38 InputEvent => "got_log_line",
39 Filter => $filter_stack,
40 );
41 },
42 got_log_line => sub {
43 print "Log: $_[ARG0]\n";
44 }
45 }
46 );
47 POE::Kernel->run();
49 exit;
50
52 POE::Filter::Stackable combines multiple filters together in such a way
53 that they appear to be a single filter. All the usual POE::Filter
54 methods work, but data is secretly passed through the stacked filters
55 before it is returned. POE::Wheel objects and stand-alone programs
56 need no modifications to work with a filter stack.
57 In the "SYNOPSIS", POE::Filter::Line and POE::Filter::Grep are combined
59 into one filter that only returns a particular kind of line. This can
60 be more efficient than filtering lines in application space, as fewer
61 events may need to be dispatched and handled.
62 Internally, filters are stored in an array.
64 Data added by get_one_start() will flow through the filter array in
66 increasing index order. Filter #0 will have first crack at it,
67 followed by filter #1 and so. The get_one() call will return an item
68 after it has passed through the last filter.
69 put() passes data through the filters in descending index order. Data
71 will go through the filter with the highest index first, and put() will
72 return the results after data has passed through filter #0.
73
75 In addition to the usual POE::Filter methods, POE::Filter::Stackable
76 also supports the following.
77 new
79 By default, new() creates an empty filter stack that behaves like
80 POE::Filter::Stream. It may be given optional parameters to initialize
81 the stack with an array of filters.
82 my $sudo_lines = POE::Filter::Stackable->new(
84 Filters => [
85 POE::Filter::Line->new(),
86 POE::Filter::Grep->new(
87 Put => sub { 1 }, # put all items
88 Get => sub { shift() =~ /sudo\[\d+\]/i },
89 ),
90 ]
91 );
92 pop
94 Behaves like Perl's built-in pop() for the filter stack. The highest-
95 indexed filter is removed from the stack and returned. Any data
96 remaining in the filter's input buffer is lost, but an application may
97 always call "get_pending" in POE::Filter on the returned filter.
98 my $last_filter = $stackable->pop();
100 my $last_buffer = $last_filter->get_pending();
101 shift
103 Behaves like Perl's built-in shift() for the filter stack. The 0th
104 filter is removed from the stack and returned. Any data remaining in
105 the filter's input buffer is passed to the new head of the stack, or it
106 is lost if the stack becomes empty. An application may also call
107 "get_pending" in POE::Filter on the returned filter to examine the
108 filter's input buffer.
109 my $first_filter = $stackable->shift();
111 my $first_buffer = $first_filter->get_pending();
112 push FILTER[, FILTER]
114 push() adds one or more new FILTERs to the end of the stack. The newly
115 pushed FILTERs will process input last, and they will handle output
116 first.
117 # Reverse data read through the stack.
119 # rot13 encode data sent through the stack.
120 $stackable->push(
121 POE::Filter::Map->(
122 Get => sub { return scalar reverse shift() },
123 Put => sub { local $_ = shift(); tr[a-zA-Z][n-za-mN-ZA-M]; $_ },
124 )
125 );
126 unshift FILTER[, FILTER]
128 unshift() adds one or more new FILTERs to the beginning of the stack.
129 The newly unshifted FILTERs will process input first, and they will
130 handle output last.
131 filters
133 filters() returns a list of the filters inside the Stackable filter, in
134 the stack's native order.
135 Calling "$filter_stack->filters()" in the "SYNOPSIS" would return a
137 list of two filter objects:
138 POE::Filter::Line=ARRAY(0x8b5ee0)
140 POE::Filter::Grep=ARRAY(0x8b5f7c)
141 filter_types
143 filter_types() returns a list of class names for each filter in the
144 stack, in the stack's native order.
145 Calling "$filter_stack->filter_types()" in the "SYNOPSIS" would return
147 a list of two class names:
148 POE::FIlter::Line
150 POE::Filter::Grep
151 It could easily be replaced by:
153 my @filter_types = map { ref } $filter_stack->filters;
155
157 POE::Filter for more information about filters in general.
158 Specific filters, amongst which are: POE::Filter::Block,
160 POE::Filter::Grep, POE::Filter::HTTPD, POE::Filter::Line,
161 POE::Filter::Map, POE::Filter::RecordBlock, POE::Filter::Reference,
162 POE::Filter::Stream
163
165 None currently known.
166
168 The Stackable filter was contributed by Dieter Pearcey. Documentation
169 provided by Rocco Caputo.
170 Please see the POE manpage for more information about authors and
172 contributors.
173perl v5.36.0 2023-01-20 POE::Filter::Stackable(3)