POE::Component::Server::IRC::Plugin - Provides plugin documentation for POE::Component::Server::IRC.

This is the document coders/users should refer to when using/developing plugins for POE::Component::Server::IRC.

The plugin system works by letting coders hook into aspects of POE::Component::Server::IRC::Backend. More details are found in the docs for Object::Pluggable.

The general architecture of using the plugins should be:

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

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

 # Create the IRC session here
 my $irc = POE::Component::Server::IRC::Backend->spawn() or die 'Nooo!';

 # Create the plugin
 # Of course it could be something like $plugin = MyPlugin->new();
 my $plugin = POE::Component::Server::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 ;)

 package POE::Component::Server::IRC::ExamplePlugin;

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

 # Our constructor
 sub new {
     # ...
 }

 # Required entry point for POE::Component::Server::IRC::Backend
 sub PCSI_register {
     my ($self, $irc) = @_;
         # Register events we are interested in
         $irc->plugin_register( $self, 'SERVER', qw(connection) );

         # Return success
         return 1;
     }

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

         # PCSIB 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 IRCD_connection {
         my ($self, $irc, $line) = @_;

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

         # Return an exit code
         return PCSI_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 PCSI_EAT_NONE;
     }

The plugins are given priority on a first come, first serve basis. Therefore, plugins that were added before others have the first shot at processing events. See Object::Pluggable::Pipeline for details.

 my $pipeline = $ircd->pipeline();

Hooks that are targeted toward data received from the server will get the exact same arguments as if it was a normal event, look at the POE::Component::Server::IRC::Backend docs for more information.

Note: Server methods are identified in the plugin namespace by the subroutine prefix of IRCD_*. I.e. an ircd_cmd_kick event handler would be:

 sub IRCD_cmd_kick {}

The only difference is instead of getting scalars, the hook will get a reference to the scalar, to allow it to mangle the data. This allows the plugin to modify data *before* they are sent out to registered sessions.

They are required to return one of the exit codes so POE::Component::Server::IRC::Backend will know what to do.

Names of potential hooks:

 socketerr
 connected
 plugin_del
 ...

Keep in mind that they are always lowercased, check out the POE::Component::Server::IRC documentation.

If a plugin doesn't have a specific hook method defined for an event, the component will attempt to call a plugin's _default method. The first parameter after the plugin and irc objects will be the handler name.

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

The _default handler is expected to return one of the exit codes so POE::Component::Server::IRC::Backend will know what to do.

The following constants are exported on demand.

This means the event will continue to be processed by remaining plugins and finally, sent to interested sessions that registered for it.

This means the event will continue to be processed by remaining plugins but it will not be sent to any sessions that registered for it.

This means the event will not be processed by remaining plugins, it will go straight to interested sessions.

This means the event will be completely discarded, no plugin or session will see it.

Object::Pluggable