NAME

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

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

'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

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

OUTPUT EVENTS

CAVEATS

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

With contributions from Lyndon Miller.

LICENCE

SEE ALSO

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