The WordFilter cog is intended to be used as a moderating tool to watch the server for the use of certain words, expressions or other strings. The bot has two separate lists of filter strings:
delete
list: Any messages that match will be auto-deleted, and moderators are notified.warn
list: Moderators are notified of the matching message, but no further action is taken.
Moderator notifications are output to either #mods or #bot-output. The output can be changed between these two channels with the .filter switch
command.
1. Filter string syntax
The special character %
will match a word boundary (any non-letter character - this means punctuation is considered, so don’t worry about that!). Consequently, each word/expression in the list can be matched in four different ways:
foo
: Matches any sub-stringfoo
, even if inside a word; for example, the wordsfoobar
,zoboomafoo
, andafoot
inside a message will all be caught.%foo
: Matches any word that starts withfoo
. For example,fooing
will match, butzoboomafoo
will not match.foo%
: Matches any word that ends withfoo
. For example,zoboomafoo
will match, butfoobar
will not.%foo%
: Matches whole words only.
You can also refer to the table below to see examples of which method will catch which sub-strings.
foo | %foo | foo% | %foo% | |
---|---|---|---|---|
foo | ||||
foobar | ||||
barfoo | ||||
barfoobar |
2. filter
For all sub-commands except .filter switch
, you usually need to specify the filter type, either del
(the auto-delete filter list) or warn
(the warn-only filter list). You can also use the shorthand w
or d
.
2.1 list (shorthand: l)
Lists the current filters.
If filter_type
is not given, lists all filters; otherwise, lists the specified filter.
Usage:
.filter list [filter_type]
.filter l [filter_type]
Arguments:
filter_type
: Optional. One of [warn
,del
,w
,d
]
Users: Moderators only
Channels: Mod and bot channels only
Examples:
.filter list
- Shows both auto-warn and auto-delete lists..filter list warn
- Shows warn filter list..filter list del
- Shows auto-delete filter list..filter l w
- Shows warn filter list (shorthand).
2.2 add (shorthand: a)
Add a new filter word/expression.
Usage:
.filter add [filter_type] [word]
.filter a [filter_type] [word]
Arguments:
filter_type
: One ofwarn
,del
,w
,d
word
: The word or expression to filter. If it has spaces, use quotation marks. Use%
at the beginning/end of the word to match word boundaries (otherwise substring matching is used).
Users: Moderators only
Channels: Mod and bot channels only
Examples:
.filter add warn %word%
- Adds “word” (as an exact word match) to the auto-warning list..filter add del "%pink flamingo%"
- Add “pink flamingo” (exact expression) to the auto-delete list..filter a w %talk
- Shorthand. Add “%talk” to the warning list - this will match any words that start with “talk”.
3.3 rem (shorthand: r)
rem
command (aliases r
and remove
) functioned as described in the rnum section.Remove a filter word/expression by word.
Usage:
.filter rem [filter_type] [word]
.filter r [filter_type] [word]
.filter remove [filter_type] [word]
Arguments:
filter_type
: One ofwarn
,del
,w
,d
word
: The word or expression to remove from the filter list. If it has spaces, use quotation marks.
Users: Moderators only
Channels: Mod and bot channels only
Examples:
.filter rem warn %word%
- Remove “%word%” from the auto-warning list..filter rem del "%pink flamingo%"
- Remove “%pink flamingo%” from the auto-delete list.
3.4 rnum
rem
in v2.0b3 (a.k.a. v1.3b3).Remove a filter word/expression by list index.
Usage:
.filter rid [filter_type] [index]
Arguments:
filter_type
: One ofwarn
,del
,w
,d
index
: The index number of the filter to remove. You can get this index number using thelist
command.
Users: Moderators only
Channels: Mod and bot channels only
Examples:
.filter rem del 5
- Removes the 5th rule in the auto-delete filter..filter r w 3
- Shorthand. Removes the 3rd rule in the warning-only filter.
3.5 switch (shorthand: s)
Change the bot output channel for wordfilter warnings.
Switches between the configured filter warning channel and the general bot output channel (#mods and #bot-output at time of writing).
Usage:
.filter switch
.filter s
Arguments: None
Users: Moderators only
Channels: Mod and bot channels only