


POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


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";




perl v5.12.2                2010-11-05                          1





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


            # 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:




perl v5.12.2                2010-11-05                          2





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


       '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.





perl v5.12.2                2010-11-05                          3





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


   "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 any channels an empty hashref is
       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.



perl v5.12.2                2010-11-05                          4





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


   "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



perl v5.12.2                2010-11-05                          5





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


       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
   Augmented events
       New paramaters are added to the following POE::Component::IRC events.

       "irc_quit"

       See also "irc_quit" in POE::Component::IRC.

       Additional paramater "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_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



perl v5.12.2                2010-11-05                          6





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


       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



perl v5.12.2                2010-11-05                          7





POE::Component:User:Contributed PerPOE::Component::IRC::State(3p)


       "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.

SEE ALSO
       POE::Component::IRC

       POE::Component::IRC::Qnet::State






perl v5.12.2                2010-11-05                          8


