txt: ## dist_cpan-TYIL-Matrix-Bot.md
  # NAME
  
  Matrix::Bot
  
  # AUTHOR
  
  Patrick Spek [p.spek@tyil.work](mailto:p.spek@tyil.work)
  
  # VERSION
  
  0.2.0
  
  # Description
  
  A framework for writing Matrix bots
  
  # Installation
  
  Install this module through [zef](https://github.com/ugexe/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`](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.
  