POE::Component::IRC::Plugin3pm

Usage

 # 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;
 }

Overview

POE::Component::IRC's plugin system has been released separately as Object::Pluggable. Gleaning at its documentation is advised. The rest of this document mostly describes aspects that are specific to POE::Component::IRC's use of Object::Pluggable.

Overview

The plugin system works by letting coders hook into the two aspects of PoCo-IRC:

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 status

Exports

Exports the return constants for plugins to use in @EXPORT_OK Also, the ':ALL' tag can be used to get all of them.