README.md

nonbot is a skeleton chatbot designed to work with Matrix servers. It is a minimal example that is meant to be used as a starting point for building something more useful. It is expected that this repository will be cloned, people will add their own fuctionality, and the customized bots will be given unique names.

Synopsis

$ MY_BOT_NAME=nonbot
$ buildah unshare ./build.sh $MY_BOT_NAME
$ cat << 'END' > $HOME/.local/opt/$MY_BOT_NAME/config
HOMESRVR = matrix.fedoraproject.org
USERNAME = @FASID:fedoraproject.org
PASSWORD = PASSW0RD
ROOMNAME = \#fedora:fedoraproject.org
END
$ systemctl --user start $MY_BOT_NAME

The ROOMNAME line may be repeated to have the bot listen in multiple rooms. If you want to connect to multiple homeservers or use multiple accounts, you will have to run multiple bots.

The above commands for building the container image and creating the configuration file only need to be run once. Notice that the hash symbol (#) on the ROOMNAME line must be prefixed with a backslash (\) to prevent it from being interpreted as the start of a comment.

Once the container image is built and a configuration file is defined, the container can be started and stopped using its systemd service.

$ systemctl --user start $MY_BOT_NAME

If you make any changes to the bot under $HOME/.local/opt/$MY_BOT_NAME, you will need to restart the container.

Defining Commands

The commands that the bot will respond to are defined in the $HOME/.local/opt/$MY_BOT_NAME/commands.pm file. The hello and search commands have been provided as examples. To call the example subroutines while the bot is running enter #hello or #search <name>, respectively, in a chat room that the bot has joined. The prefix character (#) can be changed by editing the run file. Parameters passed to the commands will be available in the @_ array within the scope of the command. If the command returns text, it will be displayed in the chat room.

If you add any package dependencies to the run or commands.pm files, be sure to list them in the build.sh script. The container will need to be rebuilt if you add package dependencies.

License

nonbot is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the Perl 5 License for details.

Disclaimer

This package is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.