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 channel/nick 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 exit 0;
40 sub _start {
42 my ($kernel,$heap) = @_[KERNEL,HEAP];
43 # We get the session ID of the component from the object
45 # and register and connect to the specified server.
46 my $irc_session = $heap->{irc}->session_id();
47 $kernel->post( $irc_session => register => 'all' );
48 $kernel->post( $irc_session => connect => { } );
49 undef;
50 }
51 sub irc_001 {
53 my ($kernel,$sender) = @_[KERNEL,SENDER];
54 # Get the component's object at any time by accessing the heap of
56 # the SENDER
57 my $poco_object = $sender->get_heap();
58 print "Connected to ", $poco_object->server_name(), "\n";
59 # In any irc_* events SENDER will be the PoCo-IRC session
61 $kernel->post( $sender => join => $_ ) for @channels;
62 undef;
63 }
64 sub irc_public {
66 my ($kernel,$sender,$who,$where,$what) = @_[KERNEL,SENDER,ARG0,ARG1,ARG2];
67 my $nick = ( split /!/, $who )[0];
68 my $channel = $where->[0];
69 my $poco_object = $sender->get_heap();
71 if ( my ($rot13) = $what =~ /^rot13 (.+)/ ) {
73 # Only operators can issue a rot13 command to us.
74 return unless $poco_object->is_channel_operator( $channel, $nick );
75 $rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
77 $kernel->post( $sender => privmsg => $channel => "$nick: $rot13" );
78 }
79 undef;
80 }
81 # We registered for all events, this will produce some debug info.
83 sub _default {
84 my ($event, $args) = @_[ARG0 .. $#_];
85 my @output = ( "$event: " );
86 foreach my $arg ( @$args ) {
88 if ( ref($arg) eq 'ARRAY' ) {
89 push( @output, "[" . join(" ,", @$arg ) . "]" );
90 } else {
91 push ( @output, "'$arg'" );
92 }
93 }
94 print STDOUT join ' ', @output, "\n";
95 return 0;
96 }
97
99 POE::Component::IRC::State is a sub-class of POE::Component::IRC which
100 tracks IRC state entities such as nicks and channels. See the documen‐
101 tation for POE::Component::IRC for general usage. This document covers
102 the extra methods that POE::Component::IRC::State provides.
103 The component tracks channels and nicks, so that it always has a cur‐
105 rent snapshot of what channels it is on and who else is on those chan‐
106 nels. The returned object provides methods to query the collected
107 state.
108
110 All of the POE::Component::IRC methods are supported, plus the follow‐
111 ing:
112 channels
114 Takes no parameters. Returns a hashref, keyed on channel name and
115 whether the bot is operator, halfop or has voice on that channel.
116 foreach my $channel ( keys %{ $irc->channels() } ) {
118 $irc->yield( 'privmsg' => $channel => 'm00!' );
119 }
120 If the component happens to not be on any channels an empty hashref
122 is returned.
123 nicks
125 Takes no parameters. Returns a list of all the nicks, including
126 itself, that it knows about. If the component happens to be on no
127 channels then an empty list is returned.
128 channel_list
130 Expects a channel as parameter. Returns a list of all nicks on the
131 specified channel. If the component happens to not be on that chan‐
132 nel an empty list will be returned.
133 is_operator
135 Expects a nick as parameter. Returns 1 if the specified nick is an
136 IRC operator or 0 otherwise. If the nick does not exist in the
137 state then a 0 will be returned.
138 is_channel_mode_set
140 Expects a channel and a single mode flag [A-Za-z]. Returns 1 if
141 that mode is set on the channel, 0 otherwise.
142 channel_modes
144 Expects a channel as parameter. Returns channel modes or undef.
145 channel_limit
147 Expects a channel as parameter. Returns the channel limit or undef.
148 channel_key
150 Expects a channel as parameter. Returns the channel key or undef.
151 is_channel_member
153 Expects a channel and a nickname as parameters. Returns 1 if the
154 specified nick is on the specified channel or 0 otherwise. If
155 either channel or nick does not exist in the state then a 0 will be
156 returned.
157 is_channel_owner
159 Expects a channel and a nickname as parameters. Returns 1 if the
160 specified nick is an owner on the specified channel or 0 otherwise.
161 If either channel or nick does not exist in the state then a 0 will
162 be returned.
163 is_channel_admin
165 Expects a channel and a nickname as parameters. Returns 1 if the
166 specified nick is an admin on the specified channel or 0 otherwise.
167 If either channel or nick does not exist in the state then a 0 will
168 be returned.
169 is_channel_operator
171 Expects a channel and a nickname as parameters. Returns 1 if the
172 specified nick is an operator on the specified channel or 0 other‐
173 wise. If either channel or nick does not exist in the state then a
174 0 will be returned.
175 is_channel_halfop
177 Expects a channel and a nickname as parameters. Returns 1 if the
178 specified nick is a half-op on the specified channel or 0 other‐
179 wise. If either channel or nick does not exist in the state then a
180 0 will be returned.
181 has_channel_voice
183 Expects a channel and a nickname as parameters. Returns 1 if the
184 specified nick has voice on the specified channel or 0 otherwise.
185 If either channel or nick does not exist in the state then a 0 will
186 be returned.
187 nick_long_form
189 Expects a nickname. Returns the long form of that nickname, ie.
190 <nick>!<user>@<host> or undef if the nick is not in the state.
191 nick_channels
193 Expects a nickname. Returns a list of the channels that that nick‐
194 name and the component are on. An empty list will be returned if
195 the nickname does not exist in the state.
196 nick_info
198 Expects a nickname. Returns a hashref containing similar informa‐
199 tion to that returned by WHOIS. Returns an undef if the nickname
200 doesn't exist in the state. The hashref contains the following
201 keys: 'Nick', 'User', 'Host', 'Userhost', 'Real', 'Server' and, if
202 applicable, 'IRCop'.
203 ban_mask
205 Expects a channel and a ban mask, as passed to MODE +b-b. Returns a
206 list of nicks on that channel that match the specified ban mask or
207 an empty list if the channel doesn't exist in the state or there
208 are no matches.
209 channel_ban_list
211 Expects a channel as a parameter. Returns a hashref containing the
212 banlist if the channel is in the state, undef if not. The hashref
213 keys are the entries on the list, each with the keys 'SetBy' and
214 'SetAt'. These keys will hold the nick!hostmask of the user who set
215 the entry (or just the nick if it's all the ircd gives us), and the
216 time at which it was set respectively.
217 channel_invex_list
219 Expects a channel as a parameter. Returns a hashref containing the
220 invite exception list if the channel is in the state, undef if not.
221 The hashref keys are the entries on the list, each with the keys
222 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the
223 user who set the entry (or just the nick if it's all the ircd gives
224 us), and the time at which it was set respectively.
225 channel_except_list
227 Expects a channel as a parameter. Returns a hashref containing the
228 ban exception list if the channel is in the state, undef if not.
229 The hashref keys are the entries on the list, each with the keys
230 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the
231 user who set the entry (or just the nick if it's all the ircd gives
232 us), and the time at which it was set respectively.
233 channel_topic
235 Expects a channel as a parameter. Returns a hashref containing
236 topic information if the channel is in the state, undef if not.
237 The hashref contains the following keys: 'Value', 'SetBy', 'SetAt'.
238 These keys will hold the topic itself, the nick!hostmask of the
239 user who set it (or just the nick if it's all the ircd gives us),
240 and the time at which it was set respectively.
241 nick_channel_modes
243 Expects a channel and a nickname as parameters. Returns the modes
244 of the specified nick on the specified channel (ie. qaohv). If the
245 nick is not on the channel in the state, undef will be returned.
246
248 As well as all the usual POE::Component::IRC 'irc_*' events, there are
249 the following events you can register for:
250 irc_chan_sync
252 Sent whenever the component has completed synchronising a channel
253 that it has joined. ARG0 is the channel name and ARG1 is the time
254 in seconds that the channel took to synchronise.
255 irc_chan_sync_invex
257 Sent whenever the component has completed synchronising a channel's
258 INVEX ( invite list ). Usually triggered by the component being
259 opped on a channel. ARG0 is the channel.
260 irc_chan_sync_excepts
262 Sent whenever the component has completed synchronising a channel's
263 EXCEPTS ( ban exemption list ). Usually triggered by the component
264 being opped on a channel. ARG0 is the channel.
265 irc_nick_sync
267 Sent whenever the component has completed synchronising a user who
268 has joined a channel the component is on. ARG0 is the user's nick‐
269 name and ARG1 the channel they have joined.
270 irc_chan_mode
272 This is almost identical to irc_mode, except that it's sent once
273 for each individual mode with it's respective argument if it has
274 one (ie. the banmask if it's +b or -b). However, this event is only
275 sent for channel modes.
276 The following two 'irc_*' events are the same as their POE::Compo‐
278 nent::IRC counterparts, with the additional parameters:
279 irc_quit
281 ARG2 contains an arrayref of channel names that are common to the
282 quitting client and the component.
283 irc_nick
285 ARG2 contains an arrayref of channel names that are common to the
286 nick changing client and the component.
287 irc_kick
289 Additional parameter ARG4 contains the full nick!user@host of the
290 kicked individual.
291
293 The component gathers information by registering for 'irc_quit',
294 'irc_nick', 'irc_join', 'irc_part', 'irc_mode', 'irc_kick' and various
295 numeric replies. When the component is asked to join a channel, when it
296 joins it will issue a 'WHO #channel' and a 'MODE #channel'. These will
297 solicit between them the numerics, 'irc_352' and 'irc_324'. You may
298 want to ignore these. When someone joins a channel the bot is on, it
299 issues a 'WHO nick'.
300 Currently, whenever the component sees a topic or channel list change,
302 it will use time() for the SetAt value and the full address of the user
303 who set it for the SetBy value. When an ircd gives us it's record of
304 such changes, it will use it's own time (obviously) and may only give
305 us the nickname of the user, rather than their full address. Thus, if
306 our time() and the ircd's time do not match, or the ircd uses the nick‐
307 name only, ugly inconsistencies can develop. This leaves the SetAt and
308 SetBy values at best, inaccurate, and you should use them with this in
309 mind (for now, at least).
310
312 Chris Williams <chris@bingosnet.co.uk>
313 With contributions from the Kinky Black Goat.
315
317 This module may be used, modified, and distributed under the same terms
318 as Perl itself. Please see the license that came with your Perl distri‐
319 bution for details.
320
322 POE::Component::IRC
323perl v5.8.8 2005-10-25 POE::Component::IRC::State(3)