| @@ -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 | |||