python-app-rocketbot/patterns.md

Patterns

The PatternCog offers a way of creating custom message filters of moderate complexity without needing to make code changes in the bot and redeploy it. A guild can have any number of custom patterns. The commands are:

$rb_patterns add <name> <statement> - Add a new named pattern $rb_patterns remove <name> - Remove a named pattern $rb_patterns list - List all named patterns

The pattern <name> can be anything. If it contains spaces, enclose it in double quotes, e.g. "my filter".

Statements

A statement consists of one or more actions to take on a message followed by an expression defining the criteria for which messages match.

Actions

Available actions:

• ban - Bans the user. The “reason” in the audit log will reference the pattern name.
• delete - Deletes the message.
• kick - Kicks the user. The “reason” in the audit log will reference the pattern name.
• modwarn - Tags the mods in a warning message. The message will offer quick actions to manually delete the message, kick the user, and ban the user (assuming the other actions didn’t already do one or more of these things)
• reply "message" - Makes Rocketbot automatically reply to their message with the given text.

Expressions

The simplest expression just consists of a message field, a comparison operator, and a value to compare it to. For example:

content contains "forbidden"

The message will match if its content contains the word "forbidden".

The available operators and type of value depends on the field being accessed.

Fields

• content - The text of the message. Note this is in raw Discord markdown, so it may contain underscores, emote names, and mention codes. Available operators: ==, !=, contains, !contains, matches, !matches. Comparison value must be a quoted string.
• author - Who sent the message. Available operators: ==, !=. Comparison value must be a user mention (an @ that Discord will tab-complete for you).
• author.id - The numeric ID of the user who sent the message. Available operators: ==, !=. Comparison value must be a numeric user ID.
• author.name - The username of the author. Available operators: ==, !=, contains, !contains, matches, !matches. Comparison value must be a quoted string.
• author.joinage - How much time has elapsed from when the author joined and when the message was sent. If the user has joined and left multiple times this is the most recent join time. Available operators: ==, !=, <, >, <=, >=. Comparison value must be a timespan (see below)

Operators

• == - The values are equal
• != - The values are not equal
• < - The field is less than the given value
• > - The field is greater than the given value
• <= - The field is less than or equal to the given value
• >= - The field is greater than or equal to the given value
• contains - The value is contained somewhere in the field value
• !contains - The value is not contained anywhere in the field value
• matches - The given regular expression matches the field value
• !matches - The given regular expression does not match the field value

Values

Text values must be enclosed in double quote (") characters.

Timespans consist of one or more pairs of a number and a unit letter (“d” for days, “h” for hours, “m” for minutes, “s” for seconds). Examples:

• 30d - 30 days
• 1h30m - 1 hour, 30 minutes
• 99d9h9m9s - 99 days, 9 hours, 9 minutes, 9 seconds

Compound Expressions

Multiple expressions can be combined with “and” or “or”. For example:

content contains "alpha" and content contains "bravo"

This will only match messages that contain both “alpha” and “bravo” somewhere in the text.

More complex expressions can use parentheses to clarify the order of interpretation. For example:

(content contains "foo" and author.joinage < 30m) or (content contains "bar" and author.joinage > 30m)

A message will match if it contains “foo” and the user joined in the last half hour, OR it will match if the message contains “bar” and the author joined more than a half hour ago.

Lastly, expressions can be inverted by prefixing a !. For example:

!(content contains "me" and content contains "you")

This will only match messages that do not contain both “me” and “you”. If it contains just “me” or just “you” or neither word then it will match. If both are present it will not match.

Grammar

<statement> ::= <actions> “ if ” <expression>

<actions> ::= <action> | <action> “ ” <actions>

<action> ::= “ban” | “delete” | “kick” | “modwarn” | “reply ” <quoted_string>

<quoted_string> ::= ‘“’ <any> ‘“’

<expression> ::= <simple_expr> | <not_expr> | <paren_expr> | <compound_expr>

<simple_expr> ::= <field_name> “ ” <op> “ ” <value>

<not_expr> ::= “!” <expression>

<paren_expr> ::= “(” <expression> “)”

<compound_expr> ::= <and_expr> | <or_expr>

<and_expr> ::= <expression> “ and ” <expression>

<or_expr> ::= <expression> “ or ” <expression>

<field_name> ::= “content” | “author” | “author.id” | “author.name” | “author.joinage”

<op> ::= “==” | “!=” | “<” | “>” | “<=” | “>=” | “contains” | “!contains” | “matches” | “!matches”

<value> ::= <int> | <float> | <quoted_string> | <timespan> | <mention>

<timespan> ::= <timespan_component> | <timespan_component> <timespan>

<timespan_component> ::= <int> <timespan_unit>

<timespan_unit> ::= “d” | “h” | “m” | “s”

<mention> ::= “<@!” <int> “>”