POE::Component::IRC::Qnet::State(3pm)

1POE::Component::IRC::QnUeste:r:SCtoantter(i3b)uted PerlPDOoEc:u:mCeonmtpaotnieonnt::IRC::Qnet::State(3)
2
3
4

NAME

6       POE::Component::IRC::Qnet::State - a fully event-driven IRC client mod‐
7       ule for Quakenet, with nickname and channel tracking from POE::Compo‐
8       nent::IRC::State.
9

SYNOPSIS

11         # A simple Rot13 'encryption' bot
12
13         use strict;
14         use warnings;
15         use POE qw(Component::IRC::Qnet::State);
16
17         my $nickname = 'Flibble' . $$;
18         my $ircname = 'Flibble the Sailor Bot';
19         my $ircserver = 'irc.blahblahblah.irc';
20         my $port = 6667;
21         my $qauth = 'FlibbleBOT';
22         my $qpass = 'fubar';
23
24         my @channels = ( '#Blah', '#Foo', '#Bar' );
25
26         # We create a new PoCo-IRC object and component.
27         my $irc = POE::Component::IRC::Qnet::State->spawn(
28               nick => $nickname,
29               server => $ircserver,
30               port => $port,
31               ircname => $ircname,
32         ) or die "Oh noooo! $!";
33
34         POE::Session->create(
35               package_states => [
36                       'main' => [ qw(_default _start irc_001 irc_public) ],
37               ],
38               heap => { irc => $irc },
39         );
40
41         $poe_kernel->run();
42         exit 0;
43
44         sub _start {
45           my ($kernel,$heap) = @_[KERNEL,HEAP];
46
47           # We get the session ID of the component from the object
48           # and register and connect to the specified server.
49           my $irc_session = $heap->{irc}->session_id();
50           $kernel->post( $irc_session => register => 'all' );
51           $kernel->post( $irc_session => connect => { } );
52           undef;
53         }
54
55         sub irc_001 {
56           my ($kernel,$sender) = @_[KERNEL,SENDER];
57
58           # Get the component's object at any time by accessing the heap of
59           # the SENDER
60           my $poco_object = $sender->get_heap();
61           print "Connected to ", $poco_object->server_name(), "\n";
62
63           # Lets authenticate with Quakenet's Q bot
64           $kernel->post( $sender => qbot_auth => $qauth => $qpass );
65
66           # In any irc_* events SENDER will be the PoCo-IRC session
67           $kernel->post( $sender => join => $_ ) for @channels;
68           undef;
69         }
70
71         sub irc_public {
72           my ($kernel,$sender,$who,$where,$what) = @_[KERNEL,SENDER,ARG0,ARG1,ARG2];
73           my $nick = ( split /!/, $who )[0];
74           my $channel = $where->[0];
75
76           if ( my ($rot13) = $what =~ /^rot13 (.+)/ ) {
77               # Only operators can issue a rot13 command to us.
78               return unless $poco_object->is_channel_operator( $channel, $nick );
79
80               $rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
81               $kernel->post( $sender => privmsg => $channel => "$nick: $rot13" );
82           }
83           undef;
84         }
85
86         # We registered for all events, this will produce some debug info.
87         sub _default {
88           my ($event, $args) = @_[ARG0 .. $#_];
89           my @output = ( "$event: " );
90
91           foreach my $arg ( @$args ) {
92               if ( ref($arg) eq 'ARRAY' ) {
93                       push( @output, "[" . join(" ,", @$arg ) . "]" );
94               } else {
95                       push ( @output, "'$arg'" );
96               }
97           }
98           print STDOUT join ' ', @output, "\n";
99           return 0;
100         }
101

DESCRIPTION

103       POE::Component::IRC::Qnet::State is an extension to POE::Compo‐
104       nent::IRC::Qnet specifically for use on Quakenet <http://www.quak‐
105       enet.org/>, which includes the nickname and channel tracking from
106       POE::Component::IRC::State. See the documentation for POE::Compo‐
107       nent::IRC::Qnet and POE::Component::IRC::State for general usage. This
108       document covers the extensions.
109

METHODS

111       ban_mask
112           Expects a channel and a ban mask, as passed to MODE +b-b. Returns a
113           list of nicks on that channel that match the specified ban mask or
114           an empty list if the channel doesn't exist in the state or there
115           are no matches.  Follows Quakenet ircd rules for matching authed
116           users.
117
118       is_nick_authed
119           Expects a nickname as parameter. Will return that users authname (
120           account ) if that nick is in the state and have authed with Q.
121           Returns undef if the user is not authed or the nick doesn't exist
122           in the state.
123
124       find_auth_nicks
125           Expects an authname and a channel name. Will return a list of nicks
126           on the given channel that have authed with the given authname.
127
128       nick_info
129           Expects a nickname. Returns a hashref containing similar informa‐
130           tion to that returned by WHOIS. Returns an undef if the nickname
131           doesn't exist in the state. The hashref contains the following
132           keys: 'Nick', 'User', 'Host', 'Se rver', 'Auth', if authed, and, if
133           applicable, 'IRCop'.
134

INPUT

136       These additional events are accepted:
137
138       resync_chan
139           Accepts a list of channels, will resynchronise each of those chan‐
140           nels as if they have been joined for the first time. Expect to see
141           an 'irc_chan_sync' event for each channel given.
142
143       resync_nick
144           Accepts a nickname and a list of channels. Will resynchronise the
145           given nickname and issue an 'irc_nick_sync' event for each of the
146           given channels ( assuming that nick is on each of those channels ).
147

OUTPUT

149       This module returns one additional event over and above the usual
150       events:
151
152       irc_nick_authed
153           Sent when the component detects that a user has authed with Q. Due
154           to the mechanics of Quakenet you will usually only receive this if
155           an unauthed user joins a channel, then at some later point auths
156           with Q. The component 'detects' the auth by seeing if Q or L
157           decides to +v or +o the user. Klunky? Indeed. But it is the only
158           way to do it, unfortunately.
159
160       The following two 'irc_*' events are the same as their POE::Compo‐
161       nent::IRC::State counterparts, with the additional parameters:
162
163       irc_quit
164           ARG3 contains the quitting clients auth name if applicable.
165
166       irc_part
167           ARG3 contains the parting clients auth name if applicable.
168
169       irc_kick
170           ARG5 contains the kick victim's auth name if applicable.
171

CAVEATS

173       Like POE::Component::IRC::State this component registers itself for a
174       number of events. The main difference with POE::Component::IRC::State
175       is that it uses an extended form of 'WHO' supported by the Quakenet
176       ircd, asuka. This WHO returns a different numeric reply than the origi‐
177       nal WHO, namely, 'irc_354'. Also, due to the way Quakenet is configured
178       all users will appear to be on the server '*.quakenet.org'.
179

BUGS

181       A few have turned up in the past and they are sure to again. Please use
182       <http://rt.cpan.org/> to report any. Alternatively, email the current
183       maintainer.
184

AUTHOR

186       Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
187
188       Based on the original POE::Component::IRC by:
189
190       Dennis Taylor
191