Skip to content

Commit 8f91019

Browse files
MC-XiaoHeiMC-XiaoHei
committed
fix: add missing page
1 parent bd96aee commit 8f91019

File tree

7 files changed

+329
-17
lines changed

7 files changed

+329
-17
lines changed

‎docs/en/create-commands/arguments/arguments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ The type to cast each argument (declared in the `dev.jorel.commandapi.arguments`
140140
| [`MultiLiteralArgument`](./argument_multiliteral.md) | `String` |
141141
| [`NamespacedKeyArgument`](./argument_namespacedkey.md) | `org.bukkit.NamespacedKey` |
142142
| [`NBTCompoundArgument<T>`](./argument_nbt.md) | The cast type changes depending on whether you're shading the CommandAPI or using the CommandAPI as a plugin:<br /><ul><li>Shading:<br />`T` (implemented yourself)</li><br /><li>Plugin:<br />`dev.jorel.commandapi.nbtapi.NBTContainer`</li></ul> |
143-
| [`ObjectiveArgument`](./argument_objectives.md#objective-argument) | `org.bukkit.scoreboard.Objective` |
143+
| [`ObjectiveArgument`](.a/argument_objectives.md#objective-argument) | `org.bukkit.scoreboard.Objective` |
144144
| [`ObjectiveCriteriaArgument`](./argument_objectives.md#objective-criteria-argument) | `String` |
145145
| [`OfflinePlayerArgument`](./argument_entities.md#offlineplayer-argument) | `org.bukkit.OfflinePlayer` |
146146
| [`ParticleArgument`](./argument_particles.md) | `dev.jorel.commandapi.wrappers.ParticleData` |

‎docs/en/create-commands/arguments/command-arguments.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
---
2+
order: 2
3+
authors:
4+
- DerEchtePilz
5+
- willkroboth
6+
- JorelAli
7+
---
8+
9+
# The `CommandArguments` class
10+
11+
The `CommandArguments` class was introduced in CommandAPI 9.0.0 and provides a much more powerful way of accessing arguments than just an array of arguments which existed until 9.0.0.
12+
13+
While the argument array just gives the possibility to access the arguments via the array notation (`args[0]`), the `CommandArguments` class offers much more, including:
14+
15+
- [Access the inner structure directly](#access-the-inner-structure-directly)
16+
- [Access arguments](#access-arguments)
17+
- [Access raw arguments](#access-raw-arguments)
18+
- [Access unsafe arguments](#access-unsafe-arguments)
19+
- [Access safe arguments](#access-safe-arguments)
20+
21+
## Access the inner structure directly
22+
23+
To access the inner structure of the `CommandArguments` class directly, it provides various methods which you can learn about below:
24+
25+
**Get the argument array**
26+
27+
```java
28+
Object[] args();
29+
```
30+
31+
This returns the array of arguments as defined when creating your command.
32+
33+
**Get the arguments mapped to their node name**
34+
35+
```java
36+
Map<String, Object> argsMap();
37+
```
38+
39+
This returns an unmodifiable map which contains the arguments mapped to their node names.
40+
41+
**Get the raw argument array**
42+
43+
```java
44+
String[] rawArgs();
45+
```
46+
47+
This returns the array of raw arguments. An explanation of what raw arguments are can be found in the section about [accessing raw arguments](#access-raw-arguments).
48+
49+
**Get the raw arguments mapped to their node name**
50+
51+
```java
52+
Map<String, String> rawArgsMap();
53+
```
54+
55+
This returns an unmodifiable map which contains the raw arguments mapped to their node names. An explanation of what raw arguments are can be found in the section about [accessing raw arguments](#access-raw-arguments).
56+
57+
**Other useful methods**
58+
59+
```java
60+
String fullInput(); // Returns the full command input (including the / character)
61+
int count(); // Returns the amount of arguments
62+
```
63+
64+
## Access arguments
65+
66+
The `CommandArguments` class provides its arguments in a way similar to how a `List` or `Map` let you access their contents. When using these methods, you need to cast the arguments to their respective type. The `CommandArguments` class also provides a way to [access unsafe arguments](#access-unsafe-arguments).
67+
68+
You can choose to access arguments by their node name or by their index.
69+
70+
### Access arguments by node name
71+
72+
Accessing arguments by their node name is the recommended way of accessing arguments.
73+
74+
There are four methods you can use to access arguments by their node name:
75+
76+
```java
77+
Object get(String nodeName);
78+
Object getOrDefault(String nodeName, Object defaultValue);
79+
Object getOrDefault(String nodeName, Supplier<?> defaultValue);
80+
Optional<Object> getOptional(String nodeName);
81+
```
82+
83+
### Access arguments by index
84+
85+
Accessing arguments by their index is the original way of accessing arguments. However, we recommend to [access arguments by node name](#access-arguments-by-node-name).
86+
87+
Similar to the four methods of accessing arguments by their node name, there also are four methods you can use to access arguments by their index:
88+
89+
```java
90+
Object get(int index);
91+
Object getOrDefault(int index, Object defaultValue);
92+
Object getOrDefault(int index, Supplier<?> defaultValue);
93+
Optional<Object> getOptional(int index);
94+
```
95+
96+
::::tip Example - Access arguments by node name and index
97+
98+
To demonstrate the different ways of accessing arguments, we want to register a command `/mycommand` like this:
99+
100+
```mccmd
101+
/mycommand <name> <amount>
102+
/mycommand <name> <amount> <player>
103+
/mycommand <name> <amount> <player> <target>
104+
/mycommand <name> <amount> <player> <target> <message>
105+
```
106+
107+
This is how these commands are implemented:
108+
109+
:::tabs
110+
===Java
111+
```java
112+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments1}}
113+
```
114+
===Kotlin
115+
```kotlin
116+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments1}}
117+
```
118+
:::
119+
120+
::::
121+
122+
## Access raw arguments
123+
124+
A "raw argument" is the `String` form of an argument as written in a command. For example:
125+
126+
A user defines a command `/mycommand` that accepts a `double` as the first argument and an entity selector as the second argument. It could be executed with the values `15.3` as the `double` value and `@e` as the entity selector:
127+
128+
```mccmd
129+
/mycommand 15.3 @e
130+
```
131+
132+
When [accessing the raw arguments](#access-raw-arguments) of this command there are `15.3` and `@e` available as `String`s.
133+
134+
However, when [accessing the arguments](#access-arguments) of this command there is `15.3` available as `double` and `@e` available as `Collection<Entity>`.
135+
136+
Raw arguments are accessed basically the same way you would [access arguments](#access-arguments). You can access them by their node name and their index in the argument array.
137+
138+
### Access raw arguments by node name
139+
140+
Accessing raw arguments by their node name is the recommended way of doing it.
141+
142+
To access raw arguments by their node name, you can use these methods:
143+
144+
```java
145+
String getRaw(String nodeName);
146+
String getOrDefaultRaw(String nodeName, String defaultValue);
147+
String getOrDefaultRaw(String nodeName, Supplier<String> defaultValue);
148+
Optional<String> getRawOptional(String nodeName);
149+
```
150+
151+
### Access raw arguments by index
152+
153+
Of course, if you don't want to access raw arguments by their node name, we also provide the option to access them by index with these methods:
154+
155+
```java
156+
String getRaw(int index);
157+
String getOrDefaultRaw(int index, String defaultValue);
158+
String getOrDefaultRaw(int index, Supplier<String> defaultValue);
159+
Optional<String> getRawOptional(int index);
160+
```
161+
162+
::::tip Example - Access raw arguments by node name and index
163+
164+
To demonstrate how to access raw arguments, we are going to implement the `/mycommand` again, this time with the following syntax:
165+
166+
```mccmd
167+
/mycommand <entities>
168+
```
169+
170+
We want to find out which entity selector is being used when the command is executed.
171+
172+
:::tabs
173+
===Java
174+
```java
175+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments2}}
176+
```
177+
===Kotlin
178+
```kotlin
179+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments2}}
180+
```
181+
:::
182+
183+
::::
184+
185+
## Access unsafe arguments
186+
187+
When [accessing arguments](#access-arguments) you need to cast the `Object` returned by these methods to the type the argument returns. More about casting arguments [here](./arguments#argument-casting).
188+
189+
Unsafe arguments provide the ability to access an argument without needing to cast it to the argument's type. When not using unsafe arguments, your code looks like this:
190+
191+
```java
192+
String name = (String) args.get("name");
193+
```
194+
195+
When using unsafe arguments you can make your code look like this:
196+
197+
```java
198+
String name = args.getUnchecked("name");
199+
```
200+
201+
Unsafe arguments can also be accessed by their node names and their indices.
202+
203+
### Access arguments by node name
204+
205+
Unsafe arguments can also be accessed by node name which, again, is the recommended way of doing it.
206+
207+
Use these methods when accessing unsafe arguments by their node name:
208+
209+
```java
210+
T getUnchecked(String nodeName);
211+
T getOrDefaultUnchecked(String nodeName, T defaultValue);
212+
T getOrDefaultUnchecked(String nodeName, Supplier<T> defaultValue);
213+
Optional<T> getOptionalUnchecked(String nodeName);
214+
```
215+
216+
### Access arguments by index
217+
218+
If you want to access unsafe arguments by index, you can do that by using these methods:
219+
220+
```java
221+
T getUnchecked(int index);
222+
T getOrDefaultUnchecked(int index, T defaultValue);
223+
T getOrDefaultUnchecked(int index, Supplier<T> defaultValue);
224+
Optional<T> getOptionalUnchecked(int index);
225+
```
226+
227+
::::tip Example - Access unsafe arguments by node name and index
228+
229+
Finally, we want to implement the `/mycommand` again. This time we use this syntax:
230+
231+
```mccmd
232+
/mycommand <player>
233+
```
234+
235+
Here, we don't actually want to cast the argument, so we use unsafe arguments to remove that cast:
236+
237+
:::tabs
238+
===Java
239+
```java
240+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments3}}
241+
```
242+
===Kotlin
243+
```kotlin
244+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments3}}
245+
```
246+
:::
247+
248+
::::
249+
250+
## Access safe arguments
251+
252+
:::warning **Developer's Note:**
253+
254+
The following methods cannot be used to access a value returned by a `CustomArgument` as its return type depends on the base argument for it.
255+
256+
:::
257+
258+
Lastly, the CommandArguments class offers you a way to access your arguments in a more safe way by using internal casts. Again, methods are offered to access arguments by their
259+
index or their node name:
260+
261+
```java
262+
T getByClass(String nodeName, Class<T> argumentType);
263+
T getByClassOrDefault(String nodeName, Class<T> argumentType, T defaultValue);
264+
T getOptionalByClass(String nodeName, Class<T> argumentType);
265+
T getByClass(int index, Class<T> argumentType);
266+
T getByClassOrDefault(int index, Class<T> argumentType, T defaultValue);
267+
T getOptionalByClass(int index, Class<T> argumentType);
268+
```
269+
270+
Compared to the other methods the `CommandArguments` class offers, these methods take an additional parameter of type `Class<T>` where `T` is the return type
271+
of the argument with the given node name or index.
272+
273+
For example, say you declared a `new StringArgument("value")` and you now want to access the return value of this argument using safe casting. This would be done as follows:
274+
275+
:::tabs
276+
===Java
277+
```java
278+
String value = args.getByClass("value", String.class);
279+
```
280+
===Kotlin
281+
```kotlin
282+
val value = args.getByClass("value", String::class.java)
283+
```
284+
:::
285+
286+
### Access safe arguments using an argument instance
287+
288+
Finally, there is one more, even safer way of accessing safe arguments: by using an argument instance:
289+
290+
```java
291+
T getByArgument(Argument<T> argumentType);
292+
T getByArgumentOrDefault(Argument<T> argumentType, T defaultValue);
293+
T getOptionalByArgument(Argument<T> argumentType);
294+
```
295+
296+
However, while safer, this also introduces the need to first initialize your arguments before you can start implementing your command.
297+
To visualize this, we want to implement the command from [Access arguments by node name and index](#access-arguments-by-index) again, but this time using safe arguments with an argument instance:
298+
299+
::::tip Example - Access safe arguments using an argument instance
300+
301+
:::tabs
302+
===Java
303+
```java
304+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments4}}
305+
```
306+
===Kotlin
307+
```kotlin
308+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments4}}
309+
```
310+
:::
311+
312+
::::

‎docs/en/create-commands/arguments/listed-arguments.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
order: 3
2+
order: 4
33
authors:
44
- DerEchtePilz
55
- willkroboth
@@ -8,9 +8,9 @@ authors:
88

99
# Listed arguments
1010

11-
Arguments have a setting which determine whether they are present in the [`CommandArguments args`](./arguments) that is populated when executing a command.
11+
Arguments have a setting which determine whether they are present in the [`CommandArguments args`](./command-arguments) that is populated when executing a command.
1212

13-
By default, the `LiteralArgument` has this setting set to `false`, hence the literal values are _not_ present in the [`CommandArguments args`](arguments).
13+
By default, the `LiteralArgument` has this setting set to `false`, hence the literal values are _not_ present in the [`CommandArguments args`](command-arguments).
1414

1515
This flag is set using the following function:
1616

@@ -26,7 +26,7 @@ Say we have the following command:
2626
/mycommand <player> <value> <message>
2727
```
2828

29-
Let's also say that in our implementation of this command, we don't actually perform any processing for `<value>`. Hence, listing it in the [`CommandArguments args`](./arguments) is unnecessary.
29+
Let's also say that in our implementation of this command, we don't actually perform any processing for `<value>`. Hence, listing it in the [`CommandArguments args`](./command-arguments) is unnecessary.
3030

3131
:::tabs
3232
===Java
@@ -39,6 +39,6 @@ Let's also say that in our implementation of this command, we don't actually per
3939
```
4040
:::
4141

42-
In this scenario, the argument `<value>` is not present in the [`CommandArguments args`](./arguments) for the executor.
42+
In this scenario, the argument `<value>` is not present in the [`CommandArguments args`](./command-arguments) for the executor.
4343

4444
::::

‎docs/en/create-commands/arguments/optional-arguments.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
order: 2
2+
order: 3
33
authors:
44
- DerEchtePilz
55
- JorelAli
@@ -83,7 +83,7 @@ However, calling `withOptionalArguments` is safer because it makes sure that the
8383

8484
## Avoiding null values
8585

86-
Previously, we've looked at how to handle null values. To make all of this easier, the CommandAPI implements multiple additional methods for [`CommandArguments`](./arguments):
86+
Previously, we've looked at how to handle null values. To make all of this easier, the CommandAPI implements multiple additional methods for [`CommandArguments`](./command-arguments):
8787

8888
```java
8989
Object getOrDefault(int index, Object defaultValue);

‎docs/en/create-commands/arguments/suggestions/safe-suggestions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ SafeSuggestions<T> tooltipsAsync(Function<SuggestionInfo, CompletableFuture<Tool
4040

4141
Not all arguments support safe suggestions. This is mostly due to implementation constraints or inadequate support by the Bukkit API.
4242

43-
The list of supported arguments are displayed in the following table. The parameter `T` (shown in the method signatures above) are also provided for each argument. This parameter is the same as the cast argument described in [Argument Casting](../arguments#argument-casting), except for a few exceptions which are outlined in **bold**.
43+
The list of supported arguments are displayed in the following table. The parameter `T` (shown in the method signatures above) are also provided for each argument. This parameter is the same as the cast argument described in [Argument Casting](../command-arguments#argument-casting), except for a few exceptions which are outlined in **bold**.
4444

4545
| Argument | Class (T) |
4646
|---------------------------------------------------------------------------------:|:-----------------------------------------------|

‎docs/en/create-commands/arguments/suggestions/string-suggestions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ $$
101101
\text{/execute run} \xrightarrow{\text{redirect}} \text{mycommand arg1 arg2 arg3}
102102
$$
103103

104-
It is not possible to access the [`CommandArguments`](../arguments) of previously declared arguments. **If a command occurs via a redirect, the [`CommandArguments`](../arguments) of previously declared arguments will be null**.
104+
It is not possible to access the [`CommandArguments`](../command-arguments) of previously declared arguments. **If a command occurs via a redirect, the [`CommandArguments`](../command-arguments) of previously declared arguments will be null**.
105105

106106
:::
107107

0 commit comments

Comments
 (0)