NAME

SYNOPSIS

 # A simple ROT13 'encryption' plugin

 package Rot13;

 use strict;
 use warnings;
 use POE::Component::IRC::Plugin qw( :ALL );

 # Plugin object constructor
 sub new {
     my $package = shift;
     return bless {}, $package;
 }

 sub PCI_register {
     my ($self, $irc) = splice @_, 0, 2;

     $irc->plugin_register( $self, 'SERVER', qw(public) );
     return 1;
 }

 # This is method is mandatory but we don't actually have anything to do.
 sub PCI_unregister {
     return 1;
 }

 sub S_public {
     my ($self, $irc) = splice @_, 0, 2;

     # Parameters are passed as scalar-refs including arrayrefs.
     my $nick    = ( split /!/, ${ $_[0] } )[0];
     my $channel = ${ $_[1] }->[0];
     my $msg     = ${ $_[2] };

     if (my ($rot13) = $msg =~ /^rot13 (.+)/) {
         $rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];

         # Send a response back to the server.
         $irc->yield( privmsg => $channel => $rot13 );
         # We don't want other plugins to process this
         return PCI_EAT_PLUGIN;
     }

     # Default action is to allow other plugins to process it.
     return PCI_EAT_NONE;
 }

DESCRIPTION

HISTORY

BinGOs, the current maintainer of the module, and I heartily agreed that this is a wise choice.

One example:

Look at the magnificent new feature in 3.4 -> irc_whois replies! Yes, that is a feature I bet most of us have been coveting for a while, as it definitely makes our life easier. It was implemented in 30 minutes or so after a request, the maintainer said. I replied by saying that it's a wonderful idea, but what would happen if somebody else asked for a new feature? Maybe thatfeature is something we all would love to have, so should it be put in the core? Plugins allow the core to stay lean and mean, while delegating additional functionality to outside modules. BinGOs' work with making PoCo-IRC inheritable is wonderful, but what if there were 2 modules which have features that you would love to have in your bot? Inherit from both? Imagine the mess...

Here comes plugins to the rescue :)

You could say Bot::Pluggable does the job, and so on, but if this feature were put into the core, it would allow PoCo-IRC to be extended beyond our wildest dreams, and allow the code to be shared amongst us all, giving us superior bug smashing abilities.

Yes, there are changes that most of us will moan when we go update our bots to use the new $irc object system, but what if we also used this opportunity to improve PoCo-IRC even more and give it a lifespan until Perl8 or whatever comes along? :)

DESCRIPTION

• Data received from the server
• User commands about to be sent to the server

The goal of this system is to make PoCo-IRC so easy to extend, enabling it to Take Over The World! *Just Kidding*

The general architecture of using the plugins should be:

 # Import the stuff...
 use POE;
 use POE::Component::IRC;
 use POE::Component::IRC::Plugin::ExamplePlugin;

 # Create our session here
 POE::Session->create( ... );

 # Create the IRC session here
 my $irc = POE::Component::IRC->spawn() or die "Oh noooo! $!";

 # Create the plugin
 # Of course it could be something like $plugin = MyPlugin->new();
 my $plugin = POE::Component::IRC::Plugin::ExamplePlugin->new( ... );

 # Hook it up!
 $irc->plugin_add( 'ExamplePlugin', $plugin );

 # OOPS, we lost the plugin object!
 my $pluginobj = $irc->plugin_get( 'ExamplePlugin' );

 # We want a list of plugins and objects
 my $hashref = $irc->plugin_list();

 # Oh! We want a list of plugin aliases.
 my @aliases = keys %{ $irc->plugin_list() };

 # Ah, we want to remove the plugin
 $plugin = $irc->plugin_del( 'ExamplePlugin' );

The plugins themselves will conform to the standard API described here. What they can do is limited only by imagination and the IRC RFC's ;)

 # Import the constants
 use POE::Component::IRC::Plugin qw( :ALL );

 # Our constructor
 sub new {
     ...
 }

 # Required entry point for PoCo-IRC
 sub PCI_register {
     my ($self, $irc) = @_;
     # Register events we are interested in
     $irc->plugin_register( $self, 'SERVER', qw( 355 kick whatever) );

     # Return success
     return 1;
 }

 # Required exit point for PoCo-IRC
 sub PCI_unregister {
     my ($self, $irc) = @_;

     # PCI will automatically unregister events for the plugin

     # Do some cleanup...

     # Return success
     return 1;
 }

 # Registered events will be sent to methods starting with IRC_
 # If the plugin registered for SERVER - irc_355
 sub S_355 {
     my($self, $irc, $line) = @_;

     # Remember, we receive pointers to scalars, so we can modify them
     $$line = 'frobnicate!';

     # Return an exit code
     return PCI_EAT_NONE;
 }

 # Default handler for events that do not have a corresponding plugin
 # method defined.
 sub _default {
     my ($self, $irc, $event) = splice @_, 0, 3;

     print "Default called for $event\n";

     # Return an exit code
     return PCI_EAT_NONE;
 }

Plugins can even embed their own POE sessions if they need to do fancy stuff. Below is a template for a plugin which does just that.

 package POE::Plugin::Template;

 use POE;
 use POE::Component::IRC::Plugin qw( :ALL );

 sub new {
     my $package = shift;
     my $self = bless {@_}, $package;
     return $self;
 }

 sub PCI_register {
     my ($self, $irc) = splice @_, 0, 2;

     # We store a ref to the $irc object so we can use it in our
     # session handlers.
     $self->{irc} = $irc;

     $irc->plugin_register( $self, 'SERVER', qw(blah blah blah) );

     POE::Session->create(
         object_states => [
             $self => [qw(_start _shutdown)],
         ],
     );

     return 1;
 }

 sub PCI_unregister {
     my ($self, $irc) = splice @_, 0, 2;
     # Plugin is dying make sure our POE session does as well.
     $poe_kernel->call( $self->{SESSION_ID} => '_shutdown' );
     delete $self->{irc};
     return 1;
 }

 sub _start {
     my ($kernel, $self) = @_[KERNEL, OBJECT];
     $self->{SESSION_ID} = $_[SESSION]->ID();
     # Make sure our POE session stays around. Could use aliases but that is so messy :)
     $kernel->refcount_increment( $self->{SESSION_ID}, __PACKAGE__ );
     return;
 }

 sub _shutdown {
     my ($kernel, $self) = @_[KERNEL, OBJECT];
     $kernel->alarm_remove_all();
     $kernel->refcount_decrement( $self->{SESSION_ID}, __PACKAGE__ );
     return;
 }

EVENT TYPES

 sub S_kick {}

 001
 socketerr
 connected
 plugin_del
 ...

 sub U_kick {}

 kick
 dcc_chat
 ison
 privmsg
 ...

 dcc        - $nick, $type, $file, $blocksize, $timeout
 dcc_accept - $cookie, $myfile
 dcc_resume - $cookie
 dcc_chat   - $cookie, @lines
 dcc_close  - $cookie

 sub _default {
     my ($self, $irc, $event) = splice @_, 0, 3;

     # $event will be something like S_public or U_dcc, etc.
     return PCI_EAT_NONE;
 }

EXIT CODES

EXPORTS

SEE ALSO

Object::Pluggable

Object::Pluggable::Pipeline

POE::Session

AUTHOR