Noi/RegexBot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated documentation

Browse source
This commit is contained in:
Noikoio 2018-01-13 12:02:48 -08:00
parent 1694c82691
commit b8abc50703
7 changed files with 175 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
docs/automod.md
View file

@ -1,22 +1,24 @@
## AutoMod
AutoMod is a component that takes inspiration from Reddit's [Automoderator](https://www.reddit.com/wiki/automoderator). It allows the user to define one or more *rules* based on regular expression (regex) patterns. When the rule is matched, the bot will proceed to to execute a *response*. This was initially the main and only feature of this bot, hence its name RegexBot.
AutoMod is a component that takes inspiration from Reddit's [Automoderator](https://www.reddit.com/wiki/automoderator). It was the original feature of RegexBot. It allows the operator to define one or more *rules* based on regular expression (regex) patterns. When a particular rule is matched, the bot executes the appropriate *response*.
AutoMod rules are defined per-server within the `automod` object. Each rule is defined as a name/value pair, with the name serving as its label.
AutoMod is set up by defining rules within a JSON object named `automod` within a server definition. Rules are defined by means of name/value pairs, with the name serving as its label.
Sample AutoMod rules:
Sample within a [server definition](serverdef.html):
```
"Delete bilingual pirates": {
"regex": [ "pira(te|cy)", "pirat(a|ería)", ],
"response": [
"delete"
"report #0000000::mod-queue"
]
},
"Selective trigger": {
"regex": "secret",
"response: "say #_ Don't say the s word, @_!",
whitelist: { "channels": [ "#dont-say-secret" ] }
"automod": {
"Delete bilingual pirates": {
"regex": [ "pira(te|cy)", "pirat(a|ería)", ],
"response": [
"delete"
"report #0000000::mod-queue"
]
},
"Selective trigger": {
"regex": "secret",
"response: "say #_ Don't say the s word, @_!",
whitelist: { "channels": [ "#dont-say-secret" ] }
}
}
```
@ -24,15 +26,18 @@ Sample AutoMod rules:
The following is a list of accepted members within an AutoMod rule:
* regex (*string* or *string array*) - **Required.** Regular expression pattern(s) that trigger the defined rule.
* response (*string* or *string array*) - **Required.** Response, or list of responses to execute.
* See the section below for more information on responses.
* whitelist *[(entity list)](entitylist.html)* - Entities to which the rule exclusively applies to.
* blacklist *[(entity list)](entitylist.html)* - Entities to which the rule does not apply to.
* exempt *[(entity list)](entitylist.html)* - Entities which are exempt from whitelist or blacklist rules.
* See the section below for more information on defining responses.
* whitelist (*[entity list](entitylist.html)*) - Entities to which the rule exclusively applies to.<sup>1</sup>
* blacklist (*[entity list](entitylist.html)*) - Entities to which the rule does not apply to.<sup>1</sup>
* exempt (*[entity list](entitylist.html)*) - Entities which are exempt from whitelist or blacklist rules.<sup>2</sup>
* For example: It would allow for a specific user to trigger a rule, despite being a member of a blocked role.
* AllowModBypass *(boolean)* - Specifies if those defined within the *moderators* list for the server should be exempt from triggering this rule. Defaults to *true*.
<sup>1</sup> A rule may either contain a whitelist or blacklist, but not both.
<sup>2</sup> Used only if a whitelist or blacklist have been specified.
### Responses
Responses are the actions executed when a rule is matched. They take the form of one or more strings defined within a single rule. Defining a response could be considered to be similar to typing out a command, with particular responses requiring a number of parameters.
A response is the action, or list of actions, to be executed when a rule is matched. Defining a response could be considered to be similar to typing out a command or a batch script, with certain responses requiring a number of parameters.
The following responses are currently implemented:
* ban - Immediately bans the user that triggered the rule.
@ -47,4 +52,6 @@ The following responses are currently implemented:
* say *target_entity* *message* - Sends *message* to the given *target_entity*.
* Aliases: send
For responses that support parameters, it is possible to specify the matching user or the channel in which the match occurred as a parameter. This is done using `@_` and `#_`, respectively. Additionally it is possible to define a user or channel in the same way as items in an entity list, by using either the entity's ID, name, or both.
In regards to responses that accept *target* parameters, it is possible to specify the target to be the user who triggered the rule or the channel in which the rule was triggered in. This is done by specifying the parameter as `@_` or `#_`, respectively. The sample above shows an example of this.
Additionally, targets may be defined in the same type of format accepted within [entity lists](entitylist.html). This is also shown in the above example.

42
docs/autorespond.md
View file

