=head2 NAME
Bot::BasicBot::CommandBot
=head2 DESCRIPTION
Simple declarative syntax for an IRC bot that responds to commands.
=head2 SYNOPSIS
command hello => sub {
my ($self, $cmd, $message) = @_;
return "Hello world!"
}
command qr/^a+/ => sub {
return 'a' x rand 6;
}
sub _auto {
return "hi" if shift =~ /hello/;
}
=head2 CONSTRUCTION
Construction of the bot is the same as Bot::BasicBot, as is running it.
CommandBot takes two new options to C<new>:
=over
=item C<trigger>
If provided, this string will be required at the start of any message for it to
be considered a bot command. Common examples include C<!>, C<?> and C<@>.
This string will be removed from the command.
=item C<address>
If provided and a true value, the bot will only respond if directly addressed.
"Addressed" is actually defined by Bot::BasicBot, so if the bot is not
addressed, nothing will happen.
=back
Despite the above, the C<_auto> method will always be called, regardless.
If both options are provided, the bot must be addressed I<and> the command must
be prefixed with the trigger for a response to happen.
=head2 COMMANDS
A command is considered to be the first contiguous string of non-whitespace
after the preprocessing done by the address and trigger detection.
!command text text
Commandbot: command text text
Commandbot: !command text text
In all these cases, C<command> is the B<command>. C<text text> is then a single string, regardless of how long it is.
This is the B<message>.
The command string is then looked up in the list of declared commands. If it is
exactly equal to a command declared as a string, or matches a command declared
with a regex, the associated subref is run.
If it does not match, the bot says "What is $command?".
=head2 DECLARING COMMANDS
=head3 command
The C<command> function declares a command. It accepts either a string or a
regex and a subref. The subref will be called whenever the bot is activated
with a matching string.
The subref receives C<$self>, C<$cmd> and C<$message>: The bot object, the
matched command and the rest of the message.
command qr/^./ => sub {
...
};
The return value from this subref is then spoken in the same place the
original message was received.
C<$self> is an instance of Bot::BasicBot::CommandBot, which of course extends
Bot::BasicBot, and therefore all things that can do, your bot can do.
=head3 declare_command
This function is called by C<command>. It is a package method. It takes the
same arguments as C<command>, but it is called on a package:
__PACKAGE__->declare_command(qr/^./, sub { ... });
This can be helpful if you don't want to put all your commands in the same
module - you can declare them all on the same package.
=head3 _auto
C<_auto> is a plain method on your bot. It is called before anything else is
done, and if it returns anything, that is said and nothing else is done.
As mentioned this is a normal method, so it receives C<$self> first, and then
C<$message>. There is no C<$cmd> because no command was involved.
This sub is intended as a hook for you to perform any actions necessary as a
result of people talking in general, or for bots that think they're human and
want to join in.
It is called in list context, so remember not to return undef.
