new mention behavior, new filter behavior (#3553)

* new mention behavior, new filter behavior

* and here too, ffs

* docs and reformat

* review handling

redbot/core/utils/common_filters.py

@@ -1,4 +1,7 @@
 import re
+from typing import Iterable
+
+import discord
 
 __all__ = [
     "URL_RE",
@@ -11,6 +14,7 @@ __all__ = [
     "normalize_smartquotes",
     "escape_spoilers",
     "escape_spoilers_and_mass_mentions",
+    "sanitize_role_mentions",
 ]
 
 # regexes
@@ -173,3 +177,32 @@ def escape_spoilers_and_mass_mentions(content: str) -> str:
         The escaped string.
     """
     return escape_spoilers(filter_mass_mentions(content))
+
+
+def sanitize_role_mentions(content: str, roles: Iterable[discord.Role]) -> str:
+    """
+    Swaps out role mentions for @RoleName
+
+    This should always be used prior to filtering everyone mentions
+
+    Parameters
+    ----------
+    content: str
+        The string to make substitutions to
+    roles: Iterable[discord.Role]
+        The roles to make substitutions for
+
+    Returns
+    -------
+    str
+        The resulting string
+    """
+    transformations = {re.escape(fr"<@&{role.id}>"): f"@{role.name}" for role in roles}
+
+    def repl(obj):
+        return transformations.get(re.escape(obj.group(0)), "")
+
+    pattern = re.compile("|".join(transformations.keys()))
+    result = pattern.sub(repl, content)
+
+    return result