File Coverage

blib/lib/Message/Passing/Role/Filter.pm
Criterion Covered Total %
statement 10 10 100.0
branch 2 2 100.0
condition n/a
subroutine 3 3 100.0
pod 1 1 100.0
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Message::Passing::Role::Filter;
2 11     11   37326 use Moo::Role;
  11         34  
  11         79  
3 11     11   3916 use namespace::clean -except => 'meta';
  11         29  
  11         90  
4              
5             requires 'filter';
6              
7             with qw/
8             Message::Passing::Role::Input
9             Message::Passing::Role::Output
10             /;
11              
12             sub consume {
13 33     33 1 10452 my ($self, $message) = @_;
14 33         151 my $new = $self->filter($message);
15 33 100       666 return unless $new;
16 24         457 $self->output_to->consume($new);
17             }
18              
19             1;
20              
21             =head1 NAME
22              
23             Message::Passing::Role::Filter - Simple abstraction for filtering messages
24              
25             =head1 SYNOPSIS
26              
27             package My::Filter;
28             use Moo;
29             use namespace::clean -except => 'meta';
30              
31             with 'Message::Passing::Role::Filter';
32              
33             sub filter {
34             my ($self, $message) = @_;
35             # Do something with $message
36             return $message; # Or return undef to halt message!
37             }
38              
39             1;
40              
41             =head1 DESCRIPTION
42              
43             Both a producer and a consumer of messages, able to filter out messages based upon their contents,
44             or permute the structure of messages.
45              
46             =head1 REQUIRED METHODS
47              
48             =head2 filter
49              
50             Called to filter the message. Returns the mangled message.
51              
52             Note if you return undef then the message is not propagated further up the chain, which may be used
53             for filtering out unwanted messages.
54              
55             =head1 REQUIRED ATTRIBUTES
56              
57             =head2 output_to
58              
59             From L<Message::Passing::Role::Input>.
60              
61             =head1 METHODS
62              
63             =head2 consume
64              
65             Consumers a message, calling the filter method provided by the user with the message.
66              
67             In the case where the filter returns a message, outputs the message to the next step in the chain.
68              
69             =head1 SEE ALSO
70              
71             =over
72              
73             =item L<Message::Passing>
74              
75             =item L<Message::Passing::Manual::Concepts>
76              
77             =back
78              
79             =head1 SPONSORSHIP
80              
81             This module exists due to the wonderful people at Suretec Systems Ltd.
82             <http://www.suretecsystems.com/> who sponsored its development for its
83             VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with
84             the SureVoIP API -
85             <http://www.surevoip.co.uk/support/wiki/api_documentation>
86              
87             =head1 AUTHOR, COPYRIGHT AND LICENSE
88              
89             See L<Message::Passing>.
90              
91             =cut