Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/maverick

Perl Mojo::IRC Bot framework
https://github.com/grinnz/maverick

Last synced: 2 months ago
JSON representation

Perl Mojo::IRC Bot framework

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



Bot::Maverick - Mojo::IRC Bot framework



=head1 SYNOPSIS



  use Bot::Maverick;

  

  my $bot = Bot::Maverick->new(

    name => 'MyIRCBot',

    networks => {

      libera => {

        class => 'Libera',

        irc => { server => 'irc.libera.chat' },

      },

    },

  );

  

  $bot->start;



=head1 DESCRIPTION



L is an IRC bot framework built on L that supports

connecting to multiple networks and is designed to be configurable and

customizable via plugins. A core set of plugins is included from

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



=head1 CONFIGURATION



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



=head2 main



=head2 irc



=head2 network



=head2 channels



=head2 users



=head2 commands



=head2 apis



=head1 NETWORKS



IRC networks are represented by L (or subclassed)

objects that handle all communication with that network. Networks can be

specified in the bot's constructor, or added later with the L"network">

method.



=head1 PLUGINS



Plugins are L objects that compose the role L. They

are registered by calling the required method C 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.



=head1 COMMANDS



Commands are represented by L 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.



=head1 HOOKS



Hooks are subroutines which are run whenever a specific action occurs. They are

a powerful way to add global functionality.



=head2 start



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



Emitted when the bot is started.



=head2 stop



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



Emitted when the bot is stopped.



=head2 reload



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



Emitted when the bot is reloaded.



=head2 privmsg



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



The C hook is called whenever the bot receives a channel or private

message ("privmsg") from an IRC user. The callback will receive the

L object and the L object containing the

message details.



=head2 before_command



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



The C hook is called before a recognized command is executed.

The callback will receive the L object and the

L object containing the message details.



=head2 after_command



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



The C hook is called after a command has been executed. The

callback will receive the L object and the

L object containing the message details.



=head1 METHODS



=head2 new



Constructs a new L object instance. Accepts values for the following

attributes:



=over



=item name



  name => 'Botzilla',



Name for the bot, defaults to C. 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

C will (by default) use the configuration file C, network

configuration files CnetworkE.conf>, and database file

C.



=item 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 C (defaults to L)

and configuration for the network. The C will be appended to

C if it does not contain C<::>.



=item 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 C if they do not contain C<::>. 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 L for documentation on

Maverick plugins.



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

C attribute.



=item config_dir



  config_dir => "$HOME/.mybot",



Directory to store configuration and other files. Defaults to current

directory.



=item config_file



  config_file => 'myconfig.conf',



Filename for main configuration file. Defaults to bot's name, lowercased and

appended with C<.conf>. Network configuration filenames default to bot's name,

lowercased and appended with lowercased C<-EnetworkE.conf>.



=item storage_file



  storage_file => 'mystuff.db',



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

appended with C<.db>.



=item 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 C, C, C,

C, and C methods, such as L. Defaults to logging to

the file specified by the configuration C, or STDERR otherwise.



=back



=head2 start



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

to stop.



=head2 stop



Disconnect from all networks and stop the bot.



=head2 reload



Reloads configuration and reopens log handles.



=head2 add_network



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



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



=head2 add_plugin



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



Registers a plugin with optional hashref of parameters to pass to the plugin's

C method. See L"PLUGINS">.



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

L"AUTOLOAD">.



=head2 has_helper



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



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

available.



=head2 add_command



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

  $bot = $bot->add_command(...);



Adds a L to the bot, or passes the arguments to

construct a new L and add it to the bot. See

L"COMMANDS">.



=head2 get_command



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



Returns the L object representing the command, or

C if the command does not exist.



=head2 get_commands_by_prefix



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



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



=head2 remove_command



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



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



=head2 loop



  my $loop = $bot->loop;



Returns the L singleton used for the bot's operation.



=head2 new_future



  my $future = $bot->new_future;



Returns a L initialized with the L singleton.



=head2 timer_future



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



Returns a L initialized with the L singleton, which

will be set to done after the specified delay in seconds.



=head2 adopt_future



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



Stores a reference to the passed L object which will be cleared once

the future is ready. Stored futures will be cancelled if the bot is stopped.



=head2 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 L request and returns a L

that will be set to failed on connection or HTTP error, and otherwise will be

set to done with the L. The first argument can

optionally be a request method (defaults to C), and the remaining

arguments are passed to L.



=head2 fork_call



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



Runs a code ref in a forked process using L

and returns a L that will be set to failed if the code throws an

exception, and otherwise will be set to done with the returned values.



=head1 BUGS



Report any issues on the public bugtracker.



=head1 AUTHOR



Dan Book, C



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



=head1 SEE ALSO



L, L, L



=cut