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 |