NAME ==== Matrix::Bot AUTHOR ====== Patrick Spek VERSION ======= 0.2.0 Description =========== A framework for writing Matrix bots Installation ============ Install this module through [zef](https://github.com/ugexe/zef): ```sh 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, 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`](https://modules.perl6.org/dist/LogP6:cpan:ATROXAPER). 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 `cliche`s, `filter`s and `LogP6` in general can be found in the `LogP6` documentation. The following traits are used throughout `Matrix::Bot`: * `Matrix::Bot` * `Matrix::Bot/message` * `Matrix::Bot/plugin($name)` (The `$name` corresponds to the name of the plugin's class) License ======= This module is distributed under the terms of the AGPL-3.0.