@ -1,29 +1,33 @@
## AutoRespond
AutoRespond is a component that exists exclusively to allow your bot to respond to certain text triggers. An AutoRespond *definition* takes one or more regular expression patterns, a response string, and optionally several other options for adjusting the definition's behavior.
AutoRespond is a component that deals exclusively with responding to text triggers. An AutoRespond *definition* takes one or more regular expression patterns, a response string, and optionally several other options for adjusting the definition's behavior.
Although it is possible to create auto-response rules using AutoMod, defining them in AutoRespond allows you to not have to worry about adding extra configuration to ensure it works properly for all users.
This may seem like a redundant feature, given that the same can be accomplished with AutoMod. However, this feature spares you of having to insert special cases within AutoMod rules that would prevent all users from having equal access to triggers. Additionally, it allows for extra features that would not be possible in AutoMod, such as rate limiting.
Sample AutoRespond definitions:
Sample within a [server definition](serverdef.html):
```
"Help command": {
"regex": "^!help$",
"reply": "You can't be helped. Try again in 45 minutes.",
"ratelimit": 2700
},
"Spam trigger": {
"regex": [
"spam post",
"dumb",
"productive conversation"
],
"exec": "python /home/autospam.py"
"autorespond": {
"Help command": {
"regex": "^!help$",
"reply": "You can't be helped. Try again in 45 minutes.",
"ratelimit": 2700
},
"Spam trigger": {
"regex": [
"spam post",
"dumb",
"productive conversation"
],
"exec": "python /home/bot/did-someone-say-botspam.py"
}
}
```
### Definition structure
The following is a list of accepted members within an AutoRespond definition:
* regex (*string* or *string array*) - **Required.** Regular expression pattern(s) that will invoke the response.
* reply *(string)* - The message to send out to the channel in which the response was invoked.
* exec *(string)* - Command line path and optional parameters to an external program. The program's output will be sent to the channel in which the response was invoked.
* It is **required** to have one of either *reply* or *exec* in a definition.
* ratelimit *(integer)* - The amount of time in seconds in which the response may not be triggered again within the same channel. Defaults to 20.
* reply *(string)* - The message to send out to the channel in which the response was invoked.<sup>1</sup>
* exec *(string)* - Command line path and optional parameters to an external program. The program's output will be sent to the channel in which the response was invoked.<sup>1</sup>
* ratelimit *(integer)* - The amount of time in seconds in which the response may not be triggered again within the same channel. Defaults to 20.
<sup>1</sup> It is **required** to have either *reply* or *exec* specified in a definition.

23
docs/docs.md
View file

