README.pod

NAME

Bot::Maverick - Mojo::IRC Bot framework

SYNOPSIS

use Bot::Maverick;

my $bot = Bot::Maverick->new(
  name => 'MyIRCBot',
  networks => {
    libera => {
      class => 'Libera',
      irc => { server => 'irc.libera.chat' },
    },
  },
);

$bot->start;

DESCRIPTION

Bot::Maverick is an IRC bot framework built on Mojo::IRC that supports connecting to multiple networks and is designed to be configurable and customizable via plugins. A core set of plugins is included from Bot::Maverick::Plugin::Core which includes basic administrative and configuration commands, and additional plugins can be registered that may implement any functionality from adding more commands to hooking into message events and more.

CONFIGURATION

Bot::Maverick is configured by INI files: one global configuration file and a network configuration file for each network it connects to. The global configuration file is used as a default configuration for each network. Any configuration specified in the constructor or when adding a network will be written to the configuration files, overriding existing configuration.

Configuration INI files are organized into sections, and all parameters must be within a section.

main

irc

network

channels

users

commands

apis

NETWORKS

IRC networks are represented by Bot::Maverick::Network (or subclassed) objects that handle all communication with that network. Networks can be specified in the bot's constructor, or added later with the "network" method.

PLUGINS

Plugins are Moo objects that compose the role Bot::Maverick::Plugin. They are registered by calling the required method register and may add commands, hooks, or anything else to the bot instance. A plugin may also register a method of its own as a "helper method" which then can be called on the bot instance from elsewhere. The plugin object is passed as the invocant of the registered helper method.

COMMANDS

Commands are represented by Bot::Maverick::Command objects which define the properties of the command and a callback "on_run" that is called when the command is invoked by a IRC user.

HOOKS

Hooks are subroutines which are run whenever a specific action occurs. They are a powerful way to add global functionality.

start

$bot->on(start => sub { my ($bot) = @_; ... });

Emitted when the bot is started.

stop

$bot->on(stop => sub { my ($bot) = @_; ... });

Emitted when the bot is stopped.

reload

$bot->on(reload => sub { my ($bot) = @_; ... });

Emitted when the bot is reloaded.

privmsg

$bot->on(privmsg => sub { my ($bot, $m) = @_; ... });

The privmsg hook is called whenever the bot receives a channel or private message ("privmsg") from an IRC user. The callback will receive the Bot::Maverick object and the Bot::Maverick::Message object containing the message details.

before_command

$bot->on(before_command => sub { my ($bot, $m) = @_; ... });

The before_command hook is called before a recognized command is executed. The callback will receive the Bot::Maverick object and the Bot::Maverick::Message object containing the message details.

after_command

$bot->on(after_command => sub { my ($bot, $m) = @_; ... });

The after_command hook is called after a command has been executed. The callback will receive the Bot::Maverick object and the Bot::Maverick::Message object containing the message details.

METHODS

new

Constructs a new Bot::Maverick object instance. Accepts values for the following attributes:

name

name => 'Botzilla',

Name for the bot, defaults to Maverick. The bot's name is used as a default nick for networks where it is not configured, as well as lowercased for the default filenames for configuration and other files. For example, a bot named Fred will (by default) use the configuration file fred.conf, network configuration files fred-<network>.conf, and database file fred.db.

networks

networks => { libera => { class => 'Libera', config => { debug => 1 } } },

Hash reference that must contain at least one network to connect to. Keys are names which will be used to identify the network as well as lowercased to define the default network configuration filename. Values are hash references containing an optional object class (defaults to Bot::Maverick::Network) and configuration for the network. The class will be appended to Bot::Maverick::Network:: if it does not contain ::.

plugins

plugins => [qw/DNS GeoIP/],
plugins => { Core => 0, DNS => { native => 0 }, GeoIP => 1 },

Plugins to register with the bot, specified as plugin class names, which are appended to Bot::Maverick::Plugin:: if they do not contain ::. May be specified as an array reference to simply include the list of plugins, or as a hash reference to configure the plugins. If the hash value is false, the plugin will be not be registered. If the value is a hash reference, it will be passed to the plugin's constructor. See Bot::Maverick::Plugin for documentation on Maverick plugins.

