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 three new options to new:

bark

If true, the bot will ask "What is $cmd?" for any command for which no appropriate handler is found. If not, the bot will remain silent. This defaults to true.

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, autocommands 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.

sub import {
    my $caller = (caller)[0];
    $caller->declare_command(...);
}

autocommand

An autocommand will be processed regardless of whether the message was interpreted as a command or not.

autocommand => sub {
    my $self = shift;
    my $message = shift;
};

This 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 not generally considered sensible to return a value from autocommands, but if you wish to, be aware that the return value of autocommands is only spoken if an actual command does not say something. Also, the return values from all autocommands across all packages will be joined together

declare_autocommand

The equivalent of declare_command for autocommands. Lets you create an autocommand from a package besides one that extends the bot.

cpanm Bot::BasicBot::CommandBot

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