1POE::Component::IRC::PlUusgeirn:C:oBnottrCiobmumtaePndOdE(P:3e:)rClomDpoocnuemnetn:t:aItRiCo:n:Plugin::BotCommand(3)
2
3
4

NAME

6       POE::Component::IRC::Plugin::BotCommand - A PoCo-IRC plugin which
7       handles commands issued to your bot
8

SYNOPSIS

10        use POE;
11        use POE::Component::Client::DNS;
12        use POE::Component::IRC;
13        use POE::Component::IRC::Plugin::BotCommand;
14
15        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
22        POE::Session->create(
23            package_states => [
24                main => [ qw(_start irc_001 irc_botcmd_slap irc_botcmd_lookup dns_response) ],
25            ],
26        );
27
28        $poe_kernel->run();
29
30        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
41        # join some channels
42        sub irc_001 {
43            $irc->yield(join => $_) for @channels;
44            return;
45        }
46
47        # 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
55        # 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
61            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
74        sub dns_response {
75            my $res = $_[ARG0];
76            my @answers = map { $_->rdatastr } $res->{response}->answer() if $res->{response};
77
78            $irc->yield(
79                'notice',
80                $res->{context}->{where},
81                $res->{context}->{nick} . (@answers
82                    ? ": @answers"
83                    : ': no answers for "' . $res->{host} . '"')
84            );
85
86            return;
87        }
88

DESCRIPTION

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
95       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

METHODS

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
105       If a command's value is a HASH ref like this:
106
107            $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
117       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
122       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
126       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
130       Accepting commands
131
132       'In_channels', a boolean value indicating whether to accept commands in
133       channels. Default is true.
134
135       'In_private', a boolean value indicating whether to accept commands in
136       private. Default is true.
137
138       'Addressed', requires users to address the bot by name in order to
139       issue commands. Default is true.
140
141       '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
145       'Bare_private', a boolean value indicating whether bare commands
146       (without the prefix) are allowed in private messages. Default is false.
147
148       Authorization
149
150       '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
156       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
160       Your subroutine will be called with the following arguments:
161
162       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
169       '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
173       Help Command
174
175       '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
179       Your subroutine will be called with the following arguments:
180
181       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
187       Miscellaneous
188
189       '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
193       'Method', how you want help messages to be delivered. Valid options are
194       'notice' (the default) and 'privmsg'.
195
196       '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
200       Returns a plugin object suitable for feeding to POE::Component::IRC's
201       "plugin_add" method.
202
203   "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
209   "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
213   "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
218   "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

OUTPUT EVENTS

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
229       •   "ARG0": the nick!hostmask of the user who issued the command.
230
231       •   "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
234       •   "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

AUTHOR

239       Hinrik Örn Sigurðsson, hinrik.sig@gmail.com
240
241
242
243perl v5.32.1                      202P1O-E0:1:-C2o7mponent::IRC::Plugin::BotCommand(3)
Impressum