Browse Source

Implement minor stylistic changes

pull/1437/head
Still Hsu 5 years ago
parent
commit
ccdb87c90e
No known key found for this signature in database GPG Key ID: C176DD7907FF62A7
1 changed files with 19 additions and 15 deletions
  1. +19
    -15
      docs/guides/commands/namedarguments.md

+ 19
- 15
docs/guides/commands/namedarguments.md View File

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

Loading…
Cancel
Save