@ -1,25 +1,26 @@
# Documentation
**Important note: Documentation is a work in progress and may be incomplete in some areas.**
RegexBot has no default behavior of its own. It is up to the bot operator to define all aspects of its function, and this is all done by means of a configuration file.
RegexBot has no default behavior of its own. It is up to the bot operator to define all aspects of its function, down to its triggers and commands to be used by moderators.
Configuration takes the form of a [JSON](https://json.org/) file residing in the same directory as the executable, named `settings.json`. The sample provided below should give you an idea of how the file is structured. Additionally, the JSON parser used by RegexBot allows for comments within the file.
Its configuration takes the form of a JSON file residing in the executable directory, named `settings.json`. Within this file should be one nameless JSON object, which itself should contain named values described near the bottom of this page. Additionally, the JSON parser treats text following double slashes as comments.
The following is a sample configuration file:
Sample configuration file:
```
{
"bot-token": "AbCDEf-gh1JKLmn0pqR$Tu.vwXyZ",
"playing": "with my preferred text editor",
"playing": "with my preferred text editor", // not saying which!
"servers": [
{
// (server configuration goes here)
// server definition(s) defined here
}
]
}
```
### Structure
The following is a list of all accepted members at the top level of the configuration file. Links given below and in subsequent pages will further explain additional values that are allowed within them.
The following is a list of all accepted values with links to pages explaining them in more detail.
* bot-token *(string)* - **Required.** Discord token used for connecting to the service.
* playing *(string)* - String to display as the bot's "now playing" status message.
* servers *(array)* - Takes an array of unnamed [server definition](serverdef.html) objects.
Value names are **case sensitive**. Keep this in mind, as case is not consistent throughout the list of member names. This will be corrected in future updates.
* bot-token (*string*) - Discord token for connecting to the service. **Required.**
* playing (*string*) - Optional text to display for the bot's status message.
* servers (*array*) - Takes an array of unnamed [server definition](serverdef.html) objects.

8
docs/entitylist.md
View file

@ -1,8 +1,8 @@
## Entity list
An entity list is a JSON object with multiple values each containing arrays of strings. They are used in various places in the configuration to specify a number of users, roles, channels, or any combination thereof.
An entity list is a JSON object with multiple values each containing arrays of strings. They are used in various places in the configuration to specify a group of users, roles, channels, or any combination thereof.
The following is a sample of an entity list:
Sample entity list:
```
{
"users": [ "@000000000000::MyName", "That Guy Over There" ],
@ -11,11 +11,11 @@ The following is a sample of an entity list:
}
```
As can be seen, all entities defined may either be specified using their name, or otherwise have their unique ID along with a label, separated by two colon (:) characters. Additionally, the ID should be prefixed with `@` if referring to a user or `#` if referring to a channel.
As you can see, all entities may be specified by name, or by having their [unique ID](https://support.discordapp.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-) along with a label, separated by two colon (:) characters. Additionally, the ID value should be prefixed with `@` if referring to a user or `#` if referring to a channel.
Each individual property is optional within an entity list, and is not necessary if your configuration does not require it. For example, this is a valid definition for an empty entity list:
```
{ }
```
It is **strongly recommended** to use unique IDs when defining entities with names that could change at any given time, such as users. Certain servers that frequently change role and channel names also benefit from having those IDs specified.
It is **strongly recommended** to use unique IDs when defining entities with names that could change at any given time, such as users. Certain servers that frequently change role and channel names will also benefit from having them specified.

26
docs/index.md
View file

@ -2,19 +2,31 @@
title: RegexBot
---
# Introduction
Perhaps you've already found a number of bots that cover your needs, configured in just the right way to handle the day-to-day activity of your Discord server. Yet, have you ever wanted to be able to change *that one detail* to finally make things perfect?
Perhaps you already have all the bots you need, configured in just the right way to handle the day-to-day activity of your Discord server. But have you ever wanted to modify *that one thing* in order to finally make things perfect?
RegexBot offers a blank slate. It does nothing on its own and leaves every aspect of its behavior to its configuration. This means each instance of RegexBot is uniquely suited to the server(s) it is configured to run on.
RegexBot is a moderation bot that on its own, does nothing. All aspects of its behavior are defined through configuration. This means that each instance of RegexBot is uniquely suited to the server(s) it is configured to run on.
# Features
* Define custom actions to perform in response to regular expression patterns
* Supports a handful of commands for making moderation easier
* Run external scripts and send the output to a text channel
# Running the bot
There is no public instance of RegexBot ready to be invited to servers, and there are no plans to do so. Self-hosting the bot will be necessary to make use of it.
At the moment, there is no public instance of RegexBot that is ready and available to be sent to other servers. It has been considered, but is currently not a priority. Hosting your own instance will be necessary.
### Download
Pre-compiled executables will be available soon. Until then, see below for instructions on how to compile the bot from source.
A link to all available downloads is availabe at the top of the page, through the "Releases" link. You may choose to either download a pre-compiled binary or compile it from source. See below for detailed instructions.
If using a pre-compiled binary, keep in mind the requirements:
* Windows: Windows 7 SP1, Windows 8.1, Windows 10 1607+ (Anniversary Update)
* macOS: Mac OS X 10.12 (Sierra) or higher
* Linux: Most major distributions supported. Dependencies required.
* List of dependencies can be found [here](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x).
Extract the contents to a folder, create a configuration file (see top of page, Documentation) and then run `RegexBot.exe` (Windows) or `./RegexBot` (Linux, macOS).
### Make a bot account
You will need to get a bot token. To do so, [create an app in Discord](https://discordapp.com/developers/applications/me) and convert it into a Bot User. Make a note of the token and Client ID. **Do not share your bot token or put it in a public place.**
You will need to get a bot token. To do so, [create an app in Discord](https://discordapp.com/developers/applications/me) and convert it into a Bot User. Make a note of the token and Client ID. **Do not share this token under any circumstances.**
Once you have created your Discord app, go to the following URL after inserting your client ID where specified: `https://discordapp.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot`.
@ -36,9 +48,9 @@ $ dotnet publish -c Release -o output
```
You may see some warnings during this last step, but the build should still succeed. These warnings will be corrected in future releases.
At this point, the bot has been compiled and all dependencies placed in the `output` directory. You may run the bot at this point by issuing the following:
At this point, the bot has been compiled and all dependencies placed in the `output` directory. The bot may be run by issuing the following:
```
$ cd output
$ dotnet RegexBot.dll
```
You may move and rename the output directory at your convenience.
You may move and rename the output directory at your convenience.

64
docs/modtools.md
View file

@ -1,2 +1,64 @@
## ModTools
(to be written later)
ModTools is the current name for the component that provides commands for use by moderators. Commands are defined based on a number of available template-like *type*s, which can then be customized with further configuration.
Sample within a [server definition](serverdef.html):
```
"ModTools": {
"Commands": {
"Kick": { // a plain and simple kick command
"type": "kick",
"command": "!!kick"
},
"Party Ban": { // self-explanatory
"type": "ban",
"command": "!!party",
"successmsg": "Yay! $target got banned!\nhttps://i.imgur.com/i4CIBtT.jpg"
}
}
}
```
### Definition structure
Commands are defined within a JSON object named `Commands` within another object named `ModTools`. They are defined by means of name/value pairs, with the name serving as its label.
The following values are **required** in a definition:
* type (*string*) - Specifies the behavior that the command should take.
* command (*string*) - The text trigger for the command being defined. Must not contain spaces, and it is recommended to start it with an uncommon symbol, such as `!`.
### Command types
Each command type specifies the action taken by the bot when the command is invoked. Certain types offer additional configuration options as well.
#### Ban
* `"type": "ban"`
* Usage: (*command*) (*user name or ID*) [*reason*]
Bans the given user from the server the command was invoked in, and sends the reason, if any, to the server's audit log.
Additional behavior can be specified in its configuration:
* forcereason (*boolean*) - Forces the reason to be specified if set to true. If none is specified, the action is not taken. Defaults to *false*.
* purgedays (*integer*) - The number of days, between 0 and 7 inclusive, of the target's post history to erase during banning. Defaults to *0*.
* successmsg (*string*) - Custom message to display on a successful ban. If not specified, a default message is used.
* The string *$target* can be used in the value to represent the ban target.
* notifymsg (*string*) - A message to send to the target user prior to banning, informing the user of the action taking place.
* The strings *$s* and *$r* can be used in the value to represent the server name and ban reason, respectively.
* Uses a default message if this configuration value is not specified.
* To disable, specify a blank value.
#### Kick
* `"type": "kick"`
* Usage: (*command*) (*user name or ID*) [*reason*]
Removes the given user from the server the command was invoked in, and sends the reason, if any, to the server's audit log.
Additional behavior can be specified in its configuration:
* forcereason (*boolean*) - Forces the reason to be specified if set to true. If none is specified, the action is not taken. Defaults to *false*.
* successmsg (*string*) - Custom message to display on a successful ban. If not specified, a default message is used.
* The string *$target* can be used in the value to represent the ban target.
* notifymsg (*string*) - A message to send to the target user prior to banning, informing the user of the action taking place.
* The strings *$s* and *$r* can be used in the value to represent the server name and ban reason, respectively.
* Uses a default message if this configuration value is not specified.
* To disable, specify a blank value.
#### Say
* `"type": "say"`
* Usage: (*command*) (*channel name or ID*) (*message*)
Causes the bot to send the given message exactly as specified to the given channel.

34
docs/serverdef.md
View file

@ -1,11 +1,31 @@
## Server definition
Server definitions are defined within the `servers` array. Each definition represents unique configuration for a single server. Defining multiple servers allows for a single bot instance to be uniquely configured for use in several servers at once.
Server definitions are defined within the `servers` array. Each definition represents unique configuration values for a single server. It is possible to specify multiple servers, thus allowing for a single bot instance to be used in several servers at once.
Sample definition within [configuration](docs.html):
```
servers: [
{
"id": 100000000000,
"name": "Fun Server",
"autoresponses": {
// ...
}
},
{
"id": 100000000001,
"name": "Serious Business",
"automod": {
// ...
}
}
]
```
The following is a list of accepted members within a server definition.
* id *(integer)* - **Required.** A value containing the server ID, and optionally the name, of the server that this definition represents.
* name *(string)* - The server name. Only used during configuration (re)load to make logs more readable.
* moderators *[(entity list)](entitylist.html)* - A list of entities to consider as moderators. Actions done by the members of those in this list are able to execute *ModTools* commands and are exempt from certain *AutoMod* rules if a particular rule has its *AllowModBypass* setting set to *false*.
* [AutoMod](automod.html) *(name/value pairs)* - Auto-moderation matching and response definitions.
* [AutoResponses](autorespond.html) *(name/value pairs)* - Definitions for automatic responses.
* [ModTools](modtools.html) *(name/value pairs)* - Moderation command definitions.
* id (*integer*) - **Required.** A value containing the server's [unique ID](https://support.discordapp.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-).
* name (*string*) - Preferably a readable version of the server's name. Not used for anything other than internal logging.
* moderators (*[entity list](entitylist.html)*) - A list of entities to consider as moderators. Actions done by members of this list are able to execute *ModTools* commands and are exempt from certain *AutoMod* rules. See their respective pages for more details.
* [automod](automod.html) (*name/value pairs*) - See respective page.
* [autoresponses](autorespond.html) (*name/value pairs*) - See respective page.
* [ModTools](modtools.html) (*name/value pairs*) - See respective page.