NAME
POE::Component::IRC::State - A fully event-driven IRC client module with nickname and channel tracking
SYNOPSIS
# A simple Rot13 'encryption' bot
use strict;
use warnings;
use POE qw(Component::IRC::State);
my $nickname = 'Flibble' . $$;
my $ircname = 'Flibble the Sailor Bot';
my $ircserver = 'irc.blahblahblah.irc';
my $port = 6667;
my @channels = ( '#Blah', '#Foo', '#Bar' );
# We create a new PoCo-IRC object and component.
my $irc = POE::Component::IRC::State->spawn(
nick => $nickname,
server => $ircserver,
port => $port,
ircname => $ircname,
) or die "Oh noooo! $!";
POE::Session->create(
package_states => [
main => [ qw(_default _start irc_001 irc_public) ],
],
heap => { irc => $irc },
);
$poe_kernel->run();
sub _start {
my ($kernel, $heap) = @_[KERNEL, HEAP];
# We get the session ID of the component from the object
# and register and connect to the specified server.
my $irc_session = $heap->{irc}->session_id();
$kernel->post( $irc_session => register => 'all' );
$kernel->post( $irc_session => connect => { } );
return;
}
sub irc_001 {
my ($kernel, $sender) = @_[KERNEL, SENDER];
# Get the component's object at any time by accessing the heap of
# the SENDER
my $poco_object = $sender->get_heap();
print "Connected to ", $poco_object->server_name(), "\n";
# In any irc_* events SENDER will be the PoCo-IRC session
$kernel->post( $sender => join => $_ ) for @channels;
return;
}
sub irc_public {
my ($kernel ,$sender, $who, $where, $what) = @_[KERNEL, SENDER, ARG0 .. ARG2];
my $nick = ( split /!/, $who )[0];
my $channel = $where->[0];
my $poco_object = $sender->get_heap();
if ( my ($rot13) = $what =~ /^rot13 (.+)/ ) {
# Only operators can issue a rot13 command to us.
return if !$poco_object->is_channel_operator( $channel, $nick );
$rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
$kernel->post( $sender => privmsg => $channel => "$nick: $rot13" );
}
return;
}
# We registered for all events, this will produce some debug info.
sub _default {
my ($event, $args) = @_[ARG0 .. $#_];
my @output = ( "$event: " );
for my $arg ( @$args ) {
if (ref $arg eq 'ARRAY') {
push( @output, '[' . join(', ', @$arg ) . ']' );
}
else {
push ( @output, "'$arg'" );
}
}
print join ' ', @output, "\n";
return 0;
}DESCRIPTION
POE::Component::IRC::State is a sub-class of POE::Component::IRC which tracks IRC state entities such as nicks and channels. See the documentation for POE::Component::IRC for general usage. This document covers the extra methods that POE::Component::IRC::State provides.
The component tracks channels and nicks, so that it always has a current snapshot of what channels it is on and who else is on those channels. The returned object provides methods to query the collected state.
CONSTRUCTORS
POE::Component::IRC::State's constructors, and its connect event, all take the same arguments as POE::Component::IRC does, as well as two additional ones:
'AwayPoll', the interval (in seconds) in which to poll (i.e. WHO #channel) the away status of channel members. Defaults to 0 (disabled). If enabled, you will receive irc_away_sync_* / irc_user_away / irc_user_back events, and will be able to use the is_away method for users other than yourself. This can cause a lot of increase in traffic, especially if you are on big channels, so if you do use this, you probably don't want to set it too low. For reference, X-Chat uses 300 seconds (5 minutes).
'WhoJoiners', a boolean indicating whether the component should send a WHO nick for every person which joins a channel. Defaults to on (the WHO is sent). If you turn this off, is_operator will not work and nick_info will only return the keys 'Nick', 'User', 'Host' and 'Userhost'.
METHODS
All of the POE::Component::IRC methods are supported, plus the following:
ban_mask
Expects a channel and a ban mask, as passed to MODE +b-b. Returns a list of nicks on that channel that match the specified ban mask or an empty list if the channel doesn't exist in the state or there are no matches.
channel_ban_list
Expects a channel as a parameter. Returns a hashref containing the banlist if the channel is in the state, a false value if not. The hashref keys are the entries on the list, each with the keys 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user who set the entry (or just the nick if it's all the ircd gives us), and the time at which it was set respectively.
channel_creation_time
Expects a channel as parameter. Returns channel creation time or a false value.
channel_except_list
Expects a channel as a parameter. Returns a hashref containing the ban exception list if the channel is in the state, a false value if not. The hashref keys are the entries on the list, each with the keys 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user who set the entry (or just the nick if it's all the ircd gives us), and the time at which it was set respectively.
channel_invex_list
Expects a channel as a parameter. Returns a hashref containing the invite exception list if the channel is in the state, a false value if not. The hashref keys are the entries on the list, each with the keys 'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user who set the entry (or just the nick if it's all the ircd gives us), and the time at which it was set respectively.
channel_key
Expects a channel as parameter. Returns the channel key or a false value.
channel_limit
Expects a channel as parameter. Returns the channel limit or a false value.
channel_list
Expects a channel as parameter. Returns a list of all nicks on the specified channel. If the component happens to not be on that channel an empty list will be returned.
channel_modes
Expects a channel as parameter. Returns a hash ref keyed on channel mode, with the mode argument (if any) as the value. Returns a false value instead if the channel is not in the state.
channels
Takes no parameters. Returns a hashref, keyed on channel name and whether the bot is operator, halfop or has voice on that channel.
for my $channel ( keys %{ $irc->channels() } ) {
$irc->yield( 'privmsg' => $channel => 'm00!' );
}channel_topic
Expects a channel as a parameter. Returns a hashref containing topic information if the channel is in the state, a false value if not. The hashref contains the following keys: 'Value', 'SetBy', 'SetAt'. These keys will hold the topic itself, the nick!hostmask of the user who set it (or just the nick if it's all the ircd gives us), and the time at which it was set respectively.
If the component happens to not be on the channel, nothing will be returned.
channel_url
Expects a channel as a parameter. Returns the channel's URL. If the channel has no URL or the component is not on the channel, nothing will be returned.
has_channel_voice
Expects a channel and a nickname as parameters. Returns a true value if the nick has voice on the specified channel. Returns false if the nick does not have voice on the channel or if the nick/channel does not exist in the state.
is_away
Expects a nick as parameter. Returns a true value if the specified nick is away. Returns a false value if the nick is not away or not in the state. This will only work for your IRC user unless you specified a value for 'AwayPoll' in spawn.
is_channel_admin
Expects a channel and a nickname as parameters. Returns a true value if the nick is an admin on the specified channel. Returns false if the nick is not an admin on the channel or if the nick/channel does not exist in the state.
is_channel_halfop
Expects a channel and a nickname as parameters. Returns a true value if the nick is a half-operator on the specified channel. Returns false if the nick is not a half-operator on the channel or if the nick/channel does not exist in the state.
is_channel_member
Expects a channel and a nickname as parameters. Returns a true value if the nick is on the specified channel. Returns false if the nick is not on the channel or if the nick/channel does not exist in the state.
is_channel_mode_set
Expects a channel and a single mode flag [A-Za-z]. Returns a true value if that mode is set on the channel.
is_channel_operator
Expects a channel and a nickname as parameters. Returns a true value if the nick is an operator on the specified channel. Returns false if the nick is not an operator on the channel or if the nick/channel does not exist in the state.
is_channel_owner
Expects a channel and a nickname as parameters. Returns a true value if the nick is an owner on the specified channel. Returns false if the nick is not an owner on the channel or if the nick/channel does not exist in the state.
is_channel_synced
Expects a channel as a parameter. Returns true if the channel has been synced. Returns false if it has not been synced or if the channel is not in the state.
is_operator
Expects a nick as parameter. Returns a true value if the specified nick is an IRC operator. Returns a false value if the nick is not an IRC operator or is not in the state.
is_user_mode_set
Expects single user mode flag [A-Za-z]. Returns a true value if that user mode is set.
nick_channel_modes
Expects a channel and a nickname as parameters. Returns the modes of the specified nick on the specified channel (ie. qaohv). If the nick is not on the channel in the state, a false value will be returned.
nick_channels
Expects a nickname. Returns a list of the channels that that nickname and the component are on. An empty list will be returned if the nickname does not exist in the state.
nick_info
Expects a nickname. Returns a hashref containing similar information to that returned by WHOIS. Returns a false value if the nickname doesn't exist in the state. The hashref contains the following keys:
'Nick', 'User', 'Host', 'Userhost', 'Hops', 'Real', 'Server' and, if applicable, 'IRCop'.
nick_long_form
Expects a nickname. Returns the long form of that nickname, ie. nick!user@host or a false value if the nick is not in the state.
nicks
Takes no parameters. Returns a list of all the nicks, including itself, that it knows about. If the component happens to be on no channels then an empty list is returned.
umode
Takes no parameters. Returns the current user mode set for the bot.
OUTPUT EVENTS
Augmented events
New parameters are added to the following POE::Component::IRC events.
irc_quit
See also irc_quit in POE::Component::IRC.
Additional parameter ARG2 contains an arrayref of channel names that are common to the quitting client and the component.
irc_nick
See also irc_nick in POE::Component::IRC.
Additional parameter ARG2 contains an arrayref of channel names that are common to the nick hanging client and the component.
irc_kick
See also irc_kick in POE::Component::IRC.
Additional parameter ARG4 contains the full nick!user@host of the kicked individual.
irc_topic
See also irc_kick in POE::Component::IRC.
Additional parameter ARG3 contains the old topic hashref, like the one returned by channel_topic.
irc_disconnected
irc_error
irc_socketerr
These three all have two additional parameters. ARG1 is a hash of information about your IRC user (see nick_info), while ARG2 is a hash of the channels you were on (see channels).
New events
As well as all the usual POE::Component::IRC irc_* events, there are the following events you can register for:
irc_away_sync_start
Sent whenever the component starts to synchronise the away statuses of channel members. ARG0 is the channel name. You will only receive this event if you specified a value for 'AwayPoll' in spawn.
irc_away_sync_end
Sent whenever the component has completed synchronising the away statuses of channel members. ARG0 is the channel name. You will only receive this event if you specified a value for 'AwayPoll' in spawn.
irc_chan_mode
This is almost identical to irc_mode, except that it's sent once for each individual mode with it's respective argument if it has one (ie. the banmask if it's +b or -b). However, this event is only sent for channel modes.
irc_chan_sync
Sent whenever the component has completed synchronising a channel that it has joined. ARG0 is the channel name and ARG1 is the time in seconds that the channel took to synchronise.
irc_chan_sync_invex
Sent whenever the component has completed synchronising a channel's INVEX (invite list). Usually triggered by the component being opped on a channel. ARG0 is the channel name.
irc_chan_sync_excepts
Sent whenever the component has completed synchronising a channel's EXCEPTS (ban exemption list). Usually triggered by the component being opped on a channel. ARG0 is the channel.
irc_nick_sync
Sent whenever the component has completed synchronising a user who has joined a channel the component is on. ARG0 is the user's nickname and ARG1 the channel they have joined.
irc_user_away
Sent when an IRC user sets his/her status to away. ARG0 is the nickname, ARG1 is an arrayref of channel names that are common to the nickname and the component. You will only receive this event if you specified a value for 'AwayPoll' in spawn.
Note: This above is only for users other than yourself. To know when you change your own away status, register for the irc_305 and irc_306 events.
irc_user_back
Sent when an IRC user unsets his/her away status. ARG0 is the nickname, ARG1 is an arrayref of channel names that are common to the nickname and the component. You will only receive this event if you specified a value for 'AwayPoll' in spawn.
Note: This above is only for users other than yourself. To know when you change your own away status, register for the irc_305 and irc_306 events.
irc_user_mode
This is almost identical to irc_mode, except it is sent for each individual umode that is being set.
CAVEATS
The component gathers information by registering for irc_quit, irc_nick, irc_join, irc_part, irc_mode, irc_kick and various numeric replies. When the component is asked to join a channel, when it joins it will issue 'WHO #channel', 'MODE #channel', and 'MODE #channel b'. These will solicit between them the numerics, irc_352, irc_324 and irc_329, respectively. When someone joins a channel the bot is on, it issues a 'WHO nick'. You may want to ignore these.
Currently, whenever the component sees a topic or channel list change, it will use time for the SetAt value and the full address of the user who set it for the SetBy value. When an ircd gives us its record of such changes, it will use its own time (obviously) and may only give us the nickname of the user, rather than their full address. Thus, if our time and the ircd's time do not match, or the ircd uses the nickname only, ugly inconsistencies can develop. This leaves the 'SetAt' and 'SetBy' values inaccurate at best, and you should use them with this in mind (for now, at least).
AUTHOR
Chris Williams <chris@bingosnet.co.uk>
With contributions from Lyndon Miller.
LICENCE
This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.