Provided by: libpoe-component-irc-perl_6.83+dfsg-1_all bug

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.

SEE ALSO

       POE::Component::IRC

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