1POE::Component::IRC::StUasteer(3C)ontributed Perl DocumePnOtEa:t:iCoonmponent::IRC::State(3)
2
6 POE::Component::IRC::State - A fully event-driven IRC client module
7 with nickname and channel tracking
8
10 # A simple Rot13 'encryption' bot
11 use strict;
13 use warnings;
14 use POE qw(Component::IRC::State);
15 my $nickname = 'Flibble' . $$;
17 my $ircname = 'Flibble the Sailor Bot';
18 my $ircserver = 'irc.blahblahblah.irc';
19 my $port = 6667;
20 my @channels = ( '#Blah', '#Foo', '#Bar' );
22 # We create a new PoCo-IRC object and component.
24 my $irc = POE::Component::IRC::State->spawn(
25 nick => $nickname,
26 server => $ircserver,
27 port => $port,
28 ircname => $ircname,
29 ) or die "Oh noooo! $!";
30 POE::Session->create(
32 package_states => [
33 main => [ qw(_default _start irc_001 irc_public) ],
34 ],
35 heap => { irc => $irc },
36 );
37 $poe_kernel->run();
39 sub _start {
41 my ($kernel, $heap) = @_[KERNEL, HEAP];
42 # We get the session ID of the component from the object
44 # and register and connect to the specified server.
45 my $irc_session = $heap->{irc}->session_id();
46 $kernel->post( $irc_session => register => 'all' );
47 $kernel->post( $irc_session => connect => { } );
48 return;
49 }
50 sub irc_001 {
52 my ($kernel, $sender) = @_[KERNEL, SENDER];
53 # Get the component's object at any time by accessing the heap of
55 # the SENDER
56 my $poco_object = $sender->get_heap();
57 print "Connected to ", $poco_object->server_name(), "\n";
58 # In any irc_* events SENDER will be the PoCo-IRC session
60 $kernel->post( $sender => join => $_ ) for @channels;
61 return;
62 }
63 sub irc_public {
65 my ($kernel ,$sender, $who, $where, $what) = @_[KERNEL, SENDER, ARG0 .. ARG2];
66 my $nick = ( split /!/, $who )[0];
67 my $channel = $where->[0];
68 my $poco_object = $sender->get_heap();
69 if ( my ($rot13) = $what =~ /^rot13 (.+)/ ) {
71 # Only operators can issue a rot13 command to us.
72 return if !$poco_object->is_channel_operator( $channel, $nick );
73 $rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
75 $kernel->post( $sender => privmsg => $channel => "$nick: $rot13" );
76 }
77 return;
78 }
79 # We registered for all events, this will produce some debug info.
81 sub _default {
82 my ($event, $args) = @_[ARG0 .. $#_];
83 my @output = ( "$event: " );
84 for my $arg ( @$args ) {
86 if (ref $arg eq 'ARRAY') {
87 push( @output, '[' . join(', ', @$arg ) . ']' );
88 }
89 else {
90 push ( @output, "'$arg'" );
91 }
92 }
93 print join ' ', @output, "\n";
94 return 0;
95 }
96
98 POE::Component::IRC::State is a sub-class of POE::Component::IRC which
99 tracks IRC state entities such as nicks and channels. See the
100 documentation for POE::Component::IRC for general usage. This document
101 covers the extra methods that POE::Component::IRC::State provides.
102 The component tracks channels and nicks, so that it always has a
104 current snapshot of what channels it is on and who else is on those
105 channels. The returned object provides methods to query the collected
106 state.
107
109 POE::Component::IRC::State's constructors, and its "connect" event, all
110 take the same arguments as POE::Component::IRC does, as well as two
111 additional ones:
112 'AwayPoll', the interval (in seconds) in which to poll (i.e. "WHO
114 #channel") the away status of channel members. Defaults to 0
115 (disabled). If enabled, you will receive "irc_away_sync_*" /
116 "irc_user_away" / "irc_user_back" events, and will be able to use the
117 "is_away" method for users other than yourself. This can cause a lot of
118 increase in traffic, especially if you are on big channels, so if you
119 do use this, you probably don't want to set it too low. For reference,
120 X-Chat uses 300 seconds (5 minutes).
121 'WhoJoiners', a boolean indicating whether the component should send a
123 "WHO nick" for every person which joins a channel. Defaults to on (the
124 "WHO" is sent). If you turn this off, "is_operator" will not work and
125 "nick_info" will only return the keys 'Nick', 'User', 'Host' and
126 'Userhost'.
127
129 All of the POE::Component::IRC methods are supported, plus the
130 following:
131 "ban_mask"
133 Expects a channel and a ban mask, as passed to MODE +b-b. Returns a
134 list of nicks on that channel that match the specified ban mask or an
135 empty list if the channel doesn't exist in the state or there are no
136 matches.
137 "channel_ban_list"
139 Expects a channel as a parameter. Returns a hashref containing the
140 banlist if the channel is in the state, a false value if not. The
141 hashref keys are the entries on the list, each with the keys 'SetBy'
142 and 'SetAt'. These keys will hold the nick!hostmask of the user who set
143 the entry (or just the nick if it's all the ircd gives us), and the
144 time at which it was set respectively.
145 "channel_creation_time"
147 Expects a channel as parameter. Returns channel creation time or a
148 false value.
149 "channel_except_list"
151 Expects a channel as a parameter. Returns a hashref containing the ban
152 exception list if the channel is in the state, a false value if not.
153 The hashref keys are the entries on the list, each with the keys
154 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user
155 who set the entry (or just the nick if it's all the ircd gives us), and
156 the time at which it was set respectively.
157 "channel_invex_list"
159 Expects a channel as a parameter. Returns a hashref containing the
160 invite exception list if the channel is in the state, a false value if
161 not. The hashref keys are the entries on the list, each with the keys
162 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user
163 who set the entry (or just the nick if it's all the ircd gives us), and
164 the time at which it was set respectively.
165 "channel_key"
167 Expects a channel as parameter. Returns the channel key or a false
168 value.
169 "channel_limit"
171 Expects a channel as parameter. Returns the channel limit or a false
172 value.
173 "channel_list"
175 Expects a channel as parameter. Returns a list of all nicks on the
176 specified channel. If the component happens to not be on that channel
177 an empty list will be returned.
178 "channel_modes"
180 Expects a channel as parameter. Returns a hash ref keyed on channel
181 mode, with the mode argument (if any) as the value. Returns a false
182 value instead if the channel is not in the state.
183 "channels"
185 Takes no parameters. Returns a hashref, keyed on channel name and
186 whether the bot is operator, halfop or has voice on that channel.
187 for my $channel ( keys %{ $irc->channels() } ) {
189 $irc->yield( 'privmsg' => $channel => 'm00!' );
190 }
191 "channel_topic"
193 Expects a channel as a parameter. Returns a hashref containing topic
194 information if the channel is in the state, a false value if not. The
195 hashref contains the following keys: 'Value', 'SetBy', 'SetAt'. These
196 keys will hold the topic itself, the nick!hostmask of the user who set
197 it (or just the nick if it's all the ircd gives us), and the time at
198 which it was set respectively.
199 If the component happens to not be on any channels an empty hashref is
201 returned.
202 "has_channel_voice"
204 Expects a channel and a nickname as parameters. Returns a true value if
205 the nick has voice on the specified channel. Returns false if the nick
206 does not have voice on the channel or if the nick/channel does not
207 exist in the state.
208 "is_away"
210 Expects a nick as parameter. Returns a true value if the specified nick
211 is away. Returns a false value if the nick is not away or not in the
212 state. This will only work for your IRC user unless you specified a
213 value for 'AwayPoll' in "spawn".
214 "is_channel_admin"
216 Expects a channel and a nickname as parameters. Returns a true value if
217 the nick is an admin on the specified channel. Returns false if the
218 nick is not an admin on the channel or if the nick/channel does not
219 exist in the state.
220 "is_channel_halfop"
222 Expects a channel and a nickname as parameters. Returns a true value if
223 the nick is a half-operator on the specified channel. Returns false if
224 the nick is not a half-operator on the channel or if the nick/channel
225 does not exist in the state.
226 "is_channel_member"
228 Expects a channel and a nickname as parameters. Returns a true value if
229 the nick is on the specified channel. Returns false if the nick is not
230 on the channel or if the nick/channel does not exist in the state.
231 "is_channel_mode_set"
233 Expects a channel and a single mode flag "[A-Za-z]". Returns a true
234 value if that mode is set on the channel.
235 "is_channel_operator"
237 Expects a channel and a nickname as parameters. Returns a true value if
238 the nick is an operator on the specified channel. Returns false if the
239 nick is not an operator on the channel or if the nick/channel does not
240 exist in the state.
241 "is_channel_owner"
243 Expects a channel and a nickname as parameters. Returns a true value if
244 the nick is an owner on the specified channel. Returns false if the
245 nick is not an owner on the channel or if the nick/channel does not
246 exist in the state.
247 "is_channel_synced"
249 Expects a channel as a parameter. Returns true if the channel has been
250 synced. Returns false if it has not been synced or if the channel is
251 not in the state.
252 "is_operator"
254 Expects a nick as parameter. Returns a true value if the specified nick
255 is an IRC operator. Returns a false value if the nick is not an IRC
256 operator or is not in the state.
257 "is_user_mode_set"
259 Expects single user mode flag "[A-Za-z]". Returns a true value if that
260 user mode is set.
261 "nick_channel_modes"
263 Expects a channel and a nickname as parameters. Returns the modes of
264 the specified nick on the specified channel (ie. qaohv). If the nick is
265 not on the channel in the state, a false value will be returned.
266 "nick_channels"
268 Expects a nickname. Returns a list of the channels that that nickname
269 and the component are on. An empty list will be returned if the
270 nickname does not exist in the state.
271 "nick_info"
273 Expects a nickname. Returns a hashref containing similar information to
274 that returned by WHOIS. Returns a false value if the nickname doesn't
275 exist in the state. The hashref contains the following keys:
276 'Nick', 'User', 'Host', 'Userhost', 'Hops', 'Real', 'Server' and, if
278 applicable, 'IRCop'.
279 "nick_long_form"
281 Expects a nickname. Returns the long form of that nickname, ie.
282 "nick!user@host" or a false value if the nick is not in the state.
283 "nicks"
285 Takes no parameters. Returns a list of all the nicks, including itself,
286 that it knows about. If the component happens to be on no channels then
287 an empty list is returned.
288 "umode"
290 Takes no parameters. Returns the current user mode set for the bot.
291
293 Augmented events
294 New paramaters are added to the following POE::Component::IRC events.
295 "irc_quit"
297 See also "irc_quit" in POE::Component::IRC.
299 Additional paramater "ARG2" contains an arrayref of channel names that
301 are common to the quitting client and the component.
302 "irc_nick"
304 See also "irc_nick" in POE::Component::IRC.
306 Additional parameter "ARG2" contains an arrayref of channel names that
308 are common to the nick hanging client and the component.
309 "irc_kick"
311 See also "irc_kick" in POE::Component::IRC.
313 Additional parameter "ARG4" contains the full nick!user@host of the
315 kicked individual.
316 "irc_disconnected"
318 "irc_error"
320 "irc_socketerr"
322 These three all have two additional parameters. "ARG1" is a hash of
324 information about your IRC user (see "nick_info"), while "ARG2" is a
325 hash of the channels you were on (see "channels").
326 New events
328 As well as all the usual POE::Component::IRC "irc_*" events, there are
329 the following events you can register for:
330 "irc_away_sync_start"
332 Sent whenever the component starts to synchronise the away statuses of
334 channel members. "ARG0" is the channel name. You will only receive this
335 event if you specified a value for 'AwayPoll' in "spawn".
336 "irc_away_sync_end"
338 Sent whenever the component has completed synchronising the away
340 statuses of channel members. "ARG0" is the channel name. You will only
341 receive this event if you specified a value for 'AwayPoll' in "spawn".
342 "irc_chan_mode"
344 This is almost identical to "irc_mode", except that it's sent once for
346 each individual mode with it's respective argument if it has one (ie.
347 the banmask if it's +b or -b). However, this event is only sent for
348 channel modes.
349 "irc_chan_sync"
351 Sent whenever the component has completed synchronising a channel that
353 it has joined. "ARG0" is the channel name and "ARG1" is the time in
354 seconds that the channel took to synchronise.
355 "irc_chan_sync_invex"
357 Sent whenever the component has completed synchronising a channel's
359 INVEX (invite list). Usually triggered by the component being opped on
360 a channel. "ARG0" is the channel name.
361 "irc_chan_sync_excepts"
363 Sent whenever the component has completed synchronising a channel's
365 EXCEPTS (ban exemption list). Usually triggered by the component being
366 opped on a channel. "ARG0" is the channel.
367 "irc_nick_sync"
369 Sent whenever the component has completed synchronising a user who has
371 joined a channel the component is on. "ARG0" is the user's nickname and
372 "ARG1" the channel they have joined.
373 "irc_user_away"
375 Sent when an IRC user sets his/her status to away. "ARG0" is the
377 nickname, "ARG1" is an arrayref of channel names that are common to the
378 nickname and the component. You will only receive this event if you
379 specified a value for 'AwayPoll' in "spawn".
380 Note: This above is only for users other than yourself. To know when
382 you change your own away status, register for the "irc_305" and
383 "irc_306" events.
384 "irc_user_back"
386 Sent when an IRC user unsets his/her away status. "ARG0" is the
388 nickname, "ARG1" is an arrayref of channel names that are common to the
389 nickname and the component. You will only receive this event if you
390 specified a value for 'AwayPoll' in "spawn".
391 Note: This above is only for users other than yourself. To know when
393 you change your own away status, register for the "irc_305" and
394 "irc_306" events.
395 "irc_user_mode"
397 This is almost identical to "irc_mode", except it is sent for each
399 individual umode that is being set.
400
402 The component gathers information by registering for "irc_quit",
403 "irc_nick", "irc_join", "irc_part", "irc_mode", "irc_kick" and various
404 numeric replies. When the component is asked to join a channel, when
405 it joins it will issue 'WHO #channel', 'MODE #channel', and 'MODE
406 #channel b'. These will solicit between them the numerics, "irc_352",
407 "irc_324" and "irc_329", respectively. When someone joins a channel
408 the bot is on, it issues a 'WHO nick'. You may want to ignore these.
409 Currently, whenever the component sees a topic or channel list change,
411 it will use "time" for the SetAt value and the full address of the user
412 who set it for the SetBy value. When an ircd gives us its record of
413 such changes, it will use its own time (obviously) and may only give us
414 the nickname of the user, rather than their full address. Thus, if our
415 "time" and the ircd's time do not match, or the ircd uses the nickname
416 only, ugly inconsistencies can develop. This leaves the 'SetAt' and
417 'SetBy' values inaccurate at best, and you should use them with this in
418 mind (for now, at least).
419
421 Chris Williams <chris@bingosnet.co.uk>
422 With contributions from Lyndon Miller.
424
426 This module may be used, modified, and distributed under the same terms
427 as Perl itself. Please see the license that came with your Perl
428 distribution for details.
429
431 POE::Component::IRC
432 POE::Component::IRC::Qnet::State
434perl v5.12.2 2010-11-05 POE::Component::IRC::State(3)