.. _filter:

======
Filter
======

This is the cog guide for the filter cog. You will
find detailed docs about usage and commands.

``[p]`` is considered as your prefix.

.. note:: To use this cog, load it by typing this::

        [p]load filter

.. _filter-usage:

-----
Usage
-----

This cog is designed for "filtering" unwanted words and phrases from a server.

It provides tools to manage a list of words or sentences, and to customize automatic actions to be taken against users who use those words in channels or in their name/nickname.

This can be used to prevent inappropriate language, off-topic discussions, invite links, and more.


.. _filter-commands:

--------
Commands
--------

.. _filter-command-filter:

^^^^^^
filter
^^^^^^

.. note:: |mod-lock|

**Syntax**

.. code-block:: none

    [p]filter 

**Description**

Base command to add or remove words from the server filter.

Use double quotes to add or remove sentences.

.. _filter-command-filter-add:

""""""""""
filter add
""""""""""

**Syntax**

.. code-block:: none

    [p]filter add [words...]

**Description**

Add words to the filter.

Use double quotes to add sentences.

Examples:
    - ``[p]filter add word1 word2 word3``
    - ``[p]filter add "This is a sentence"``

**Arguments:**

- ``[words...]`` The words or sentences to filter.

.. _filter-command-filter-channel:

""""""""""""""
filter channel
""""""""""""""

**Syntax**

.. code-block:: none

    [p]filter channel 

**Description**

Base command to add or remove words from the channel filter.

Use double quotes to add or remove sentences.

.. _filter-command-filter-channel-add:

""""""""""""""""""
filter channel add
""""""""""""""""""

**Syntax**

.. code-block:: none

    [p]filter channel add [words...]

**Description**

Add words to the filter.

Use double quotes to add sentences.

Examples:
    - ``[p]filter channel add word1 word2 word3``
    - ``[p]filter channel add "This is a sentence"``

**Arguments:**

- ``[words...]`` The words or sentences to filter.

.. _filter-command-filter-channel-list:

"""""""""""""""""""
filter channel list
"""""""""""""""""""

**Syntax**

.. code-block:: none

    [p]filter channel list 

**Description**

Send a list of the channel's filtered words.

.. _filter-command-filter-channel-remove:

"""""""""""""""""""""
filter channel remove
"""""""""""""""""""""

**Syntax**

.. code-block:: none

    [p]filter channel remove [words...]

**Description**

Remove words from the filter.

Use double quotes to remove sentences.

Examples:
    - ``[p]filter channel remove word1 word2 word3``
    - ``[p]filter channel remove "This is a sentence"``

**Arguments:**

- ``[words...]`` The words or sentences to no longer filter.

.. _filter-command-filter-delete:

"""""""""""""
filter delete
"""""""""""""

**Syntax**

.. code-block:: none

    [p]filter delete [words...]

.. tip:: Aliases: ``filter remove``, ``filter del``

**Description**

Remove words from the filter.

Use double quotes to remove sentences.

Examples:
    - ``[p]filter remove word1 word2 word3``
    - ``[p]filter remove "This is a sentence"``

**Arguments:**

- ``[words...]`` The words or sentences to no longer filter.

.. _filter-command-filter-list:

"""""""""""
filter list
"""""""""""

**Syntax**

.. code-block:: none

    [p]filter list 

**Description**

Send a list of this server's filtered words.

.. _filter-command-filter-names:

""""""""""""
filter names
""""""""""""

**Syntax**

.. code-block:: none

    [p]filter names 

**Description**

Toggle name and nickname filtering.

This is disabled by default.

.. _filter-command-filterset:

^^^^^^^^^
filterset
^^^^^^^^^

.. note:: |admin-lock|

**Syntax**

.. code-block:: none

    [p]filterset 

**Description**

Base command to manage filter settings.

.. _filter-command-filterset-ban:

"""""""""""""
filterset ban
"""""""""""""

**Syntax**

.. code-block:: none

    [p]filterset ban <count> <timeframe>

**Description**

Set the filter's autoban conditions.

Users will be banned if they send ``<count>`` filtered words in
``<timeframe>`` seconds.

Set both to zero to disable autoban.

Examples:
    - ``[p]filterset ban 5 5`` - Ban users who say 5 filtered words in 5 seconds.
    - ``[p]filterset ban 2 20`` - Ban users who say 2 filtered words in 20 seconds.

**Arguments:**

- ``<count>`` The amount of filtered words required to trigger a ban.
- ``<timeframe>`` The period of time in which too many filtered words will trigger a ban.

.. _filter-command-filterset-defaultname:

"""""""""""""""""""""
filterset defaultname
"""""""""""""""""""""

**Syntax**

.. code-block:: none

    [p]filterset defaultname <name>

**Description**

Set the nickname for users with a filtered name.

Note that this has no effect if filtering names is disabled
(to toggle, run ``[p]filter names``).

The default name used is *John Doe*.

Example:
    - ``[p]filterset defaultname Missingno``

**Arguments:**

- ``<name>`` The new nickname to assign.
