IRC.pm

filter: Statementstmt 95.1% 157 / 165 Branchbran 78.9% 90 / 114 Conditioncond 68.9% 20 / 29 MC/DCmcdc 47.3% 9 / 19 Subroutinesub 85.1% 23 / 27 Podpod 85.7% 18 / 21 totaltotal 84.5% 317 / 375 CC 70 SCAR 26.1
CC
70
Cov
87%
incoming_message
28.6
send_message
14.1
cmp_prefix_flags
11.7
CRAP 13.6
↑ Summary IRC/Client.pm »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2010-2017 -- leonerd@leonerd.org.uk
5  
6 package Protocol::IRC 0.13;
7  
8 12 ▶use v5.14;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 12 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 12 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 12 ▶use Scalar::Util qw( blessed );
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 12 ▶use Protocol::IRC::Message;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 # This should be mixed in MI-style
17  
18 =head1 NAME
19  
20 C<Protocol::IRC> - IRC protocol handling
21  
22 =head1 DESCRIPTION
23  
24 This mix-in class provides a base layer of IRC message handling logic. It
25 allows reading of IRC messages from a string buffer and dispatching them to
26 handler methods on its instance.
27  
28 L<Protocol::IRC::Client> provides an extension to this logic that may be more
29 convenient for IRC client implementations. Much of the code provided here is
30 still useful in client applications, so the reader should be familiar with
31 both modules.
32  
33 =head1 MESSAGE HANDLING
34  
35 Every incoming message causes a sequence of message handling to occur. First,
36 the message is parsed, and a hash of data about it is created; this is called
37 the hints hash. The message and this hash are then passed down a sequence of
38 potential handlers.
39  
40 Each handler indicates by return value, whether it considers the message to
41 have been handled. Processing of the message is not interrupted the first time
42 a handler declares to have handled a message. Instead, the hints hash is marked
43 to say it has been handled. Later handlers can still inspect the message or its
44 hints, using this information to decide if they wish to take further action.
45  
46 A message with a command of C<COMMAND> will try handlers in following places:
47  
48 =over 4
49  
50 =item 1.
51  
52 A method called C<on_message_COMMAND>
53  
54 $irc->on_message_COMMAND( $message, \%hints )
55  
56 =item 2.
57  
58 A method called C<on_message>
59  
60 $irc->on_message( 'COMMAND', $message, \%hints )
61  
62 =back
63  
64 For server numeric replies, if the numeric reply has a known name, it will be
65 attempted first at its known name, before falling back to the numeric if it
66 was not handled. Unrecognised numerics will be attempted only at their numeric
67 value.
68  
69 Because of the wide variety of messages in IRC involving various types of data
70 the message handling specific cases for certain types of message, including
71 adding extra hints hash items, or invoking extra message handler stages. These
72 details are noted here.
73  
74 Many of these messages create new events; called synthesized messages. These
75 are messages created by the C<Protocol::IRC> object itself, to better
76 represent some of the details derived from the primary ones from the server.
77 These events all take lower-case command names, rather than capitals, and will
78 have a C<synthesized> key in the hints hash, set to a true value. These are
79 dispatched and handled identically to regular primary events, detailed above.
80  
81 If any handler of the synthesized message returns true, then this marks the
82 primary message handled as well.
83  
84 If a message is received that has a gating disposition, extra processing is
85 applied to it before the processing above. The effect on its gate is given as
86 a string (one of C<more>, C<done>, C<fail>) to handlers in the following
87 places:
88  
89 =over 4
90  
91 =item 1.
92  
93 A method called C<on_message_gate_EFFECT_GATE>
94  
95 $irc->on_message_gate_EFFECT_GATE( $message, \%hints )
96  
97 =item 2.
98  
99 A method called C<on_message_gate_EFFECT>
100  
101 $irc->on_message_gate_EFFECT( 'GATE', $message, \%hints )
102  
103 =item 3.
104  
105 A method called C<on_message_gate>
106  
107 $irc->on_message_gate( 'EFFECT', 'GATE', $message, \%hints )
108  
109 =back
110  
111 =head2 Message Hints
112  
113 When messages arrive they are passed to the appropriate message handling
114 method, which the implementation may define. As well as the message, a hash
115 of extra information derived from or relating to the message is also given.
116  
117 The following keys will be present in any message hint hash:
118  
119 =over 8
120  
121 =item handled => BOOL
122  
123 Initially false. Will be set to true the first time a handler returns a true
124 value.
125  
126 =item prefix_nick => STRING
127  
128 =item prefix_user => STRING
129  
130 =item prefix_host => STRING
131  
132 Values split from the message prefix; see the C<Protocol::IRC::Message>
133 C<prefix_split> method.
134  
135 =item prefix_name => STRING
136  
137 Usually the prefix nick, or the hostname in case the nick isn't defined
138 (usually on server messages).
139  
140 =item prefix_is_me => BOOL
141  
142 True if the nick mentioned in the prefix refers to this connection.
143  
144 =back
145  
146 Added to this set, will be all the values returned by the message's
147 C<named_args> method. Some of these values may cause yet more values to be
148 generated.
149  
150 If the message type defines a C<target_name>:
151  
152 =over 8
153  
154 =item * target_type => STRING
155  
156 Either C<channel> or C<user>, as returned by C<classify_name>.
157  
158 =item * target_is_me => BOOL
159  
160 True if the target name is a user and refers to this connection.
161  
162 =back
163  
164 Any key whose name ends in C<_nick> or C<_name> will have a corresponding key
165 added with C<_folded> suffixed on its name, containing the value casefolded
166 using C<casefold_name>. This is for the convenience of string comparisons,
167 hash keys, etc..
168  
169 Any of these keys that are not the C<prefix_name> will additionally have a
170 corresponding key with C<_is_me> replacing the C<_nick> or C<_name>,
171 containing the boolean result of calling the C<is_nick_me> method on that
172 name. This makes it simpler to detect commands or results affecting the user
173 the connection represents.
174  
175 =cut
176  
177 =head1 METHODS
178  
179 =cut
180  
181 =head2 on_read
182  
183 $irc->on_read( $buffer )
184  
185 Informs the protocol implementation that more bytes have been read from the
186 peer. This method will modify the C<$buffer> directly, and remove from it the
187 prefix of bytes it has consumed. Any bytes remaining should be stored by the
188 caller for next time.
189  
190 Any messages found in the buffer will be passed, in sequence, to the
191 C<incoming_message> method.
192  
193 =cut
194  
195 sub on_read
196 52 ▶{
Subroutine on_read: called CC=3 SCAR=11.0
Pod documented
197 52 my $self = shift;
198 # buffer in $_[0]
199  
200 52 ▶ while( $_[0] =~ s/^(.*)\x0d\x0a// ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] =~ s/^(.*)\x0d\x0a//u) 53 52 105
201 53 my $line = $1;
202 # Ignore blank lines
203 53 ▶ next if !length $line;
Branch: 1 branch
BranchTrueFalseTotal
unless length $line 2 51 53
204  
205 51 $self->incoming_message( Protocol::IRC::Message->new_from_line( $line ) );
206 }
207 }
208  
209 =head2 incoming_message
210  
211 $irc->incoming_message( $message )
212  
213 Invoked by the C<on_read> method for every incoming IRC message. This method
214 implements the actual dispatch into various handler methods as described in
215 the L</MESSAGE HANDLING> section above.
216  
217 This method is exposed so that subclasses can override it, primarily to wrap
218 extra logic before or after the main dispatch (e.g. for logging or other
219 processing).
220  
221 =cut
222  
223 sub incoming_message
224 51 ▶{
Subroutine incoming_message: called CC=28 SCAR=33.5
Pod documented
225 51 my $self = shift;
226 51 my ( $message ) = @_;
227  
228 51 my $command = $message->command_name;
229  
230 51 my ( $prefix_nick, $prefix_user, $prefix_host ) = $message->prefix_split;
231  
232 51 ▶ my $hints = {
Branch: 1 branch
BranchTrueFalseTotal
defined $prefix_nick ? : 27 24 51
233 handled => 0,
234  
235 prefix_nick => $prefix_nick,
236 prefix_user => $prefix_user,
237 prefix_host => $prefix_host,
238 # Most of the time this will be "nick", except for special messages from the server
239 prefix_name => defined $prefix_nick ? $prefix_nick : $prefix_host,
240 };
241  
242 51 ▶ if( my $named_args = $message->named_args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $named_args = $message->named_args) 48 3 51
243 48 $hints->{$_} = $named_args->{$_} for keys %$named_args;
244 }
245  
246 51 ▶ if( defined $hints->{text} and my $encoder = $self->encoder ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $hints->{"text"} and my $encoder = $self->encoder) 2 49 51
Condition100%3/3
defined $hints->{"text"} and my $encoder = $self->encoder
!ll&&!rl&&r
30192
MC/DC100%2/2
defined $hints->{"text"} and my $encoder = $self->encoder
defined $hints->{"text"} my $encoder = $self->encoder
Truth table100%3/3
A and B
A= defined $hints->{"text"}B= my $encoder = $self->encoder
ABresult
0X0
100
111
247 2 $hints->{text} = $encoder->decode( $hints->{text} );
248 }
249  
250 51 ▶ if( defined( my $target_name = $hints->{target_name} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $target_name = $hints->{"target_name"})) 28 23 51
251 28 my $target_type = $self->classify_name( $target_name );
252 28 $hints->{target_type} = $target_type;
253 }
254  
255 51 my $prepare_method = "prepare_hints_$command";
256 51 ▶ $self->$prepare_method( $message, $hints ) if $self->can( $prepare_method );
Branch: 1 branch
BranchTrueFalseTotal
if $self->can($prepare_method) 12 39 51
257  
258 51 ▶ foreach my $k ( grep { m/_nick$/ or m/_name$/ } keys %$hints ) {
Condition100%3/3
/_nick$/u || /_name$/u
l!l&&r!l&&!r
5879271
MC/DC100%2/2
/_nick$/u || /_name$/u
/_nick$/u /_name$/u
Truth table100%3/3
A || B
A= /_nick$/uB= /_name$/u
ABresult
1X1
011
000
259 137 $hints->{"${k}_folded"} = $self->casefold_name( my $name = $hints->{$k} );
260 137 ▶ defined $name or next;
Branch: 1 branch
BranchTrueFalseTotal
defined $name or next 113 24 137
261 113 ▶ $k eq "prefix_name" and next;
Branch: 1 branch
BranchTrueFalseTotal
$k eq "prefix_name" and next 51 62 113
262  
263 62 ( my $knew = $k ) =~ s/_name$|_nick$/_is_me/;
264 62 $hints->{$knew} = $self->is_nick_me( $name );
265 }
266  
267 51 ▶ if( my $disp = $message->gate_disposition ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $disp = $message->gate_disposition) 17 34 51
268 17 my ( $type, $gate ) = $disp =~ m/^([-+!*])(.*)$/;
269 my $effect = ( $type eq "-" ? "more" :
270 $type eq "+" ? "done" :
271 $type eq "!" ? "fail" :
272 17 ▶ $type eq "*" ? ( $hints->{prefix_is_me} ? "done" : undef ) :
Branch: 5 branches
BranchTrueFalseTotal
$type eq '-' ? : 10 7 17
$type eq '+' ? : 5 2 7
$type eq '!' ? : 1 1 2
$type eq '*' ? : 1 0 1
$hints->{'prefix_is_me'} ? : 1 0 1
273 die "TODO" );
274  
275 17 ▶ if( defined $effect ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $effect) 17 0 17
276 17 ▶ $self->invoke( "on_message_gate_${effect}_$gate", $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_gate_${effect}_$gate", $message, $hints) and $hints->{"handled"} = 1 0 17 17
277 17 ▶ $self->invoke( "on_message_gate_$effect", $gate, $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_gate_$effect", $gate, $message, $hints) and $hints->{"handled"} = 1 0 17 17
278 17 ▶ $self->invoke( "on_message_gate", $effect, $gate, $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_gate", $effect, $gate, $message, $hints) and $hints->{"handled"} = 1 17 0 17
279 }
280 }
281  
282 51 ▶ $self->invoke( "on_message_$command", $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_$command", $message, $hints) and $hints->{"handled"} = 1 9 42 51
283 51 ▶ $self->invoke( "on_message", $command, $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message", $command, $message, $hints) and $hints->{"handled"} = 1 28 23 51
284  
285 51 ▶ if( !$hints->{handled} and $message->command ne $command ) { # numerics
Branch: 1 branch
BranchTrueFalseTotal
if (not $hints->{"handled"} and $message->command ne $command) 2 49 51
Condition100%3/3
not $hints->{"handled"} and $message->command ne $command
!ll&&!rl&&r
4812
MC/DC100%2/2
not $hints->{"handled"} and $message->command ne $command
not $hints->{"handled"} $message->command ne $command
Truth table100%3/3
not(A) and B
A= not $hints->{"handled"}B= $message->command ne $command
ABresult
0X0
100
111
286 2 my $numeric = $message->command;
287 2 ▶ $self->invoke( "on_message_$numeric", $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_$numeric", $message, $hints) and $hints->{"handled"} = 1 0 2 2
288 2 ▶ $self->invoke( "on_message", $numeric, $message, $hints ) and $hints->{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message", $numeric, $message, $hints) and $hints->{"handled"} = 1 0 2 2
289 }
290 }
291  
292 =head2 send_message
293  
294 This method takes arguments in three different forms, depending on their
295 number and type.
296  
297 If the first argument is a reference then it must contain a
298 C<Protocol::IRC::Message> instance which will be sent directly:
299  
300 $irc->send_message( $message )
301  
302 Otherwise, the first argument must be a plain string that gives the command
303 name. If the second argument is a hash, it provides named arguments in a form
304 similar to L<Protocol::IRC::Message/new_from_named_args>, otherwise the
305 remaining arguments must be the prefix string and other positional arguments,
306 as plain strings:
307  
308 $irc->send_message( $command, { %args } )
309  
310 $irc->send_message( $command, $prefix, @args )
311  
312 =head3 Named Argument Mangling
313  
314 For symmetry with incoming message processing, this method applies some
315 adjustment of named arguments for convenience of callers.
316  
317 =over 4
318  
319 =item *
320  
321 Callers may define a named argument of C<target>; it will be renamed to
322 C<target_name>.
323  
324 =item *
325  
326 If a named argument of C<text> is defined and an L</encoder> exists, the
327 argument value will be encoded using this encoder.
328  
329 =back
330  
331 =cut
332  
333 sub send_message
334 14 ▶{
Subroutine send_message: called CC=13 SCAR=26.5
Pod documented
335 14 my $self = shift;
336  
337 14 my $message;
338  
339 14 ▶ if( @_ == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ == 1) { } 1 13 14
340 1 $message = shift;
341 1 ▶ blessed $message and $message->isa( "Protocol::IRC::Message" ) or
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($message) and $message->isa("Protocol::IRC::Message") or croak("Expected an instance of Protocol::IRC::Message") 1 0 1
Condition33%1/3
builtin::blessed($message) and $message->isa("Protocol::IRC::Message")
!ll&&!rl&&r
001
MC/DC0%0/2
builtin::blessed($message) and $message->isa("Protocol::IRC::Message")
builtin::blessed($message) $message->isa("Protocol::IRC::Message")
Truth table33%1/3
A and B
A= builtin::blessed($message)B= $message->isa("Protocol::IRC::Message")
ABresult
0X0
100
111
342 croak "Expected an instance of Protocol::IRC::Message";
343 }
344 else {
345 13 my $command = shift;
346 13 ▶ ref $command and
Branch: 1 branch
BranchTrueFalseTotal
ref $command and croak("Expected \$command to be a plain string") 0 13 13
347 croak "Expected \$command to be a plain string";
348  
349 13 ▶ if( @_ == 1 and ref $_[0] ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ == 1 and ref $_[0]) { } 8 5 13
Condition100%3/3
@_ == 1 and ref $_[0]
!ll&&!rl&&r
418
MC/DC100%2/2
@_ == 1 and ref $_[0]
@_ == 1 ref $_[0]
Truth table100%3/3
A and B
A= @_ == 1B= ref $_[0]
ABresult
0X0
100
111
350 8 my %args = %{ $_[0] };
351  
352 8 ▶ $args{target_name} = delete $args{target} if defined $args{target};
Branch: 1 branch
BranchTrueFalseTotal
if defined $args{"target"} 3 5 8
353  
354 8 ▶ if( defined $args{text} and my $encoder = $self->encoder ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $args{"text"} and my $encoder = $self->encoder) 0 8 8
Condition66%2/3
defined $args{"text"} and my $encoder = $self->encoder
!ll&&!rl&&r
170
MC/DC0%0/2
defined $args{"text"} and my $encoder = $self->encoder
defined $args{"text"} my $encoder = $self->encoder
Truth table66%2/3
A and B
A= defined $args{"text"}B= my $encoder = $self->encoder
ABresult
0X0
100
111
355 0 $args{text} = $encoder->encode( $args{text} );
356 }
357  
358 8 $message = Protocol::IRC::Message->new_from_named_args( $command, %args );
359 }
360 else {
361 5 my ( $prefix, @args ) = @_;
362  
363 5 ▶ if( my $encoder = $self->encoder ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $encoder = $self->encoder) 1 4 5
364 1 my $argnames = Protocol::IRC::Message->arg_names( $command );
365  
366 1 ▶ if( defined( my $i = $argnames->{text} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $i = $argnames->{"text"})) 1 0 1
367 1 ▶ $args[$i] = $encoder->encode( $args[$i] ) if defined $args[$i];
Branch: 1 branch
BranchTrueFalseTotal
if defined $args[$i] 1 0 1
368 }
369 }
370  
371 5 $message = Protocol::IRC::Message->new( $command, $prefix, @args );
372 }
373 }
374  
375 14 $self->write( $message->stream_to_line . "\x0d\x0a" );
376 }
377  
378 =head2 send_ctcp
379  
380 $irc->send_ctcp( $prefix, $target, $verb, $argstr )
381  
382 Shortcut to sending a CTCP message. Sends a PRIVMSG to the given target,
383 containing the given verb and argument string.
384  
385 =cut
386  
387 sub send_ctcp
388 1 ▶{
Subroutine send_ctcp: called CC=1 SCAR=0.0
Pod documented
389 1 my $self = shift;
390 1 my ( $prefix, $target, $verb, $argstr ) = @_;
391  
392 1 $self->send_message( "PRIVMSG", undef, $target, "\001$verb $argstr\001" );
393 }
394  
395 =head2 send_ctcpreply
396  
397 $irc->send_ctcpreply( $prefix, $target, $verb, $argstr )
398  
399 Shortcut to sending a CTCP reply. As C<send_ctcp> but using a NOTICE instead.
400  
401 =cut
402  
403 sub send_ctcpreply
404 1 ▶{
Subroutine send_ctcpreply: called CC=1 SCAR=0.0
Pod documented
405 1 my $self = shift;
406 1 my ( $prefix, $target, $verb, $argstr ) = @_;
407  
408 1 $self->send_message( "NOTICE", undef, $target, "\001$verb $argstr\001" );
409 }
410  
411 =head1 ISUPPORT-DRIVEN UTILITIES
412  
413 The following methods are controlled by the server information given in the
414 C<ISUPPORT> settings. They use the C<isupport> required method to query the
415 information required.
416  
417 =cut
418  
419 =head2 casefold_name
420  
421 $name_folded = $irc->casefold_name( $name )
422  
423 Returns the C<$name>, folded in case according to the server's C<CASEMAPPING>
424 C<ISUPPORT>. Such a folded name will compare using C<eq> according to whether the
425 server would consider it the same name.
426  
427 Useful for use in hash keys or similar.
428  
429 =cut
430  
431 sub casefold_name
432 296 ▶{
Subroutine casefold_name: called CC=5 SCAR=16.1
Pod documented
433 296 my $self = shift;
434 296 my ( $nick ) = @_;
435  
436 296 ▶ return undef unless defined $nick;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $nick 24 272 296
437  
438 272 ▶ my $mapping = lc( $self->isupport( "CASEMAPPING" ) || "" );
Condition100%2/2
$self->isupport('CASEMAPPING') || ''
l!l
8264
MC/DC100%1/1
$self->isupport('CASEMAPPING') || ''
$self->isupport('CASEMAPPING')
Truth table100%2/2
A
A= $self->isupport('CASEMAPPING')
Aresult
11
00
439  
440 # Squash the 'capital' [\] into lowercase {|}
441 272 ▶ $nick =~ tr/[\\]/{|}/ if $mapping ne "ascii";
Branch: 1 branch
BranchTrueFalseTotal
if $mapping ne "ascii" 269 3 272
442  
443 # Most RFC 1459 implementations also squash ^ to ~, even though the RFC
444 # didn't mention it
445 272 ▶ $nick =~ tr/^/~/ unless $mapping eq "strict-rfc1459";
Branch: 1 branch
BranchTrueFalseTotal
unless $mapping eq "strict-rfc1459" 270 2 272
446  
447 272 return lc $nick;
448 }
449  
450 =head2 cmp_prefix_flags
451  
452 $cmp = $irc->cmp_prefix_flags( $lhs, $rhs )
453  
454 Compares two channel occupant prefix flags, and returns a signed integer to
455 indicate which of them has higher priviledge, according to the server's
456 ISUPPORT declaration. Suitable for use in a C<sort()> function or similar.
457  
458 =cut
459  
460 sub cmp_prefix_flags
461 4 ▶{
Subroutine cmp_prefix_flags: called CC=9 SCAR=24.6
Pod documented
462 4 my $self = shift;
463 4 my ( $lhs, $rhs ) = @_;
464  
465 4 ▶ return undef unless defined $lhs and defined $rhs;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $lhs and defined $rhs 0 4 4
Condition33%1/3
defined $lhs and defined $rhs
!ll&&!rl&&r
004
MC/DC0%0/2
defined $lhs and defined $rhs
defined $lhs defined $rhs
Truth table33%1/3
A and B
A= defined $lhsB= defined $rhs
ABresult
0X0
100
111
466  
467 # As a special case, compare emptystring as being lower than voice
468 4 ▶ return 0 if $lhs eq "" and $rhs eq "";
Branch: 1 branch
BranchTrueFalseTotal
if $lhs eq "" and $rhs eq "" 0 4 4
Condition33%1/3
$lhs eq "" and $rhs eq ""
!ll&&!rl&&r
400
MC/DC0%0/2
$lhs eq "" and $rhs eq ""
$lhs eq "" $rhs eq ""
Truth table33%1/3
A and B
A= $lhs eq ""B= $rhs eq ""
ABresult
0X0
100
111
469 4 ▶ return 1 if $rhs eq "";
Branch: 1 branch
BranchTrueFalseTotal
if $rhs eq "" 0 4 4
470 4 ▶ return -1 if $lhs eq "";
Branch: 1 branch
BranchTrueFalseTotal
if $lhs eq "" 0 4 4
471  
472 4 my $PREFIX_FLAGS = $self->isupport( 'prefix_flags' );
473  
474 4 ▶ ( my $lhs_index = index $PREFIX_FLAGS, $lhs ) > -1 or return undef;
Branch: 1 branch
BranchTrueFalseTotal
(my $lhs_index = index($PREFIX_FLAGS, $lhs)) > -1 or return undef 4 0 4
475 4 ▶ ( my $rhs_index = index $PREFIX_FLAGS, $rhs ) > -1 or return undef;
Branch: 1 branch
BranchTrueFalseTotal
(my $rhs_index = index($PREFIX_FLAGS, $rhs)) > -1 or return undef 3 1 4
476  
477 # IRC puts these in greatest-first, so we need to swap the ordering here
478 3 return $rhs_index <=> $lhs_index;
479 }
480  
481 =head2 cmp_prefix_modes
482  
483 $cmp = $irc->cmp_prefix_modes( $lhs, $rhs )
484  
485 Similar to C<cmp_prefix_flags>, but compares channel occupant C<MODE> command
486 flags.
487  
488 =cut
489  
490 sub cmp_prefix_modes
491 4 ▶{
Subroutine cmp_prefix_modes: called CC=5 SCAR=16.8
Pod documented
492 4 my $self = shift;
493 4 my ( $lhs, $rhs ) = @_;
494  
495 4 ▶ return undef unless defined $lhs and defined $rhs;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $lhs and defined $rhs 0 4 4
Condition33%1/3
defined $lhs and defined $rhs
!ll&&!rl&&r
004
MC/DC0%0/2
defined $lhs and defined $rhs
defined $lhs defined $rhs
Truth table33%1/3
A and B
A= defined $lhsB= defined $rhs
ABresult
0X0
100
111
496  
497 4 my $PREFIX_MODES = $self->isupport( "prefix_modes" );
498  
499 4 ▶ ( my $lhs_index = index $PREFIX_MODES, $lhs ) > -1 or return undef;
Branch: 1 branch
BranchTrueFalseTotal
(my $lhs_index = index($PREFIX_MODES, $lhs)) > -1 or return undef 4 0 4
500 4 ▶ ( my $rhs_index = index $PREFIX_MODES, $rhs ) > -1 or return undef;
Branch: 1 branch
BranchTrueFalseTotal
(my $rhs_index = index($PREFIX_MODES, $rhs)) > -1 or return undef 3 1 4
501  
502 # IRC puts these in greatest-first, so we need to swap the ordering here
503 3 return $rhs_index <=> $lhs_index;
504 }
505  
506 =head2 prefix_mode2flag
507  
508 $flag = $irc->prefix_mode2flag( $mode )
509  
510 Converts a channel occupant C<MODE> flag (such as C<o>) into a name prefix
511 flag (such as C<@>).
512  
513 =cut
514  
515 sub prefix_mode2flag
516 7 ▶{
Subroutine prefix_mode2flag: called CC=1 SCAR=0.0
Pod documented
517 7 my $self = shift;
518 7 my ( $mode ) = @_;
519  
520 7 return $self->isupport( 'prefix_map_m2f' )->{$mode};
521 }
522  
523 =head2 prefix_flag2mode
524  
525 $mode = $irc->prefix_flag2mode( $flag )
526  
527 The inverse of C<prefix_mode2flag>.
528  
529 =cut
530  
531 sub prefix_flag2mode
532 2 ▶{
Subroutine prefix_flag2mode: called CC=1 SCAR=0.0
Pod documented
533 2 my $self = shift;
534 2 my ( $flag ) = @_;
535  
536 2 return $self->isupport( 'prefix_map_f2m' )->{$flag};
537 }
538  
539 =head2 classify_name
540  
541 $classification = $irc->classify_name( $name )
542  
543 Returns C<channel> if the given name matches the pattern of names allowed for
544 channels according to the server's C<CHANTYPES> C<ISUPPORT>. Returns C<user>
545 if not.
546  
547 =cut
548  
549 sub classify_name
550 40 ▶{
Subroutine classify_name: called CC=2 SCAR=6.9
Pod documented
551 40 my $self = shift;
552 40 my ( $name ) = @_;
553  
554 40 ▶ return "channel" if $name =~ $self->isupport( "channame_re" );
Branch: 1 branch
BranchTrueFalseTotal
if $name =~ $self->isupport("channame_re") 29 11 40
555 11 return "user"; # TODO: Perhaps we can be a bit stricter - only check for valid nick chars?
556 }
557  
558 =head2 is_nick_me
559  
560 $me = $irc->is_nick_me( $nick )
561  
562 Returns true if the given nick refers to that in use by the connection.
563  
564 =cut
565  
566 sub is_nick_me
567 67 ▶{
Subroutine is_nick_me: called CC=1 SCAR=0.0
Pod documented
568 67 my $self = shift;
569 67 my ( $nick ) = @_;
570  
571 67 return $self->casefold_name( $nick ) eq $self->nick_folded;
572 }
573  
574 =head1 INTERNAL MESSAGE HANDLING
575  
576 The following messages are handled internally by C<Protocol::IRC>.
577  
578 =cut
579  
580 =head2 PING
581  
582 C<PING> messages are automatically replied to with C<PONG>.
583  
584 =cut
585  
586 sub on_message_PING
587 0 ▶{
Subroutine on_message_PING: not called CC=1 SCAR=6.9
Pod undocumented
588 0 my $self = shift;
589 0 my ( $message, $hints ) = @_;
590  
591 0 $self->send_message( "PONG", undef, $message->named_args->{text} );
592  
593 0 return 1;
594 }
595  
596 =head2 NOTICE and PRIVMSG
597  
598 Because C<NOTICE> and C<PRIVMSG> are so similar, they are handled together by
599 synthesized events called C<text>, C<ctcp> and C<ctcpreply>. Depending on the
600 contents of the text, and whether it was supplied in a C<PRIVMSG> or a
601 C<NOTICE>, one of these three events will be created.
602  
603 In all cases, the hints hash will contain a C<is_notice> key being true or
604 false, depending on whether the original messages was a C<NOTICE> or a
605 C<PRIVMSG>, a C<target_name> key containing the message target name, a
606 case-folded version of the name in a C<target_name_folded> key, and a
607 classification of the target type in a C<target_type> key.
608  
609 For the C<user> target type, it will contain a boolean in C<target_is_me> to
610 indicate if the target of the message is the user represented by this
611 connection.
612  
613 For the C<channel> target type, it will contain a C<restriction> key
614 containing the channel message restriction, if present.
615  
616 For normal C<text> messages, it will contain a key C<text> containing the
617 actual message text.
618  
619 For either CTCP message type, it will contain keys C<ctcp_verb> and
620 C<ctcp_args> with the parsed message. The C<ctcp_verb> will contain the first
621 space-separated token, and C<ctcp_args> will be a string containing the rest
622 of the line, otherwise unmodified. This type of message is also subject to a
623 special stage of handler dispatch, involving the CTCP verb string. For
624 messages with C<VERB> as the verb, the following are tried. C<CTCP> may stand
625 for either C<ctcp> or C<ctcpreply>.
626  
627 =over 4
628  
629 =item 1.
630  
631 A method called C<on_message_CTCP_VERB>
632  
633 $irc->on_message_CTCP_VERB( $message, \%hints )
634  
635 =item 2.
636  
637 A method called C<on_message_CTCP>
638  
639 $irc->on_message_CTCP( 'VERB', $message, \%hintss )
640  
641 =item 3.
642  
643 A method called C<on_message>
644  
645 $irc->on_message( 'CTCP VERB', $message, \%hints )
646  
647 =back
648  
649 =cut
650  
651 sub on_message_NOTICE
652 3 ▶{
Subroutine on_message_NOTICE: called CC=1 SCAR=0.0
Pod undocumented
653 3 my $self = shift;
654 3 my ( $message, $hints ) = @_;
655 3 return $self->_on_message_text( $message, $hints, 1 );
656 }
657  
658 sub on_message_PRIVMSG
659 7 ▶{
Subroutine on_message_PRIVMSG: called CC=1 SCAR=0.0
Pod undocumented
660 7 my $self = shift;
661 7 my ( $message, $hints ) = @_;
662 7 return $self->_on_message_text( $message, $hints, 0 );
663 }
664  
665 sub _on_message_text
666 10 ▶{
Subroutine _on_message_text: called CC=11 SCAR=24.0
667 10 my $self = shift;
668 10 my ( $message, $hints, $is_notice ) = @_;
669  
670 10 my %hints = (
671 %$hints,
672 synthesized => 1,
673 is_notice => $is_notice,
674 );
675  
676 # TODO: In client->server messages this might be a comma-separated list
677 10 my $target = delete $hints{targets};
678  
679 10 my $prefixflag_re = $self->isupport( 'prefixflag_re' );
680  
681 10 my $restriction = "";
682 10 ▶ while( $target =~ m/^$prefixflag_re/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($target =~ /^$prefixflag_re/u) 1 10 11
683 1 $restriction .= substr( $target, 0, 1, "" );
684 }
685  
686 10 $hints{target_name} = $target;
687 10 $hints{target_name_folded} = $self->casefold_name( $target );
688  
689 10 my $type = $hints{target_type} = $self->classify_name( $target );
690  
691 10 ▶ if( $type eq "channel" ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'channel') { } 5 5 10
elsif ($type eq 'user') { } 5 0 5
692 5 $hints{restriction} = $restriction;
693 5 $hints{target_is_me} = '';
694 }
695 elsif( $type eq "user" ) {
696 # TODO: user messages probably can't have restrictions. What to do
697 # if we got one?
698 5 $hints{target_is_me} = $self->is_nick_me( $target );
699 }
700  
701 10 my $text = $hints->{text};
702  
703 10 ▶ if( $text =~ m/^\x01(.*)\x01$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text =~ /^\x01(.*)\x01$/u) { } 2 8 10
704 2 ( my $verb, $text ) = split( m/ /, $1, 2 );
705 2 $hints{ctcp_verb} = $verb;
706 2 $hints{ctcp_args} = $text;
707  
708 2 ▶ my $ctcptype = $is_notice ? "ctcpreply" : "ctcp";
Branch: 1 branch
BranchTrueFalseTotal
$is_notice ? : 1 1 2
709  
710 2 ▶ $self->invoke( "on_message_${ctcptype}_$verb", $message, \%hints ) and $hints{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_${ctcptype}_$verb", $message, \%hints) and $hints{"handled"} = 1 0 2 2
711 2 ▶ $self->invoke( "on_message_${ctcptype}", $verb, $message, \%hints ) and $hints{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_$ctcptype", $verb, $message, \%hints) and $hints{"handled"} = 1 0 2 2
712 2 ▶ $self->invoke( "on_message", "$ctcptype $verb", $message, \%hints ) and $hints{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message", "$ctcptype $verb", $message, \%hints) and $hints{"handled"} = 1 2 0 2
713 }
714 else {
715 8 $hints{text} = $text;
716  
717 8 ▶ $self->invoke( "on_message_text", $message, \%hints ) and $hints{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message_text", $message, \%hints) and $hints{"handled"} = 1 1 7 8
718 8 ▶ $self->invoke( "on_message", "text", $message, \%hints ) and $hints{handled} = 1;
Branch: 1 branch
BranchTrueFalseTotal
$self->invoke("on_message", "text", $message, \%hints) and $hints{"handled"} = 1 4 4 8
719 }
720  
721 10 return $hints{handled};
722 }
723  
724 =head1 REQUIRED METHODS
725  
726 As this class is an abstract base class, a concrete implementation must
727 provide the following methods to complete it and make it useable.
728  
729 =cut
730  
731 =head2 write
732  
733 $irc->write( $string )
734  
735 Requests the byte string to be sent to the peer
736  
737 =cut
738  
739 0 ▶sub write { croak "Attemped to invoke abstract ->write on " . ref $_[0] }
Subroutine write: not called CC=1 SCAR=6.9
Pod documented
740  
741 =head2 encoder
742  
743 $encoder = $irc->encoder
744  
745 Optional. If supplied, returns an L<Encode> object used to encode or decode
746 the bytes appearing in a C<text> field of a message. If set, all text strings
747 will be returned, and should be given, as Unicode strings. They will be
748 encoded or decoded using this object.
749  
750 =cut
751  
752 30 ▶sub encoder { undef }
Subroutine encoder: called CC=1 SCAR=0.0
Pod documented
753  
754 =head2 invoke
755  
756 $result = $irc->invoke( $name, @args )
757  
758 Optional. If provided, invokes the message handling routine called C<$name>
759 with the given arguments. A default implementation is provided which simply
760 attempts to invoke a method of the given name, or return false if no method
761 of that name exists.
762  
763 If an implementation does override this method, care should be taken to ensure
764 that methods are tested for and invoked if present, in addition to any other
765 work the method wishes to perform, as this is the basis by which derived
766 message handling works.
767  
768 =cut
769  
770 sub invoke
771 214 ▶{
Subroutine invoke: called CC=2 SCAR=6.9
Pod documented
772 214 my $self = shift;
773 214 my ( $name, @args ) = @_;
774 214 ▶ return unless $self->can( $name );
Branch: 1 branch
BranchTrueFalseTotal
unless $self->can($name) 111 103 214
775 103 return $self->$name( @args );
776 }
777  
778 =head2 isupport
779  
780 $value = $irc->isupport( $field )
781  
782 Should return the value of the given C<ISUPPORT> field.
783  
784 As well as the all-capitals server-supplied fields, the following fields may
785 be requested. Their names are all lowercase and contain underscores, to
786 distinguish them from server-supplied fields.
787  
788 =over 8
789  
790 =item prefix_modes => STRING
791  
792 The mode characters from C<PREFIX> (e.g. C<ohv>)
793  
794 =item prefix_flags => STRING
795  
796 The flag characters from C<PREFIX> (e.g. C<@%+>)
797  
798 =item prefixflag_re => Regexp
799  
800 A precompiled regexp that matches any of the prefix flags
801  
802 =item prefix_map_m2f => HASH
803  
804 A map from mode characters to flag characters
805  
806 =item prefix_map_f2m => HASH
807  
808 A map from flag characters to mode characters
809  
810 =item chanmodes_list => ARRAY
811  
812 A 4-element array containing the split portions of C<CHANMODES>;
813  
814 [ $listmodes, $argmodes, $argsetmodes, $boolmodes ]
815  
816 =item channame_re => Regexp
817  
818 A precompiled regexp that matches any string beginning with a channel prefix
819 character in C<CHANTYPES>.
820  
821 =back
822  
823 =cut
824  
825 0 ▶sub isupport { croak "Attempted to invoke abstract ->isupport on " . ref $_[0] }
Subroutine isupport: not called CC=1 SCAR=6.9
Pod documented
826  
827 =head2 nick
828  
829 $nick = $irc->nick
830  
831 Should return the current nick in use by the connection.
832  
833 =head2 nick_folded
834  
835 $nick_folded = $irc->nick_folded
836  
837 Optional. If supplied, should return the current nick as case-folded by the
838 C<casefold_name> method. If not provided, this will be performed by
839 case-folding the result from C<nick>.
840  
841 =cut
842  
843 0 ▶sub nick { croak "Attempted to invoke abstract ->nick on " . ref $_[0] }
Subroutine nick: not called CC=1 SCAR=6.9
Pod documented
844 67 ▶sub nick_folded { $_[0]->casefold_name( $_[0]->nick ) }
Subroutine nick_folded: called CC=1 SCAR=0.0
Pod documented
845  
846 =head1 AUTHOR
847  
848 Paul Evans <leonerd@leonerd.org.uk>
849  
850 =cut
851  
852 12 0x55AA;
↑ Summary IRC/Client.pm »