|
|
@@ -7,15 +7,16 @@ title: Named Arguments |
|
|
|
|
|
|
|
By default, arguments for commands are parsed positionally, meaning |
|
|
|
that the order matters. But sometimes you may want to define a command |
|
|
|
with many optional parameters and it'd be easier for users to specify |
|
|
|
only what they want to set instead of needing them to specify everything. |
|
|
|
with many optional parameters, and it'd be easier for developers |
|
|
|
to only specify what they want to set, instead of needing them |
|
|
|
to specify everything by hand. |
|
|
|
|
|
|
|
## Setting up Named Arguments |
|
|
|
|
|
|
|
In order to be able to specify different arguments by name, you have |
|
|
|
to create a new class that contains all of the optional values that |
|
|
|
the command will use and applying an instance of |
|
|
|
[`NamedArgumentTypeAttribute`](xref:Discord.Commands.NamedArgumentTypeAttribute) on it. |
|
|
|
the command will use, and apply an instance of |
|
|
|
[NamedArgumentTypeAttribute] on it. |
|
|
|
|
|
|
|
### Example - Creating a Named Arguments Type |
|
|
|
|
|
|
@@ -30,7 +31,7 @@ public class NamableArguments |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
## Use in a command |
|
|
|
## Usage in a Command |
|
|
|
|
|
|
|
The command where you want to use these values can be declared like so: |
|
|
|
```cs |
|
|
@@ -38,6 +39,9 @@ The command where you want to use these values can be declared like so: |
|
|
|
public async Task Act(int requiredArg, NamableArguments namedArgs) |
|
|
|
``` |
|
|
|
|
|
|
|
The command can now be invoked as |
|
|
|
`.act 42 first: Hello fourth: "A string with spaces must be wrapped in quotes" second: World`. |
|
|
|
|
|
|
|
A TypeReader for the named arguments container type is |
|
|
|
automatically registered. |
|
|
|
It's important that any other arguments that would be required |
|
|
@@ -45,31 +49,31 @@ are placed before the container type. |
|
|
|
|
|
|
|
> [!IMPORTANT] |
|
|
|
> A single command can have only __one__ parameter of a |
|
|
|
> type annotated with `[NamedArgumentType]` and it |
|
|
|
> type annotated with [NamedArgumentTypeAttribute], and it |
|
|
|
> **MUST** be the last parameter in the list. |
|
|
|
> A command parameter of such an annotated type |
|
|
|
> is automatically treated as if that parameter |
|
|
|
> has [`[Remainder]`](xref:Discord.Commands.RemainderAttribute) |
|
|
|
|
|
|
|
The command can now be invoked as follows: |
|
|
|
`.act 42 first: Hello fourth: "A string with spaces must be wrapped in quotes" second: World` |
|
|
|
> has [RemainderAttribute](xref:Discord.Commands.RemainderAttribute) |
|
|
|
> applied. |
|
|
|
|
|
|
|
## Complex types |
|
|
|
## Complex Types |
|
|
|
|
|
|
|
The TypeReader for Named Argument Types will look for a TypeReader |
|
|
|
of every property type, meaning any other command parameter type |
|
|
|
will work just the same. |
|
|
|
|
|
|
|
You can also read multiple values into a single property |
|
|
|
by making that property an `IEnumerable<T>`. So if your |
|
|
|
Named Argument Type has, for example: |
|
|
|
by making that property an `IEnumerable<T>`. So for example, if your |
|
|
|
Named Argument Type has the following field, |
|
|
|
```cs |
|
|
|
public IEnumerable<int> Numbers { get; set; } |
|
|
|
``` |
|
|
|
the command can be invoked as: |
|
|
|
then the command can be invoked as |
|
|
|
`.cmd numbers: "1, 2, 4, 8, 16, 32"` |
|
|
|
|
|
|
|
## Additional |
|
|
|
## Additional Notes |
|
|
|
|
|
|
|
The use of [`[OverrideTypeReader]`](xref:Discord.Commands.OverrideTypeReaderAttribute) |
|
|
|
is also supported on the properties of a Named Argument Type. |
|
|
|
|
|
|
|
[NamedArgumentTypeAttribute]: xref:Discord.Commands.NamedArgumentTypeAttribute |