config

config => { debug => 1, irc => { nick => 'OtherGuy' } },

Global configuration that will override any defaults or existing global configuration file. To override configuration for a specific network, see the networks attribute.

config_dir

config_dir => "$HOME/.mybot",

Directory to store configuration and other files. Defaults to current directory.

config_file

config_file => 'myconfig.conf',

Filename for main configuration file. Defaults to bot's name, lowercased and appended with .conf. Network configuration filenames default to bot's name, lowercased and appended with lowercased -<network>.conf.

storage_file

storage_file => 'mystuff.db',

Filename for database storage file. Defaults to bot's name, lowercased and appended with .db.

logger

logger => Mojo::Log->new('/var/log/botstuff.log')->level('warn'),

Logger object that will be used for all debug, informational and warning output. Can be any type of logger that has debug, info, warn, error, and fatal methods, such as Mojo::Log. Defaults to logging to the file specified by the configuration logfile, or STDERR otherwise.

start

Start the bot and connect to configured networks. Blocks until the bot is told to stop.

stop

Disconnect from all networks and stop the bot.

reload

Reloads configuration and reopens log handles.

add_network

$bot = $bot->add_network(libera => { class => 'Libera' });

Adds a network for the bot to connect to. See "NETWORKS".

add_plugin

$bot = $bot->add_plugin(DNS => { native => 0 });

Registers a plugin with optional hashref of parameters to pass to the plugin's register method. See "PLUGINS".

add_helper

$bot = $bot->add_helper(DNS => 'dns_resolve');

Adds a helper method to the bot, so that it may be called on the bot via "AUTOLOAD".

has_helper

my $bool = $bot->has_helper('dns_resolve');

Returns a boolean value that is true if the specified helper method is available.

add_command

$bot = $bot->add_command(Bot::Maverick::Command->new(...));
$bot = $bot->add_command(...);

Adds a Bot::Maverick::Command to the bot, or passes the arguments to construct a new Bot::Maverick::Command and add it to the bot. See "COMMANDS".

get_command

my $command = $bot->get_command('say');

Returns the Bot::Maverick::Command object representing the command, or undef if the command does not exist.

get_commands_by_prefix

my $commands = $bot->get_commands_by_prefix('wo');

Returns an array reference of command objects matching a prefix, if any.

remove_command

$bot = $bot->remove_command('locate');

Removes a command from the bot by name if it exists.

loop

my $loop = $bot->loop;

Returns the Mojo::IOLoop singleton used for the bot's operation.

new_future

my $future = $bot->new_future;

Returns a Future::Mojo initialized with the Mojo::IOLoop singleton.

timer_future

my $future = $bot->timer_future(1);

Returns a Future::Mojo initialized with the Mojo::IOLoop singleton, which will be set to done after the specified delay in seconds.

adopt_future

$future = $bot->adopt_future($future);

Stores a reference to the passed Future object which will be cleared once the future is ready. Stored futures will be cancelled if the bot is stopped.

ua_request

my $future = $bot->ua_request($url);
my $future = $bot->ua_request(post => $url, {Authorization => 'open sesame'}, json => [1,2,3]);

Runs a non-blocking Mojo::UserAgent request and returns a Future::Mojo that will be set to failed on connection or HTTP error, and otherwise will be set to done with the Mojo::Message::Response. The first argument can optionally be a request method (defaults to get), and the remaining arguments are passed to Mojo::UserAgent.

fork_call

my $future = $bot->fork_call(sub { return 'foo' });

Runs a code ref in a forked process using Mojo::IOLoop::Subprocess::Sereal and returns a Future::Mojo that will be set to failed if the code throws an exception, and otherwise will be set to done with the returned values.

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book, dbook@cpan.org

COPYRIGHT AND LICENSE

Copyright 2015, Dan Book.

This library is free software; you may redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Bot::Maverick::Network, Bot::Maverick::Plugin, Mojo::IRC