POE::Component::IRC::State - a fully event-driven IRC client module with channel/nick tracking.

  use POE::Component::IRC::State;

  my ($irc) = POE::Component::IRC::State->spawn() or die;

  $irc->yield( 'register' => 'all' );

  $irc->yield( 'connect' => 
                { Nick     => 'Boolahman',
                  Server   => 'irc-w.primenet.com',
                  Port     => 6669,
                  Username => 'quetzal',
                  Ircname  => 'Ask me about my colon!', } );

POE::Component::IRC::State is an extension to 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 extensions.

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.

All of the POE::Component::IRC methods are supported, plus the following:

channels

Takes no parameters. Returns a hashref, keyed on channel name and whether the bot is operator, halfop or has voice on that channel.

        foreach my $channel ( keys %{ $irc->channels() } ) {
                $irc->yield( 'privmsg' => $channel => 'm00!' );
        }

If the component happens to not be on any channels an empty hashref is returned.

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.

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.

is_operator

Expects a nick as parameter. Returns 1 if the specified nick is an IRC operator or 0 otherwise. If the nick does not exist in the state then a 0 will be returned.

is_channel_mode_set

Expects a channel and a single mode flag [A-Za-z]. Returns 1 if that mode is set on the channel, 0 otherwise.

channel_modes

Expects a channel as parameter. Returns channel modes or undef.

is_channel_member

Expects a channel and a nickname as parameters. Returns 1 if the specified nick is on the specified channel or 0 otherwise. If either channel or nick does not exist in the state then a 0 will be returned.

is_channel_operator

Expects a channel and a nickname as parameters. Returns 1 if the specified nick is an operator on the specified channel or 0 otherwise. If either channel or nick does not exist in the state then a 0 will be returned.

is_channel_halfop

Expects a channel and a nickname as parameters. Returns 1 if the specified nick is a half-op on the specified channel or 0 otherwise. If either channel or nick does not exist in the state then a 0 will be returned.

has_channel_voice

Expects a channel and a nickname as parameters. Returns 1 if the specified nick has voice on the specified channel or 0 otherwise. If either channel or nick does not exist in the state then a 0 will be returned.

nick_long_form

Expects a nickname. Returns the long form of that nickname, ie. <nick>!<user>@<host> or undef if the nick is not in the state.

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 an undef if the nickname doesn't exist in the state. The hashref contains the following keys: 'Nick', 'User', 'Host', 'Server' and, if applicable, 'IRCop'.

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.

As well as all the usual POE::Component::IRC 'irc_*' events, there are the following events you can register for:

irc_chan_sync

Sent whenever the component has completed synchronising a channel that it has joined. ARG0 is the channel name.

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.

The following two 'irc_*' events are the same as their POE::Component::IRC counterparts, with the additional parameters:

irc_quit

ARG2 contains an arrayref of channel names that are common to the quitting client and the component.

irc_nick

ARG2 contains an arrayref of channel names that are common to the nick changing client and the component.

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 a 'WHO #channel' and a 'MODE #channel'. These will solicit between them the numerics, 'irc_352' and 'irc_324'. You may want to ignore these. When someones joins a channel the bot is on, it issues a 'WHO nick'.

Chris Williams <chris@bingosnet.co.uk>

POE::Component::IRC