forked from LibreGaming/matchbot
91 lines
2.9 KiB
Markdown
91 lines
2.9 KiB
Markdown
<!--- SPDX-License-Identifier: Apache-2.0 -->
|
|
<!--- SPDX-FileCopyrightText: 2022 Sebastian Crane <seabass-labrax@gmx.com> -->
|
|
|
|
# matchbot
|
|
|
|
A chatbot for announcing upcoming matches and finding fellow players, written for the [LibreGaming](https://libregaming.org) community
|
|
|
|
## Running
|
|
|
|
1. Install Clojure - you can use [Clojure's official installation guide](https://clojure.org/guides/getting_started) or your distribution's package.
|
|
|
|
2. Clone this repository:
|
|
|
|
``` bash
|
|
git clone https://git.libregaming.org/LibreGaming/matchbot.git
|
|
cd matchbot
|
|
```
|
|
|
|
3. Create a configuration file, `config.yaml`, in YAML format:
|
|
|
|
``` yaml
|
|
data-file: "matchbot-data.json"
|
|
irc:
|
|
server: example.com
|
|
port: 6667
|
|
nick: matchbot
|
|
channel: "##matchbot-test"
|
|
```
|
|
|
|
4. Run `matchbot`:
|
|
|
|
``` bash
|
|
clojure -M -m system
|
|
```
|
|
|
|
## Usage
|
|
|
|
**`!list`** - show all the games that have a list of players
|
|
|
|
**`!match game`** - announce a match of `game` to all of its players
|
|
|
|
**`!players game`** - show all the players of `game`
|
|
|
|
**`!add game`** - add yourself to the list of players for `game`
|
|
|
|
**`!remove game`** - remove yourself from the list of players for `game`
|
|
|
|
**`!help`** - show available commands with their explanations
|
|
|
|
## Development
|
|
|
|
### Running the tests
|
|
|
|
`matchbot` includes automated unit tests for many functions, along with a simple test runner configuration with [Kaocha](https://cljdoc.org/d/lambdaisland/kaocha/).
|
|
Running the tests is a similar process to running the main application:
|
|
|
|
```bash
|
|
clojure -M:test
|
|
```
|
|
|
|
### Starting a development REPL
|
|
|
|
When developing `matchbot`, it can be more convenient and efficient to work interactively with a REPL integrated into your text editor.
|
|
Since `matchbot` uses Clojure's [tools.deps library](https://clojure.org/guides/deps_and_cli), the best way to start is by following [the relevant part of the nREPL documentation](https://nrepl.org/nrepl/usage/server.html#using-clojure-cli-tools) to create a user-level `deps.edn` file, then install the [nREPL extension for your text editor](https://nrepl.org/nrepl/usage/clients.html#editorsides).
|
|
|
|
You can create, start and stop an instance of the chatbot process with the functions in the `system` namespace:
|
|
|
|
``` clojure
|
|
;; creating a new instance - an empty Var
|
|
(def my-instance nil)
|
|
|
|
;; starting the instance
|
|
(alter-var-root #'my-instance system/start)
|
|
|
|
;; restarting the instance
|
|
(system/restart #'my-instance)
|
|
|
|
;; stopping and resetting the instance
|
|
(alter-var-root #'my-instance system/stop)
|
|
(alter-var-root #'my-instance (constantly nil))
|
|
```
|
|
|
|
Once you are familiar with nREPL, you can additionally use [tools.namespace.repl](https://github.com/clojure/tools.namespace) to make reevaluating (reloading) your changes easier:
|
|
|
|
``` clojure
|
|
(require '[clojure.tools.namespace.repl :refer [refresh]])
|
|
(refresh)
|
|
```
|
|
|
|
Make sure that you create your system instance in the REPL, since `refresh` will forcefully delete the instance if it has been defined in another namespace!
|