1POE::Component::IRC::PlUusgeirn:C:oBnottrCiobmumtaePndOdE(P:3e:)rClomDpoocnuemnetn:t:aItRiCo:n:Plugin::BotCommand(3)
2
6 POE::Component::IRC::Plugin::BotCommand - A PoCo-IRC plugin which
7 handles commands issued to your bot
8
10 use POE;
11 use POE::Component::Client::DNS;
12 use POE::Component::IRC;
13 use POE::Component::IRC::Plugin::BotCommand;
14 my @channels = ('#channel1', '#channel2');
16 my $dns = POE::Component::Client::DNS->spawn();
17 my $irc = POE::Component::IRC->spawn(
18 nick => 'YourBot',
19 server => 'some.irc.server',
20 );
21 POE::Session->create(
23 package_states => [
24 main => [ qw(_start irc_001 irc_botcmd_slap irc_botcmd_lookup dns_response) ],
25 ],
26 );
27 $poe_kernel->run();
29 sub _start {
31 $irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
32 Commands => {
33 slap => 'Takes one argument: a nickname to slap.',
34 lookup => 'Takes two arguments: a record type (optional), and a host.',
35 }
36 ));
37 $irc->yield(register => qw(001 botcmd_slap botcmd_lookup));
38 $irc->yield(connect => { });
39 }
40 # join some channels
42 sub irc_001 {
43 $irc->yield(join => $_) for @channels;
44 return;
45 }
46 # the good old slap
48 sub irc_botcmd_slap {
49 my $nick = (split /!/, $_[ARG0])[0];
50 my ($where, $arg) = @_[ARG1, ARG2];
51 $irc->yield(ctcp => $where, "ACTION slaps $arg");
52 return;
53 }
54 # non-blocking dns lookup
56 sub irc_botcmd_lookup {
57 my $nick = (split /!/, $_[ARG0])[0];
58 my ($where, $arg) = @_[ARG1, ARG2];
59 my ($type, $host) = $arg =~ /^(?:(\w+) )?(\S+)/;
60 my $res = $dns->resolve(
62 event => 'dns_response',
63 host => $host,
64 type => $type,
65 context => {
66 where => $where,
67 nick => $nick,
68 },
69 );
70 $poe_kernel->yield(dns_response => $res) if $res;
71 return;
72 }
73 sub dns_response {
75 my $res = $_[ARG0];
76 my @answers = map { $_->rdatastr } $res->{response}->answer() if $res->{response};
77 $irc->yield(
79 'notice',
80 $res->{context}->{where},
81 $res->{context}->{nick} . (@answers
82 ? ": @answers"
83 : ': no answers for "' . $res->{host} . '"')
84 );
85 return;
87 }
88
90 POE::Component::IRC::Plugin::BotCommand is a POE::Component::IRC
91 plugin. It provides you with a standard interface to define bot
92 commands and lets you know when they are issued. Commands are accepted
93 as channel or private messages.
94 The plugin will respond to the 'help' command by default, listing
96 available commands and information on how to use them. However, if you
97 add a help command yourself, that one will be used instead.
98
100 "new"
101 'Commands', a hash reference, with your commands as keys, and usage
102 information as values. If the usage string contains newlines, the
103 plugin will send one message for each line.
104 If a command's value is a HASH ref like this:
106 $irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
108 Commands => {
109 slap => {
110 info => 'Slap someone',
111 args => [qw(nickname)],
112 nickname => 'nickname to slap'
113 }
114 }
115 ));
116 The args array reference is than used to validate number of arguments
118 required and to name arguments passed to event handler. Help is than
119 generated from "info" and other hash keys which represent arguments
120 (they are optional).
121 An optional "handler" key can be specified inside the HASH ref to
123 override the event handler. The irc_botcmd_ prefix is not
124 automatically prepended to the handler name when overriding it.
125 An optional "aliases" key can be specified inside the HASH ref
127 containing a array ref with alias names. The aliases can be specified
128 for help and to run the command.
129 Accepting commands
131 'In_channels', a boolean value indicating whether to accept commands in
133 channels. Default is true.
134 'In_private', a boolean value indicating whether to accept commands in
136 private. Default is true.
137 'Addressed', requires users to address the bot by name in order to
139 issue commands. Default is true.
140 'Prefix', a string which all commands must be prefixed with (except in
142 channels when 'Addressed' is true). Default is '!'. You can set it to
143 '' to allow bare commands.
144 'Bare_private', a boolean value indicating whether bare commands
146 (without the prefix) are allowed in private messages. Default is false.
147 Authorization
149 'Auth_sub', a subroutine reference which, if provided, will be called
151 for every command. The subroutine will be called in list context. If
152 the first value returned is true, the command will be processed as
153 normal. If the value is false, then no events will be generated, and an
154 error message will possibly be sent back to the user.
155 You can override the default error message by returning a second value,
157 an array reference of (zero or more) strings. Each string will be sent
158 as a message to the user.
159 Your subroutine will be called with the following arguments:
161 1. The IRC component object
163 2. The nick!user@host of the user
164 3. The place where the command was issued (the nickname of the user if
165 it was in private)
166 4. The name of the command
167 5. The command argument string
168 'Ignore_unauthorized', if true, the plugin will ignore unauthorized
170 commands, rather than printing an error message upon receiving them.
171 This is only relevant if 'Auth_sub' is also supplied. Default is false.
172 Help Command
174 'Help_sub', a subroutine reference which, if provided, will be called
176 upon the end of the predefined help command. The subroutine will be
177 called in list context.
178 Your subroutine will be called with the following arguments:
180 1. The IRC component object
182 2. The command.
183 3. The resolved command(after alias processing).
184 4. The arguments.
185 5. The generated help text as array.
186 Miscellaneous
188 'Ignore_unknown', if true, the plugin will ignore undefined commands,
190 rather than printing a help message upon receiving them. Default is
191 false.
192 'Method', how you want help messages to be delivered. Valid options are
194 'notice' (the default) and 'privmsg'.
195 'Eat', set to true to make the plugin hide "irc_public" events from
197 other plugins when they look like commands. Probably only useful when a
198 'Prefix' is defined. Default is false.
199 Returns a plugin object suitable for feeding to POE::Component::IRC's
201 "plugin_add" method.
202 "add"
204 Adds a new command. Takes two arguments, the name of the command, and a
205 string or hash reference containing its usage information (see "new").
206 Returns false if the command has already been defined or no info or
207 arguments are provided, true otherwise.
208 "remove"
210 Removes a command. Takes one argument, the name of the command. Returns
211 false if the command wasn't defined to begin with, true otherwise.
212 "list"
214 Takes no arguments. Returns a list of key/value pairs, the keys being
215 the command names and the values being the usage strings or hash
216 references.
217 "resolve_alias"
219 Takes one argument, a string to match against command aliases, if no
220 matching command can be found undef is returned.
221
223 "irc_botcmd_*"
224 You will receive an event like this for every valid command issued.
225 E.g. if 'slap' were a valid command, you would receive an
226 "irc_botcmd_slap" event every time someone issued that command. It
227 receives the following arguments:
228 • "ARG0": the nick!hostmask of the user who issued the command.
230 • "ARG1" is the name of the channel in which the command was issued,
232 or the sender's nickname if this was a private message.
233 • "ARG2": a string of arguments to the command, or hash reference
235 with arguments in case you defined command along with arguments, or
236 undef if there were no arguments
237
239 Hinrik Örn Sigurðsson, hinrik.sig@gmail.com
240perl v5.32.1 202P1O-E0:1:-C2o7mponent::IRC::Plugin::BotCommand(3)