# Heimdallr
This is a complete rewrite of the [Heimdallr bot](https://gitlab.com/NorwegianLanguageLearning/heimdallr) in Python.
The rewritten version of Heimdallr supports multiple servers, and it should be easier to add new features.

# Running
Install Heimdallr's dependencies with Poetry (`poetry install`)  
From the current directory, run `poetry run Heimdallr.py`.  
**NB:** The environment variable `DISCORD_TOKEN` must be set to a working bot token.

# Commands
`Monospaced` text indicates command usage. `<argument>` indicates a required argument. `[argument]` indicates an optional argument.
## Quote
`quote <url>`

`<url>` is a message link obtained by right clicking a message and selecting *Copy Message Link*.

![The quote command being typed](_images/quote_command.png)  
![The result of the quote command](_images/quote_example.png)

The quote command allows users to quote a message in a manner that may be more suitable than replying to one to highlight it.
It also allows quoting across different channels (and even servers, if Heimdallr is in both.)
Heimdallr checks that the user can view the channel of the original message before quoting.

By default, this command is available to everyone.

## Role
A simple system for self-serve roles.

By default all `role` commands are available to everyone.
### Role list
`role list`
List all available roles, with their descriptions and prerequisite role, if any.

### Role add
`role add <role>`
Add a self-role to yourself. Available roles are autocompleted, and exclude already assigned roles.
Note that it does not exclude roles with a prerequisite that the user does not have.

### Role remove
`role remove <role>`
Remove a self-role. It shows only roles that you already have.

## Role-admin
Administration commands for self-roles.  

By default it is available to those with the *Manage Roles* permission
### Role-admin add
`role-admin add <role> [description] [requires]`

Add a role as a self-role.
`[description]` is a description of the role, shown with `role list`. `[requires]` is an optional required role.

### Role-admin remove
`role-admin remove <role>`

Remove a role from the available self-roles.

## Warn
`warn <user> [reason] [weight] [silent]`  
`<user>`: the user to warn  
`[reason]`: the reason for issuing a warning  
`[weight]`: how severe the warning is. Default 1.0  
`[silent]`: should the warning be silent, i.e. not sent to the user. Default false

Warn will issue a warning to the user that is viewable through the infractions command. If `silent` is False (default), it will also attempt to send a message to them.

By default it is accessible to those with the *Kick User* permission.

## User-infractions
`user-infractions <user>`

Displays the infractions of a user.