Browse Source

Implement minor stylistic changes

pull/1484/head
Still Hsu 5 years ago
parent
commit
d6dddd2778
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
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

Loading…
Cancel
Save