NAME
Matrix::Bot
AUTHOR
Patrick Spek p.spek@tyil.work
VERSION
0.2.0
Description
A framework for writing Matrix bots
Installation
Install this module through zef:
zef install Matrix::Bot
Usage
Configuring the bot
First off, you have to instantiate the bot correctly. For this, a few arguments must be passed to new.
use Matrix::Bot;
my $bot = Matrix::Bot.new(
home-server => "https://matrix.org",
username => %*ENV<USER>,
password => "",
access-token => "",
plugins => [],
);
$bot.run;
You must specify a password or access-token. If you supply both, the password will be ignored, and the access-token will be used directly. The list of plugins has to be filled with classes which implement Matrix::Bot::Plugin.
The run call starts the bots event loop. It will connect to Matrix, and start retrieving new messages on the channels it is joined in.
Plugins
The simplest usage of the module would be using the handle-room-text method in a plugin. For instance, to repond to "ping" messages with a "pong", you can write a plugin as follows.
use Matrix::Bot::Plugin;
class Local::Matrix::Plugin is Matrix::Bot::Plugin {
multi method handle-room-text ($e where * eq "ping") {
"pong"
}
}
Logging
There is logging available in the module, through LogP6. This same logging object can be accessed by plugins, so they can log to the same stream when desired. To show all logging, you can set up a filter.
use LogP6 :configure;
filter(name => "", level => $trace, :update);
If you only want certain logging to be shown, you can set up one or more cliche calls instead. For instance, the following cliche shows only the messages on a channel.
cliche(
name => "messages",
matcher => "Matrix::Bot/message",
grooves => (
writer(
pattern => "%msg",
handle => $*OUT,
filter(level => $info),
),
),
);
More information on how to use cliches, filters and LogP6 in general can be found in the LogP6 documentation.
The following traits are used throughout Matrix::Bot:
License
This module is distributed under the terms of the AGPL-3.0.