=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.