ODCHBot is a bot written in Perl to provide additional features for OpenDCHub. The core bot provides an easily extensible framework for creating commands that range from simple text response to more complicated HTTP Requests, data storage and calculation.
Recommended version of OpenDCHub to use ODCHBot with is 0.7.16
The core code requires the following perl modules:
- DateTime
- DateTime::Duration
- DateTime::Format::Duration
- DBD::SQLite
- DBI
- Exporter
- FindBin
- Log::Dispatch::File
- Log::Log4perl
- Module::Load
- Number::Bytes::Human
- SQL::Abstract
- SQL::Abstract::Limit
- Storable
- Switch
- Text::Tabs
- Time::HiRes
- YAML
- YAML::AppConfig
- YAML::Syck
The commands packaged with the bot require the following perl modules:
- Date::Parse
- Data::Dumper;
- HTTP::Request::Common
- HTML::Strip
- HTML::Parser
- HTML::Entities
- IPC::System::Simple
- JSON
- List::Util
- LWP::Simple
- Mail::Sendmail
- Math::Round;
- Number::Format
- POSIX
- Scalar::Util
- String::Random
- Sys::Hostname
- WWW::TheMovieDB
- XML::Simple
The simplest way to install all of these is to use cpanimus:
curl -L http://cpanmin.us | perl - --sudo App::cpanminus
sudo cpan App::cpanminus
cpanm <modulename>
If any installs do not succeed, the following is recommended:
cpan install <module> #to get the download URL
wget <download URL>
gzip -d <package>.tar.gz
tar xvf <package>.tar
cd <package>
perl Makefile.pl
make
make install
Copy odchbot.yml.example to odchbot.yml and fill in settings in the db section depending on which db driver is being used. The bot is able to install itself into either a SQLite, MySQL, or PgSQL database although it is preconfigured for SQLite and no further changes are necessary if SQLite is to be used.
On first usage the bot will initialise a commands registry. Any commands stored in the commands directory will get loaded into the bot's memory whereupon they may be executed by users with adequate permissions.
There is a bitwise system with permissions whereby users are assigned a number when they first log in:
This number corresponds to the odch::type_get_types command that can be executed on a user. Further details may be found in DCBUser.pm with the important numbers being:
- ANONYMOUS = 4
- AUTHENTICATED = 8
- OPERATOR = 16
- ADMINISTRATOR = 32
These tie in exactly with permissions stated in the command YAML files meaning users of a permission not included in the YAML file will not be able to execute the command provided by the file.
The commands system with odchbot allows a plugable and hookable framework where new commands may be added or removed in order to fulfil needs. All commands should be stored in the 'commands' directory and consist of a YAML file for configuration and a pm file containing the command code.
The YAML file that holds all configuration for the command should be called [commandname].yml and be structured as follows (taken from tell.yml):
name: tell
description: Allows users to leave messages for other users. Usage: -tell <user> <message>
required: 0
system: 0
permissions:
- ANONYMOUS
- AUTHENTICATED
- OPERATOR
- ADMINISTRATOR
hooks:
- postlogin
- line
The name specified in the YAML file should match the filename of the command. This is what the user will type in to trigger the command. A description for the command should also be included and should describe functionality and usage of the command. Due to storage specifications, the name of the command may be no longer than 30 characters and the description may be no longer than 255 characters. Required commands are not allowed to be disabled by the bot and usually form some kind of key functionality. System commands are those prepackaged with the bot. Permssions follows the core permission system with only those users who have matching permissions being able to execute the command. NB the command will still run on hooks and affect users despite their permission level. It is only direct calling of the command in chat that is affected by the permission configuration. hooks defines which hooks the commands are triggered on in conjunction with the main command call. hooks should be an array with a new hook on each line, in this case tell will be triggered by postlogin and line hooks.
The file containing the command code should be named .pm
The command file should, at the very least define a main{} subroutine. This is the subroutine that will fire when a user executes the command via chat. Any hooks that are defined will allow the subroutine named after the hook to be called. For example, in the tell command there are subroutines for main, postlogin and line.
main {} is executed when a user calls -tell from chat
postlogin {} is called after a user is successfully validated
line{} runs with every chatline.
Access is granted to the following globals when modules are loaded and these may be used within the commands:
DCBSettings::cwd- current working directoryDCBSettings::config- hub/bot configDCBDatabase::dbh- db handle (likely unused)DCBCommon::registry- commands registryDCBUser::userlist- all usersDCBCommon::COMMON- Miscellaneous global for all modules to use
When processing all commands, there are three variables provided for use by the command.
my $command = shift;
my $user = shift;
my $chat = shift;
The first is the name of the command, passed through from commands_run_commands{}, the second is the $user object and the third is any additional chatlines that were sent as parameters to the command.
-coin Shall I go out today?
The $user object of the user calling the command is provided to all commands as the 2nd parameter. This may be used in any way and provides all of the properties that a user_load or user_load_by_name.
$user = {
'uid' => 143,
'name' => 'The_User_Name',
'permission' => 16,
'join_time' => 1370350185,
'join_share' => 242142,
'connect_time' => 1370540256,
'connect_share' => 2499204,
'disconnect_time' => 1370350265,
'new' => 0,
'ip' => '55.138.12.214',
'client' => '<RAWRDC++ V:v3,M:P,H:1/3/3,S:7>',
};
The properties provided may be accessed by $user->{$property_name}. If the name is required to report back to the user one may use $user->{'name'}. If a user is required to be looked up on the $userlist the user information may be located with DCBUser::userlist->{lc($name)}. It's important to ensure the name is lowercased otherwise no information will be returned.
Commands wishing to return some kind of message or action to chat/the user should recreate the following structure at the end of their subroutines in order to pass meaningful information back to the main bot. An array containing arrays of hashes is the structure and allows limitless responses and actions. Within each hash a number of specified elements must be returned. param should be either message or action
Use either 'message' or 'action' for the data to be sent to either odch_sendmessage or odch_action respectively.
- message allows for a variety of message types to be used to communicate with users.
- action allows bot level actions to run such as kicking users or banning nicknames.
The 'type' element is used to define what kind of message should be sent. Rather than using integer values for the returns, DCBCommon provides constants that may be used instead to provide a little more verbosity to those reading the code.
| Type | Constant | Description |
| 1 | HUB_PUBLIC | Message from the hub in main chat that everybody sees (Similar to the MOTD) |
| 2 | PUBLIC_SINGLE | Message from the bot in main chat that only the recipient sees |
| 3 | BOT_PM | PM from the bot to a user in a separate PM window |
| 4 | PUBLIC_ALL | Message from the bot in main chat that everybody sees (Most common) |
| 5 | MASS_MESSAGE | PM from the bot to all users. (Mass message) |
| 6 | SPOOF_PM_BOTH | PM from 'fromuser' to 'user' (spoofed) |
| 7 | SEND_TO_OPS | Message from the bot to all logged in Operators |
| 8 | HUB_PM | PM from the hub to 'user' in a separate PM window |
| 9 | SPOOF_PM_SINGLE | PM from 'fromuser' to 'user' that will only show to 'user' (spoofed) |
| 10 | SPOOF_PUBLIC | Message from 'user' to mainchat (spoofed) |
| 11 | RAW | Raw data to 'user' |
| 12 | SEND_TO_ADMINS | Message from the bot to all logged in admins |
user and fromuser are related to the message type and may sometimes be omitted (in the case of chat to all users etc).
my @return = ();
@return = (
{
param => "message",
message => "Welcome for the first time: $user->{name}",
type => MESSAGE->{'PUBLIC_ALL'},,
user => '',
fromuser => '',
},
{
param => "action",
user => $user->{name},
action => 'kick',
},
);
}
There are a number of 'hooks' that can be taken advantage of when creating commands. These hooks are activated with certain hub events. The events are as follows:
- init: Invoked when the hub starts up. Useful for instantiating globals/populating variables from db values.
- prelogin: User is being validated
- postlogin: Successful validation
- line: A line of chat is spoken
- pm: A private message is sent
- timer: The timer has fired (usually every 15 minutes)
- logout: The user has disconnected
- alter: Allows a command to alter any other command when it is executed.
With most of the hooks, the data provided will be:
- The name of the command
- The user in focus (logging in, saying chat)
- Additional parameters (if necessary)
Although sometimes (such is the case with the timer and init) there won't be a user parameter.
The purpose of hooks is to allow commands to have additional functionality at times where a user is not calling a command in the usual fashion. An example of this may be found within the 'tell' command. Although the main tell command creates a message for other users, the postlogin and line hooks are used to find when a user either speaks on logs in as an indicator to send the user the message.
The alter hook is special insofar as the return structure should match the variables provided to the functions. Variables provided are the same as any standard hook or command:
- command name
- hook name (which will be alter)
- user the hook relates to
- a string consisting of the name of the hook to alter followed by any additional parameters
A typical alter hook could be to disable any commands if they start with the letter 't':
It is imperative that any subroutine in the [command].pm file returns something. Whether this is a structured @return array or just an empty Perl return; does not matter. However without returning there is the chance that it could prevent execution of subsequent functionality.
Commands are also able to provide their own table structure to be created in the database on command install by invoking the schema{} subroutine. Additionally, the creation of configuration variables is possible within the same subroutine.
By creating, and returning, an associative array of 'schema' and/or 'config', the bot will create tables and variables that are ready for the command to use.
Any table declarations should exist in the schema array and should be keyed by table name. Within that key should be an array of fields with field descriptions keyed by the table column name.
There is no restriction on the number of tables/fields that can be created in this way.
Configuration may be created by entering in key/value elements underneath the config element. A standard that should ideally be kept is to prefix the key of any configuration
sub schema {
my %schema = (
schema => ({
favorite_colors => {
id => {
type => "INTEGER",
not_null => 1,
primary_key => 1,
autoincrement => 1,
},
color => { type => "VARCHAR(35)", },
time => { type => "INT", },
username => {
type => "INT",
not_null => 1,
},
},
color_index => {
color => { type => "VARCHAR(35)", },
color_file => { type => "BLOB", },
},
}),
config => {
number_votes => 1,
last_year_favorite_color => "red",
default_thanks => "Thank you for selecting your favorite color",
},
);
return \%schema;
}
If a command is uninstalled, the database table and any configuration specified in the schema{} subroutine will be removed and all data lost. This is the major difference between disabling a command and uninstalling.
Due to requirements of the bot, the %schema array must be returned by reference.
The jabber branch of this project can be used to run the bot on an XMPP/Jabber server. There are additional prerequisites of the Net::Jabber::Bot module with this patch as well as the utf8 module.
TODO: create a log file and write to that
Submit a bug report by using the -bug command or by contacting odchbot@gmail.com