1POE::Filter::Stackable(U3s)er Contributed Perl DocumentatPiOoEn::Filter::Stackable(3)
2
3
4

NAME

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

SYNOPSIS

9         #!perl
10
11         use POE qw(
12           Wheel::FollowTail
13           Filter::Line Filter::Grep Filter::Stackable
14         );
15
16         POE::Session->create(
17           inline_states => {
18             _start => sub {
19               my $parse_input_as_lines = POE::Filter::Line->new();
20
21               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
29               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
36               $_[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
48         POE::Kernel->run();
49         exit;
50

DESCRIPTION

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
58       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
63       Internally, filters are stored in an array.
64
65       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
70       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

PUBLIC FILTER METHODS

75       In addition to the usual POE::Filter methods, POE::Filter::Stackable
76       also supports the following.
77
78   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
83         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
93   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
99         my $last_filter = $stackable->pop();
100         my $last_buffer = $last_filter->get_pending();
101
102   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
110         my $first_filter = $stackable->shift();
111         my $first_buffer = $first_filter->get_pending();
112
113   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
118         # 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
127   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
132   filters
133       filters() returns a list of the filters inside the Stackable filter, in
134       the stack's native order.
135
136       Calling "$filter_stack->filters()" in the "SYNOPSIS" would return a
137       list of two filter objects:
138
139         POE::Filter::Line=ARRAY(0x8b5ee0)
140         POE::Filter::Grep=ARRAY(0x8b5f7c)
141
142   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
146       Calling "$filter_stack->filter_types()" in the "SYNOPSIS" would return
147       a list of two class names:
148
149         POE::FIlter::Line
150         POE::Filter::Grep
151
152       It could easily be replaced by:
153
154         my @filter_types = map { ref } $filter_stack->filters;
155

SEE ALSO

157       POE::Filter for more information about filters in general.
158
159       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

BUGS

165       None currently known.
166

AUTHORS & COPYRIGHTS

168       The Stackable filter was contributed by Dieter Pearcey.  Documentation
169       provided by Rocco Caputo.
170
171       Please see the POE manpage for more information about authors and
172       contributors.
173
174
175
176perl v5.36.0                      2023-01-20         POE::Filter::Stackable(3)
Impressum