Raku Land

Matrix::Bot

cpan:TYIL

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.