File Coverage

blib/lib/Reflexive/Stream/Filtering.pm
Criterion Covered Total %
statement 1 3 33.3
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 2 4 50.0


line stmt bran cond sub pod time code
1             package Reflexive::Stream::Filtering;
2             {
3             $Reflexive::Stream::Filtering::VERSION = '1.122150';
4             }
5              
6             #ABSTRACT: Provides a Reflex Stream object that can use POE::Filters
7 2     2   66604 use Moose;
  0            
  0            
8             extends 'Reflex::Stream';
9             with 'Reflexive::Role::StreamFiltering';
10              
11              
12             __PACKAGE__->meta->make_immutable();
13              
14             1;
15              
16              
17              
18             =pod
19              
20             =head1 NAME
21              
22             Reflexive::Stream::Filtering - Provides a Reflex Stream object that can use POE::Filters
23              
24             =head1 VERSION
25              
26             version 1.122150
27              
28             =head1 DESCRIPTION
29              
30             Reflexive::Stream::Filtering provides a Reflex::Stream subclass that takes and
31             uses a POE::Filter instance to filter inbound and outbound data similar to a
32             POE::Wheel object. But this class is much much simpler. The goal is to merely
33             shim in a POE::Filter instance and to do it as unobtrusively as possible.
34              
35             The main implemetation of this functionality is actually within
36             L<Reflexive::Role::StreamFiltering>. Its documentation is included here for
37             convenience.
38              
39             =head1 PUBLIC_ATTRIBUTES
40              
41             =head2 input_filter
42              
43             is: rw, isa: POE::Filter, default: POE::Filter::Stream
44              
45             This attribute is mostly to be provided at construction of the Stream. If none
46             is provided then POE::Filter::Stream (which is just a passthrough) is used.
47              
48             Internally, the following handles are provided:
49              
50             'filter_get' => 'get_one',
51             'filter_start' => 'get_one_start',
52              
53             Incidentially, only the newer POE::Filter get_one_start/get_one interace is
54             supported.
55              
56             =head2 output_filter
57              
58             is: rw, isa: POE::Filter, default: POE::Filter::Stream
59              
60             Like the input_filter attribute, this is to be provided at construction time of
61             the Stream. If an output_filter is not provided, POE::Filter::Stream is used.
62              
63             The following handles are provided:
64              
65             'filter_put' => 'put'
66              
67             =head1 PUBLIC_METHODS
68              
69             =head2 put
70              
71             (Any)
72              
73             This method is around advised to run the provided data through the filter before
74             passing it along to the original method if the filter returns multiple filtered
75             chunks then each chunk will get its own method call.
76              
77             =head1 PROTECTED_METHODS
78              
79             =head2 on_data
80              
81             (Reflexive::Event::Data)
82              
83             on_data is the advised to intercept data events. Data is passed through the
84             ilter via get_one_start. Then get_one is called until no more filtered chunks
85             are returned. Each filtered chunk is then delievered via the emitted data event
86             which is reemitted.
87              
88             =head1 CAVEATS
89              
90             The filter attributes are marked as read-write, but take care when swapping
91             filters as the filters may have data left in their buffers. This module isn't
92             quite as smart as POE::Wheel::ReadWrite and it won't automagically pull any
93             buffered data out of the previous filter and apply it to the new filter.
94              
95             =head1 AUTHOR
96              
97             Nicholas R. Perez <nperez@cpan.org>
98              
99             =head1 COPYRIGHT AND LICENSE
100              
101             This software is copyright (c) 2012 by Nicholas R. Perez <nperez@cpan.org>.
102              
103             This is free software; you can redistribute it and/or modify it under
104             the same terms as the Perl 5 programming language system itself.
105              
106             =cut
107              
108              
109             __END__