mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-06 11:18:54 -05:00
04e97f3516
* [V3 CustomCom] Custom Command Parameters
Allows specifying more parameters for CC's via {0}, {1}, etc. that will be filled by the user invoking the CC. Python-style type hinting and attribute access is also allowed for Discord and builtin types.
> [p]cc add simple greet Hi, {0.mention:Member}!
> ...
> [p]greet zephyrkul
> Hi, @zephyrkul!
The bot will reply with the standard help messages if the cc is incorrectly executed.
> [p]greet me
> Member "me" not found
* black formatting
* check command failure
Only call the custom command if the faked command succeeded.
* misc fixes
1) don't str.strip all the time, it's not family-friendly and doesn't match transform_parameter
2) transform_arg now actually returns strings in every case
3) improve prepare_args parsing security
4) help parameters will show what type they expect
5) make linter less angery
* customcom documentation
I hate rst
* don't require repeated type hinting
If a parameter was type hinted previously, don't require it again.
Ex: `{0.display_name:Member}#{0.discriminator}` is now possible.
* add cog_customcom.rts to index
I despise rst
* don't enforce order
Allow type hinting and attribute access to be in either order.
Ex. `{0:Member.mention}` is now valid.
* clean up on_message
We're building context anyway, may as well use it.
* [doc] correct cog name
Cog class is named CustomCommands, not CustomCom
* minor on_message optimization
only build context if it's needed
* update cc_add docstring
Old one wasn't user-friendly. Replaced with a link to the new docs.
Link will not function until PR is merged and docs refreshed.
* [doc] change repeat to say
repeat is an audio command, use say in the example instead
* compare ctx.prefix to None
allows for null prefixes, which is a bad idea but who am I to judge
* address review
* raise error on conflicting colon notation
bugfix I was working on but failed to actually commit
102 lines
3.7 KiB
ReStructuredText
102 lines
3.7 KiB
ReStructuredText
.. CustomCommands Cog Reference
|
|
|
|
============================
|
|
CustomCommands Cog Reference
|
|
============================
|
|
|
|
------------
|
|
How it works
|
|
------------
|
|
|
|
CustomCommands allows you to create simple commands for your bot without requiring you to code your own cog for Red.
|
|
|
|
If the command you attempt to create shares a name with an already loaded command, you cannot overwrite it with this cog.
|
|
|
|
------------------
|
|
Context Parameters
|
|
------------------
|
|
|
|
You can enhance your custom command's response by leaving spaces for the bot to substitute.
|
|
|
|
+-----------+----------------------------------------+
|
|
| Argument | Substitute |
|
|
+===========+========================================+
|
|
| {message} | The message the bot is responding to. |
|
|
+-----------+----------------------------------------+
|
|
| {author} | The user who called the command. |
|
|
+-----------+----------------------------------------+
|
|
| {channel} | The channel the command was called in. |
|
|
+-----------+----------------------------------------+
|
|
| {server} | The server the command was called in. |
|
|
+-----------+----------------------------------------+
|
|
| {guild} | Same as with {server}. |
|
|
+-----------+----------------------------------------+
|
|
|
|
You can further refine the response with dot notation. For example, {author.mention} will mention the user who called the command.
|
|
|
|
------------------
|
|
Command Parameters
|
|
------------------
|
|
|
|
You can further enhance your custom command's response by leaving spaces for the user to substitute.
|
|
|
|
To do this, simply put {#} in the response, replacing # with any number starting with 0. Each number will be replaced with what the user gave the command, in order.
|
|
|
|
You can refine the response with colon notation. For example, {0:Member} will accept members of the server, and {0:int} will accept a number. If no colon notation is provided, the argument will be returned unchanged.
|
|
|
|
+-----------------+--------------------------------+
|
|
| Argument | Substitute |
|
|
+=================+================================+
|
|
| {#:Member} | A member of your server. |
|
|
+-----------------+--------------------------------+
|
|
| {#:TextChannel} | A text channel in your server. |
|
|
+-----------------+--------------------------------+
|
|
| {#:Role} | A role in your server. |
|
|
+-----------------+--------------------------------+
|
|
| {#:int} | A whole number. |
|
|
+-----------------+--------------------------------+
|
|
| {#:float} | A decimal number. |
|
|
+-----------------+--------------------------------+
|
|
| {#:bool} | True or False. |
|
|
+-----------------+--------------------------------+
|
|
|
|
You can specify more than the above with colon notation, but those are the most common.
|
|
|
|
As with context parameters, you can use dot notation to further refine the response. For example, {0.mention:Member} will mention the Member specified.
|
|
|
|
----------------
|
|
Example commands
|
|
----------------
|
|
|
|
Showing your own avatar
|
|
|
|
.. code-block:: none
|
|
|
|
[p]customcom add simple avatar {author.avatar_url}
|
|
[p]avatar
|
|
https://cdn.discordapp.com/avatars/133801473317404673/be4c4a4fe47cb3e74c31a0504e7a295e.webp?size=1024
|
|
|
|
Repeating the user
|
|
|
|
.. code-block:: none
|
|
|
|
[p]customcom add simple say {0}
|
|
[p]say Pete and Repeat
|
|
Pete and Repeat
|
|
|
|
Greeting the specified member
|
|
|
|
.. code-block:: none
|
|
|
|
[p]customcom add simple greet Hello, {0.mention:Member}!
|
|
[p]greet Twentysix
|
|
Hello, @Twentysix!
|
|
|
|
Comparing two text channel's categories
|
|
|
|
.. code-block:: none
|
|
|
|
[p]customcom add simple comparecategory {0.category:TextChannel} | {1.category:TextChannel}
|
|
[p]comparecategory #support #general
|
|
Red | Community
|