| @@ -7,15 +7,16 @@ title: Named Arguments | |||||
| By default, arguments for commands are parsed positionally, meaning | By default, arguments for commands are parsed positionally, meaning | ||||
| that the order matters. But sometimes you may want to define a command | 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 | ## Setting up Named Arguments | ||||
| In order to be able to specify different arguments by name, you have | 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 | 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 | ### 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: | The command where you want to use these values can be declared like so: | ||||
| ```cs | ```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) | 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 | A TypeReader for the named arguments container type is | ||||
| automatically registered. | automatically registered. | ||||
| It's important that any other arguments that would be required | It's important that any other arguments that would be required | ||||
| @@ -45,31 +49,31 @@ are placed before the container type. | |||||
| > [!IMPORTANT] | > [!IMPORTANT] | ||||
| > A single command can have only __one__ parameter of a | > 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. | > **MUST** be the last parameter in the list. | ||||
| > A command parameter of such an annotated type | > A command parameter of such an annotated type | ||||
| > is automatically treated as if that parameter | > 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 | The TypeReader for Named Argument Types will look for a TypeReader | ||||
| of every property type, meaning any other command parameter type | of every property type, meaning any other command parameter type | ||||
| will work just the same. | will work just the same. | ||||
| You can also read multiple values into a single property | 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 | ```cs | ||||
| public IEnumerable<int> Numbers { get; set; } | 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"` | `.cmd numbers: "1, 2, 4, 8, 16, 32"` | ||||
| ## Additional | |||||
| ## Additional Notes | |||||
| The use of [`[OverrideTypeReader]`](xref:Discord.Commands.OverrideTypeReaderAttribute) | The use of [`[OverrideTypeReader]`](xref:Discord.Commands.OverrideTypeReaderAttribute) | ||||
| is also supported on the properties of a Named Argument Type. | is also supported on the properties of a Named Argument Type. | ||||
| [NamedArgumentTypeAttribute]: xref:Discord.Commands.NamedArgumentTypeAttribute | |||||