create optional_arguments.md

CommandAPI · JorelAli · Jan 4, 2023 · Jan 3, 2023 · Jan 4, 2023 · Jan 4, 2023
commit a25547d07541f36c544c5c9826ba91302c93f09a
diff --git a/...ndapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt b/...ndapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt
@@ -1235,7 +1235,7 @@ fun argumentkillcmd() {
 CommandAPICommand("kill")
     .withOptionalArguments(PlayerArgument("target"))
     .executesPlayer(PlayerCommandExecutor { player, args ->
-        val target: Player? = args.get("target") as Player?
+        val target: Player? = args["target"] as Player?
         if (target != null) {
             target.health = 0.0
         } else {

diff --git a/docssrc/src/SUMMARY.md b/docssrc/src/SUMMARY.md
@@ -32,6 +32,7 @@
   - [Resulting command executors](./resultingcommandexecutors.md)
   - [Handling command failures](./commandfailures.md)
 - [Command arguments](./arguments.md)
+  - [Optional arguments](./optional_arguments.md)
   - [Listed arguments](./listed.md)
   - [Argument suggestions](./argumentsuggestions.md)
     - [The SuggestionsInfo record](./suggestionsinfo.md)

diff --git a/docssrc/src/arguments.md b/docssrc/src/arguments.md
@@ -156,64 +156,3 @@ The type to cast each argument (declared in the `dev.jorel.commandapi.arguments`
 |                                                                   [`TimeArgument`](./argument_time.md) | `int`                                                                                                                                                                                                                                               |
 |                                                                   [`UUIDArgument`](./argument_uuid.md) | `java.util.UUID`                                                                                                                                                                                                                                    |
 |                                                            [`WorldArgument`](./argument_world.md) | `org.bukkit.World`                                                                                                                                                                                                                                  |
-
------
-
-## Optional/Different Arguments
-
-Sometimes, you want to register a command that has a different effect whether arguments are included or not. For example, take the `/kill` command. If you run `/kill` on its own, it will kill the command sender. If however you run `/kill <target>`, it will kill the target. In other words, we have the following command syntax:
-
-```mccmd
-/kill          - Kills yourself
-/kill <target> - Kills a target player
-```
-
-<div class="example">
-
-### Example - /kill command with two separate arguments
-
-For example, say we're registering a command `/kill`:
-
-```mccmd
-/kill          - Kills yourself
-/kill <target> - Kills a target player
-```
-
-For that, we are going to register a command `/kill`. To add optional arguments, we are going to use the `withOptionalArguments(Argument... args)` method:
-
-<div class="multi-pre">
-
-```java,Java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentkillcmd}}
-```
-
-```kotlin,Kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentkillcmd}}
-```
-
-```kotlin,Kotlin_DSL
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentkillcmd}}
-```
-
-</div>
-
-This gives us the ability to run both `/kill` and `/kill <target>` with the same command name "kill", but have different results based on the arguments used.
-
-In this example, we use the simpler, inline `.withOptionalArguments(Argument... arguments)` method to register our argument. There is no difference to using this method as opposed to explicitly declaring a list and using `.withOptionalArguments(List<Argument> arguments)`, so feel free to use whichever method you want!
-
-You will also notice that we use `args.get("target")` to get the Player out of the arguments. This is safer than using `args.get(0)` because that will result in an `ArrayIndexOutOfBoundsException` whereas calling `args.get("target")` will return `null` if the argument was not provided.
-
-</div>
-
-One thing to note when using the `withOptionalArguments` method is that this calls the `setOptional()` method internally. This means that the following two examples are identical:
-```java
-new CommandAPICommand("optional")
-    .withOptionalArguments(new PlayerArgument("target"))
-```
-
-```java
-new CommandAPICommand("optional")
-    .withArguments(new PlayerArgument("target").setOptional(true))
-```
-
-However, calling `withOptionalArguments` is safer because it makes sure that the argument is optional.
diff --git a/docssrc/src/optional_arguments.md b/docssrc/src/optional_arguments.md
@@ -0,0 +1,70 @@
+## Optional Arguments
+
+Sometimes, you want to implement a command that has arguments that do not need to be entered. Take a `/kill` command for example. You may want to kill yourself, or another player. For that, we want this command syntax:
+
+```mccmd
+/kill          - Kills yourself
+/kill <target> - Kills a target player
+```
+
+To implement these commands, the CommandAPI provides two methods to help you with that:
+
+```java
+Argument withOptionalArguments(List<Argument<?>> args)
+Argument withOptionalArguments(Argument<?>... args)
+```
+
+<div class="example">
+
+### Example - /kill command with two separate arguments
+
+For example, say we're registering a command `/kill`:
+
+```mccmd
+/kill          - Kills yourself
+/kill <target> - Kills a target player
+```
+
+For that, we are going to register a command `/kill`. To add optional arguments, we are going to use the `withOptionalArguments(Argument... args)` method:
+
+<div class="multi-pre">
+
+```java,Java
+{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentkillcmd}}
+```
+
+```kotlin,Kotlin
+{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentkillcmd}}
+```
+
+```kotlin,Kotlin_DSL
+{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentkillcmd}}
+```
+
+</div>
+
+This gives us the ability to run both `/kill` and `/kill <target>` with the same command name "kill", but have different results based on the arguments used.
+
+You can notice two things:
+- We use the `withOptionalArguments` method to add an optional argument to a command
+- We use `args.get("target")` to get our player out of the arguments
+
+With optional arguments, there is a possibility of them being not present in the arguments of a command. The reason we use `args.get("target")` is that this will just return `null` and you can handle what should happen.
+
+If you use `args.get(0)` this will just throw an `ArrayIndexOutOfBoundsException` every time the command is executed without providing the optional argument.
+
+</div>
+
+One thing to note when using the `withOptionalArguments` method is that this calls the `setOptional()` method internally. This means that the following two examples are identical:
+
+```java
+new CommandAPICommand("optional")
+    .withOptionalArguments(new PlayerArgument("target"))
+```
+
+```java
+new CommandAPICommand("optional")
+    .withArguments(new PlayerArgument("target").setOptional(true))
+```
+
+However, calling `withOptionalArguments` is safer because it makes sure that the argument is optional because of that internal call.