.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "POE::Component::IRC::Plugin 3pm" .TH POE::Component::IRC::Plugin 3pm "2018-01-01" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" POE::Component::IRC::Plugin \- Provides plugin constants and documentation for POE::Component::IRC .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # A simple ROT13 \*(Aqencryption\*(Aq 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, \*(AqSERVER\*(Aq, qw(public) ); \& return 1; \& } \& \& # This is method is mandatory but we don\*(Aqt 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\*(Aqt want other plugins to process this \& return PCI_EAT_PLUGIN; \& } \& \& # Default action is to allow other plugins to process it. \& return PCI_EAT_NONE; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" 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. .SH "HISTORY" .IX Header "HISTORY" Certain individuals in #PoE on MAGNet said we didn't need to bloat the PoCo-IRC code... .PP BinGOs, the current maintainer of the module, and I heartily agreed that this is a wise choice. .PP One example: .PP 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... .PP Here comes plugins to the rescue :) .PP 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. .PP Yes, there are changes that most of us will moan when we go update our bots to use the new \f(CW$irc\fR 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? :) .SH "DESCRIPTION" .IX Header "DESCRIPTION" The plugin system works by letting coders hook into the two aspects of PoCo-IRC: .IP "\(bu" 4 Data received from the server .IP "\(bu" 4 User commands about to be sent to the server .PP The goal of this system is to make PoCo-IRC so easy to extend, enabling it to Take Over The World! *Just Kidding* .PP The general architecture of using the plugins should be: .PP .Vb 4 \& # 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( \*(AqExamplePlugin\*(Aq, $plugin ); \& \& # OOPS, we lost the plugin object! \& my $pluginobj = $irc\->plugin_get( \*(AqExamplePlugin\*(Aq ); \& \& # 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( \*(AqExamplePlugin\*(Aq ); .Ve .PP The plugins themselves will conform to the standard \s-1API\s0 described here. What they can do is limited only by imagination and the \s-1IRC RFC\s0's ;) .PP .Vb 2 \& # 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, \*(AqSERVER\*(Aq, 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 = \*(Aqfrobnicate!\*(Aq; \& \& # 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\en"; \& \& # Return an exit code \& return PCI_EAT_NONE; \& } .Ve .PP Plugins can even embed their own \s-1POE\s0 sessions if they need to do fancy stuff. Below is a template for a plugin which does just that. .PP .Vb 1 \& 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, \*(AqSERVER\*(Aq, 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} => \*(Aq_shutdown\*(Aq ); \& 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; \& } .Ve .SH "EVENT TYPES" .IX Header "EVENT TYPES" .SS "\s-1SERVER\s0 hooks" .IX Subsection "SERVER hooks" 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 PoCo-IRC docs for more information. .PP \&\s-1NOTE:\s0 Server methods are identified in the plugin namespace by the subroutine prefix of S_*. I.e. an irc_kick event handler would be: .PP .Vb 1 \& sub S_kick {} .Ve .PP 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. .PP They are required to return one of the exit codes so PoCo-IRC will know what to do. .PP \fINames of potential hooks\fR .IX Subsection "Names of potential hooks" .PP .Vb 5 \& 001 \& socketerr \& connected \& plugin_del \& ... .Ve .PP Keep in mind that they are always lowercased. Check out the \&\s-1OUTPUT EVENTS\s0 section of POE::Component::IRC's documentation for the complete list of events. .SS "\s-1USER\s0 hooks" .IX Subsection "USER hooks" These type of hooks have two different argument formats. They are split between data sent to the server, and data sent through \s-1DCC\s0 connections. .PP \&\s-1NOTE:\s0 User methods are identified in the plugin namespace by the subroutine prefix of U_*. I.e. an irc_kick event handler would be: .PP .Vb 1 \& sub U_kick {} .Ve .PP Hooks that are targeted to user data have it a little harder. They will receive a reference to the raw line about to be sent out. That means they will have to parse it in order to extract data out of it. .PP The reasoning behind this is that it is not possible to insert hooks in every method in the \f(CW$irc\fR object, as it will become unwieldy and not allow inheritance to work. .PP The \s-1DCC\s0 hooks have it easier, as they do not interact with the server, and will receive references to the arguments specified in the \s-1DCC\s0 plugin documentation regarding dcc commands. .PP \fINames of potential hooks\fR .IX Subsection "Names of potential hooks" .PP .Vb 5 \& kick \& dcc_chat \& ison \& privmsg \& ... .Ve .PP Keep in mind that they are always lowercased, and are extracted from the raw line about to be sent to the irc server. To be able to parse the raw line, some \&\s-1RFC\s0 reading is in order. These are the \s-1DCC\s0 events that are not given a raw line, they are: .PP .Vb 5 \& dcc \- $nick, $type, $file, $blocksize, $timeout \& dcc_accept \- $cookie, $myfile \& dcc_resume \- $cookie \& dcc_chat \- $cookie, @lines \& dcc_close \- $cookie .Ve .SS "_default" .IX Subsection "_default" If a plugin has registered for an event but doesn't have a hook method defined for ir, component will attempt to call a plugin's \f(CW\*(C`_default\*(C'\fR method. The first parameter after the plugin and irc objects will be the handler name. .PP .Vb 2 \& sub _default { \& my ($self, $irc, $event) = splice @_, 0, 3; \& \& # $event will be something like S_public or U_dcc, etc. \& return PCI_EAT_NONE; \& } .Ve .PP The \f(CW\*(C`_default\*(C'\fR handler is expected to return one of the exit codes so PoCo-IRC will know what to do. .SH "EXIT CODES" .IX Header "EXIT CODES" .SS "\s-1PCI_EAT_NONE\s0" .IX Subsection "PCI_EAT_NONE" This means the event will continue to be processed by remaining plugins and finally, sent to interested sessions that registered for it. .SS "\s-1PCI_EAT_CLIENT\s0" .IX Subsection "PCI_EAT_CLIENT" 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 nothing will be sent out on the wire if it was an \s-1USER\s0 event, beware! .SS "\s-1PCI_EAT_PLUGIN\s0" .IX Subsection "PCI_EAT_PLUGIN" This means the event will not be processed by remaining plugins, it will go straight to interested sessions. .SS "\s-1PCI_EAT_ALL\s0" .IX Subsection "PCI_EAT_ALL" This means the event will be completely discarded, no plugin or session will see it. This means nothing will be sent out on the wire if it was an \s-1USER\s0 event, beware! .SH "EXPORTS" .IX Header "EXPORTS" Exports the return constants for plugins to use in \f(CW@EXPORT_OK\fR Also, the ':ALL' tag can be used to get all of them. .SH "SEE ALSO" .IX Header "SEE ALSO" POE::Component::IRC .PP Object::Pluggable .PP Object::Pluggable::Pipeline .PP POE::Session .SH "AUTHOR" .IX Header "AUTHOR" Apocalypse