File Coverage

blib/lib/POE/Component/Server/IRC/Plugin.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package POE::Component::Server::IRC::Plugin;
2             our $AUTHORITY = 'cpan:BINGOS';
3             $POE::Component::Server::IRC::Plugin::VERSION = '1.60'; # TRIAL
4 182     182   964109 use strict;
  182         542  
  182         6448  
5 182     182   1085 use warnings FATAL => 'all';
  182         452  
  182         7803  
6              
7             require Exporter;
8 182     182   1063 use base qw(Exporter);
  182         425  
  182         28323  
9             our @EXPORT_OK = qw(PCSI_EAT_NONE PCSI_EAT_CLIENT PCSI_EAT_PLUGIN PCSI_EAT_ALL);
10             our %EXPORT_TAGS = ( ALL => [@EXPORT_OK] );
11              
12             use constant {
13 182         23378 PCSI_EAT_NONE => 1,
14             PCSI_EAT_CLIENT => 2,
15             PCSI_EAT_PLUGIN => 3,
16             PCSI_EAT_ALL => 4,
17 182     182   1605 };
  182         3139  
18              
19             1;
20              
21             =encoding utf8
22              
23             =head1 NAME
24              
25             POE::Component::Server::IRC::Plugin - Provides plugin documentation for
26             POE::Component::Server::IRC.
27              
28             =head1 DESCRIPTION
29              
30             This is the document coders/users should refer to when using/developing
31             plugins for POE::Component::Server::IRC.
32              
33             The plugin system works by letting coders hook into aspects of
34             POE::Component::Server::IRC::Backend. More details are found in the docs
35             for L.
36              
37             The general architecture of using the plugins should be:
38              
39             # Import the stuff...
40             use POE;
41             use POE::Component::Server::IRC::Backend;
42             use POE::Component::Server::IRC::Plugin::ExamplePlugin;
43              
44             # Create our session here
45             POE::Session->create( ... );
46              
47             # Create the IRC session here
48             my $irc = POE::Component::Server::IRC::Backend->spawn() or die 'Nooo!';
49              
50             # Create the plugin
51             # Of course it could be something like $plugin = MyPlugin->new();
52             my $plugin = POE::Component::Server::IRC::Plugin::ExamplePlugin->new( ... );
53              
54             # Hook it up!
55             $irc->plugin_add( 'ExamplePlugin', $plugin );
56              
57             # OOPS, we lost the plugin object!
58             my $pluginobj = $irc->plugin_get( 'ExamplePlugin' );
59              
60             # We want a list of plugins and objects
61             my $hashref = $irc->plugin_list();
62              
63             # Oh! We want a list of plugin aliases.
64             my @aliases = keys %{ $irc->plugin_list() };
65              
66             # Ah, we want to remove the plugin
67             $plugin = $irc->plugin_del( 'ExamplePlugin' );
68              
69             The plugins themselves will conform to the standard API described here. What
70             they can do is limited only by imagination and the IRC RFC's ;)
71              
72             package POE::Component::Server::IRC::ExamplePlugin;
73              
74             # Import the constants
75             use POE::Component::Server::IRC::Plugin qw( :ALL );
76              
77             # Our constructor
78             sub new {
79             # ...
80             }
81              
82             # Required entry point for POE::Component::Server::IRC::Backend
83             sub PCSI_register {
84             my ($self, $irc) = @_;
85             # Register events we are interested in
86             $irc->plugin_register( $self, 'SERVER', qw(connection) );
87              
88             # Return success
89             return 1;
90             }
91              
92             # Required exit point for PoCo-Server-IRC
93             sub PCSI_unregister {
94             my ($self, $irc) = @_;
95              
96             # PCSIB will automatically unregister events for the plugin
97              
98             # Do some cleanup...
99              
100             # Return success
101             return 1;
102             }
103              
104             # Registered events will be sent to methods starting with IRC_
105             # If the plugin registered for SERVER - irc_355
106             sub IRCD_connection {
107             my ($self, $irc, $line) = @_;
108              
109             # Remember, we receive pointers to scalars, so we can modify them
110             $$line = 'frobnicate!';
111              
112             # Return an exit code
113             return PCSI_EAT_NONE;
114             }
115              
116             # Default handler for events that do not have a corresponding
117             # plugin method defined.
118             sub _default {
119             my ($self, $irc, $event) = splice @_, 0, 3;
120              
121             print "Default called for $event\n";
122              
123             # Return an exit code
124             return PCSI_EAT_NONE;
125             }
126              
127             =head2 Pipeline
128              
129             The plugins are given priority on a first come, first serve basis.
130             Therefore, plugins that were added before others have the first shot at
131             processing events. See
132             L for details.
133              
134             my $pipeline = $ircd->pipeline();
135              
136             =head1 EVENTS
137              
138             =head2 SERVER hooks
139              
140             Hooks that are targeted toward data received from the server will get the
141             exact same arguments as if it was a normal event, look at the
142             POE::Component::Server::IRC::Backend docs for more information.
143              
144             B Server methods are identified in the plugin namespace by the
145             subroutine prefix of IRCD_*. I.e. an ircd_cmd_kick event handler would be:
146              
147             sub IRCD_cmd_kick {}
148              
149             The only difference is instead of getting scalars, the hook will get a
150             reference to the scalar, to allow it to mangle the data. This allows the
151             plugin to modify data *before* they are sent out to registered sessions.
152              
153             They are required to return one of the exit codes so
154             POE::Component::Server::IRC::Backend will know what to do.
155              
156             Names of potential hooks:
157              
158             socketerr
159             connected
160             plugin_del
161             ...
162              
163             Keep in mind that they are always lowercased, check out the
164             POE::Component::Server::IRC documentation.
165              
166             =head2 C<_default>
167              
168             If a plugin doesn't have a specific hook method defined for an event, the
169             component will attempt to call a plugin's C<_default> method. The first
170             parameter after the plugin and irc objects will be the handler name.
171              
172             sub _default {
173             my ($self, $irc, $event) = splice @_, 0, 3;
174             return PCSI_EAT_NONE;
175             }
176              
177             The C<_default> handler is expected to return one of the exit codes so
178             POE::Component::Server::IRC::Backend will know what to do.
179              
180             =head1 EXPORTS
181              
182             The following constants are exported on demand.
183              
184             =head2 C
185              
186             This means the event will continue to be processed by remaining plugins and
187             finally, sent to interested sessions that registered for it.
188              
189             =head2 C
190              
191             This means the event will continue to be processed by remaining plugins but
192             it will not be sent to any sessions that registered for it.
193              
194             =head2 C
195              
196             This means the event will not be processed by remaining plugins, it will go
197             straight to interested sessions.
198              
199             =head2 C
200              
201             This means the event will be completely discarded, no plugin or session
202             will see it.
203              
204             =head1 SEE ALSO
205              
206             L
207              
208             =cut