NAME

Bot::BasicBot::CommandBot

DESCRIPTION

Simple declarative syntax for an IRC bot that responds to commands.

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/;
    }

CONSTRUCTION

Construction of the bot is the same as Bot::BasicBot, as is running it.

CommandBot takes two new options to new:

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 !, ? and @.

This string will be removed from the command.

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.

Despite the above, the _auto method will always be called, regardless.

If both options are provided, the bot must be addressed and the command must be prefixed with the trigger for a response to happen.

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, command is the command. text text is then a single string, regardless of how long it is. This is the 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?".

DECLARING COMMANDS

command

The 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 $self, $cmd and $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.

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

declare_command

This function is called by command. It is a package method. It takes the same arguments as 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.

_auto

_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 $self first, and then $message. There is no $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.

cpanm Bot::BasicBot::CommandBot

perl -MCPAN -e shell
install Bot::BasicBot::CommandBot