=begin pod

=NAME    Matrix::Bot
=AUTHOR  Patrick Spek <p.spek@tyil.work>
=VERSION 0.2.0

=head1 Description

A framework for writing Matrix bots

=head1 Installation

Install this module through L<zef|https://github.com/ugexe/zef>:

=begin code :lang<sh>
zef install Matrix::Bot
=end code

=head1 Usage

=head2 Configuring the bot

First off, you have to instantiate the bot correctly. For this, a few arguments
must be passed to C<new>.

=begin code
use Matrix::Bot;

my $bot = Matrix::Bot.new(
	home-server => "https://matrix.org",
	username => %*ENV<USER>,
	password => "",
	access-token => "",
	plugins => [],
);

$bot.run;
=end code

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 C<Matrix::Bot::Plugin>.

The C<run> call starts the bots event loop. It will connect to Matrix, and
start retrieving new messages on the channels it is joined in.

=head2 Plugins

The simplest usage of the module would be using the C<handle-room-text> method
in a plugin. For instance, to repond to C<"ping"> messages with a C<"pong">,
you can write a plugin as follows.

=begin code
use Matrix::Bot::Plugin;

class Local::Matrix::Plugin is Matrix::Bot::Plugin {
	multi method handle-room-text ($e where * eq "ping") {
		"pong"
	}
}
=end code

=head2 Logging

There is logging available in the module, through
L<C<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 C<filter>.

=begin code
use LogP6 :configure;

filter(name => "", level => $trace, :update);
=end code

If you only want certain logging to be shown, you can set up one or more
C<cliche> calls instead. For instance, the following C<cliche> shows only the
messages on a channel.

=begin code
cliche(
	name => "messages",
	matcher => "Matrix::Bot/message",
	grooves => (
		writer(
			pattern => "%msg",
			handle => $*OUT,
			filter(level => $info),
		),
	),
);
=end code

More information on how to use C<cliche>s, C<filter>s and C<LogP6> in general
can be found in the C<LogP6> documentation.

The following traits are used throughout C<Matrix::Bot>:

=item C<Matrix::Bot>
=item C<Matrix::Bot/message>
=item C<Matrix::Bot/plugin($name)> (The C<$name> corresponds to the name of the plugin's class)

=head1 License

This module is distributed under the terms of the AGPL-3.0.

=end pod
