File Coverage

blib/lib/ThreatNet/IRC/Envelope.pm
Criterion Covered Total %
statement 19 21 90.4
branch 4 10 40.0
condition 2 6 33.3
subroutine 8 10 80.0
pod 4 4 100.0
total 37 51 72.5


line stmt bran cond sub pod time code
1             package ThreatNet::IRC::Envelope;
2              
3             =pod
4              
5             =head1 NAME
6              
7             ThreatNet::IRC::Envelope - IRC envelope for ThreatNet::Message objects
8              
9             =head1 SYNOPSIS
10              
11             # Handle messages as provided from an IRC channel
12             sub handle_message {
13             my $envelope = shift;
14            
15             # Only trust messages from our network
16             return unless $envelope->who =~ /\.mydomain.com$/;
17            
18             # Filter out anything local
19             my $message = $envelope->message;
20             return unless $LocalFilter->keep($message);
21            
22             do_something($message);
23             }
24              
25             =head1 DESCRIPTION
26              
27             C objects can be created and moved around from and
28             to a variety of places. However, when freshly recieved from an IRC channel,
29             you may wish to apply logic to them based on special IRC-specific
30             considerations.
31              
32             The C class provides special C<"envelope"> objects
33             containing the actual message objects. The channel listener is able to
34             apply specific logic to these envelopes, before the message itself is
35             extracted and moves further into a system.
36              
37             The primary use for these envelopes is to allow for applying trust rules
38             on a sub-channel level. For example, trusting messages that come from a
39             specific bot in a channel when the channel as a whole is untrusted.
40              
41             =head1 METHODS
42              
43             =cut
44              
45 2     2   13 use strict;
  2         3  
  2         82  
46 2     2   6187 use Params::Util '_INSTANCE';
  2         5970  
  2         209  
47 2     2   15 use vars qw{$VERSION};
  2         4  
  2         106  
48             BEGIN {
49 2     2   1062 $VERSION = '0.20';
50             }
51              
52              
53              
54              
55              
56             #####################################################################
57             # Constructor and Accessors
58              
59             =pod
60              
61             =head2 new $Message, $who, $where
62              
63             The C constructor creates a new IRC envelope for a particular
64             message. It is most likely to happen inside the IRC/ThreatNet connector
65             code, rather than in your own code.
66              
67             Takes as argument a L object, the identifier of the
68             source node, and then channel name in which the message occured.
69              
70             Returns a new C object, or C on error.
71              
72             =cut
73              
74             sub new {
75 1 50   1 1 868 my $class = ref $_[0] ? ref shift : shift;
76 1 50       13 my $Message = _INSTANCE(shift, 'ThreatNet::Message') or return undef;
77 1 50 33     10 my $who = (defined $_[0] and length $_[0]) ? shift : return undef;
78 1 50 33     12 my $where = (defined $_[0] and length $_[0]) ? shift : return undef;
79              
80             # Create the object
81 1         9 my $self = bless {
82             Message => $Message,
83             who => $who,
84             where => $where,
85             }, $class;
86              
87 1         3 $self;
88             }
89              
90             =pod
91              
92             =head2 message
93              
94             The C accessor returns the contents of the envelope, a
95             L (or sub-class) object.
96              
97             =cut
98              
99 1     1 1 436 sub message { $_[0]->{Message} }
100              
101             =pod
102              
103             =head2 who
104              
105             The C accessor returns the identification string of the source IRC
106             client.
107              
108             =cut
109              
110 1     1 1 6 sub who { $_[0]->{who} }
111              
112             =pod
113              
114             =head2 where
115              
116             The C accessor returns the name of the channel that the message
117             occured in.
118              
119             =cut
120              
121 1     1 1 5 sub where { $_[0]->{where} }
122              
123              
124              
125              
126              
127             #####################################################################
128             # Params::Coerce Support
129              
130 0     0     sub __as_ThreatNet_Message { shift->message(@_) }
131              
132             sub __as_ThreatNet_Message_IPv4 {
133 0 0   0     $_[0]->{Message}->isa('ThreatNet::Message::IPv4')
134             ? shift->message(@_)
135             : undef;
136             }
137              
138             1;
139              
140             =pod
141              
142             =head1 SUPPORT
143              
144             All bugs should be filed via the bug tracker at
145              
146             L
147              
148             For other issues, or commercial enhancement and support, contact the author
149              
150             =head1 AUTHORS
151              
152             Adam Kennedy Eadamk@cpan.orgE
153              
154             =head1 SEE ALSO
155              
156             L
157              
158             =head1 COPYRIGHT
159              
160             Copyright (c) 2005 Adam Kennedy. All rights reserved.
161             This program is free software; you can redistribute
162             it and/or modify it under the same terms as Perl itself.
163              
164             The full text of the license can be found in the
165             LICENSE file included with this module.
166              
167             =cut
168