Heimdallr/README.md

[![Build Status](https://ci.myrkvi.com/api/badges/NLL/Heimdallr/status.svg)](https://ci.myrkvi.com/NLL/Heimdallr)

# 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 python Heimdallr.py`.  
**NB:** The environment variable `DISCORD_TOKEN` must be set to a working bot token.  
The environment variable `HEIMDALLR_LOGLEVEL` can be set to one of `critical`, `error`, `warning`, `info`, or `debug` to display appropriate log output.
If using PostgreSQL instead of SQLite, you can pass a connection URL to `HEIMDALLR_POSTGRES_URL`. Note that this is as of yet untested and may not work as intended.

# 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.

## Adm
Server administrative commands.

# Join/leave messages
Join and leave messages allow the server and the member to be referenced.

## Member
Can be accessed with `{member}`.

- `{member.id}`  
    The member's unique Snowflake ID.
- `{member.bot}`  
    Whether or not this member is a bot.
- `{member.display_name}`  
    The member's nickname, if any, or their username.
- `{member.joined_at}`  
    The time at which the member joined, as a timestamp.
- `{member.username}`  
    The member's username.
- `{member.discriminator}`  
    The member's discriminator, i.e. the four digits following their username and the `#` symbol.
- `{member.mention}`  
    A mention of the member.
  
## Guild (server)
Can be accessed with `{guild}`.

- `{guild.id}`  
    The unique Snowflake ID of the guild.
- `{guild.member_count}`  
    The total number of members in the guild.
- `{guild.name}`  
    The name of the guild.
- `{guild.description}`  
    The Discovery description of the guild.
- `{guild.created_at}`  
    A timestamp of when the guild was created.