[V3 permissions] command usage consistency (#1905)

* make the default rule settings consistent with the rest

* update docs to match new behavior

docs/cog_permissions.rst

@@ -89,8 +89,10 @@ Locking Audio to specific voice channel(s) as a serverowner or admin:
 
 .. code-block:: none
 
-    [p]permissions setguilddefault Audio deny
-    [p]permissions addguildrule allow Audio [voice channel ID or name]
+    [p]permissions setguilddefault deny play
+    [p]permissions setguilddefault deny "playlist start"
+    [p]permissions addguildrule allow play [voice channel ID or name]
+    [p]permissions addguildrule allow "playlist start" [voice channel ID or name]
 
 Allowing extra roles to use cleanup
 

redbot/cogs/permissions/converters.py

@@ -27,3 +27,18 @@ async def convert(self, ctx: commands.Context, arg: str) -> str:
         raise commands.BadArgument(
             '"{arg}" is not a valid rule. Valid rules are "allow" or "deny"'.format(arg=arg)
         )
+
+
+class ClearableRuleType(commands.Converter):
+    async def convert(self, ctx: commands.Context, arg: str) -> str:
+        if arg.lower() in ("allow", "whitelist", "allowed"):
+            return "allow"
+        if arg.lower() in ("deny", "blacklist", "denied"):
+            return "deny"
+        if arg.lower() in ("clear", "reset"):
+            return "clear"
+
+        raise commands.BadArgument(
+            '"{arg}" is not a valid rule. Valid rules are "allow" or "deny", or "clear" to remove the rule'
+            "".format(arg=arg)
+        )

redbot/cogs/permissions/permissions.py

@@ -11,7 +11,7 @@
 
 from .resolvers import val_if_check_is_valid, resolve_models, entries_from_ctx
 from .yaml_handler import yamlset_acl, yamlget_acl
-from .converters import CogOrCommand, RuleType
+from .converters import CogOrCommand, RuleType, ClearableRuleType
 from .mass_resolution import mass_resolve
 
 _models = ["owner", "guildowner", "admin", "mod", "all"]
@@ -521,18 +521,12 @@ async def rem_from_guild_rule(
     @checks.guildowner_or_permissions(administrator=True)
     @permissions.command(name="setdefaultguildrule")
     async def set_default_guild_rule(
-        self, ctx: commands.Context, cog_or_command: CogOrCommand, allow_or_deny: RuleType = None
+        self, ctx: commands.Context, allow_or_deny: ClearableRuleType, cog_or_command: CogOrCommand
     ):
         """
         Sets the default behavior for a cog or command if no rule is set
-
-        Use with a cog or command and no setting to clear the default and defer to
-        normal check logic
         """
-        if allow_or_deny:
-            val_to_set = {"allow": True, "deny": False}.get(allow_or_deny)
-        else:
-            val_to_set = None
+        val_to_set = {"allow": True, "deny": False, "clear": None}.get(allow_or_deny)
 
         model_type, type_name = cog_or_command
         async with self.config.guild(ctx.guild).owner_models() as models:
@@ -551,19 +545,12 @@ async def set_default_guild_rule(
     @checks.is_owner()
     @permissions.command(name="setdefaultglobalrule")
     async def set_default_global_rule(
-        self, ctx: commands.Context, cog_or_command: CogOrCommand, allow_or_deny: RuleType = None
+        self, ctx: commands.Context, allow_or_deny: ClearableRuleType, cog_or_command: CogOrCommand
     ):
         """
         Sets the default behavior for a cog or command if no rule is set
-
-        Use with a cog or command and no setting to clear the default and defer to
-        normal check logic
         """
-
-        if allow_or_deny:
-            val_to_set = {"allow": True, "deny": False}.get(allow_or_deny)
-        else:
-            val_to_set = None
+        val_to_set = {"allow": True, "deny": False, "clear": None}.get(allow_or_deny)
 
         model_type, type_name = cog_or_command
         async with self.config.owner_models() as models: