Implementing optional arguments

commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java

@@ -1306,21 +1306,17 @@ void resultingcommandexecutor3(){
 {
 /* ANCHOR: argumentkillcmd */
 new CommandAPICommand("kill")
+    .withOptionalArguments(new PlayerArgument("target"))
     .executesPlayer((player, args) -> {
-        player.setHealth(0);
+        Player target = (Player) args.get("target");
+        if (target != null) {
+            target.setHealth(0.0);
+        } else {
+            player.setHealth(0.0);
+        }
     })
     .register();
 /* ANCHOR_END: argumentkillcmd */
-
-/* ANCHOR: argumentkillcmd2 */
-// Register our second /kill <target> command
-new CommandAPICommand("kill")
-    .withArguments(new PlayerArgument("target"))
-    .executesPlayer((player, args) -> {
-        ((Player) args.get(0)).setHealth(0);
-    })
-    .register();
-/* ANCHOR_END: argumentkillcmd2 */
 }
 
 @SuppressWarnings("unused")

commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt

@@ -1233,21 +1233,16 @@ CommandAPICommand("mycommand")
 fun argumentkillcmd() {
 /* ANCHOR: argumentkillcmd */
 CommandAPICommand("kill")
-    .executesPlayer(PlayerCommandExecutor { player, _ ->
-        player.setHealth(0.0)
-    })
-    .register()
+    .withOptionalArguments(PlayerArgument("target"))
+    .executesPlayer(PlayerCommandExecutor { player, args ->
+        val target: Player? = args.get("target") as Player?
+        if (target != null) {
+            target.health = 0.0
+        } else {
+            player.health = 0.0
+        }
+    }).register()
 /* ANCHOR_END: argumentkillcmd */
-
-/* ANCHOR: argumentkillcmd2 */
-// Register our second /kill <target> command
-CommandAPICommand("kill")
-    .withArguments(PlayerArgument("target"))
-    .executesPlayer(PlayerCommandExecutor { _, args ->
-        (args[0] as Player).setHealth(0.0)
-    })
-    .register()
-/* ANCHOR_END: argumentkillcmd2 */
 }
 
 @Suppress("unused")
@@ -1727,7 +1722,7 @@ fun argumentsuggestions2_2() {
 /* ANCHOR: ArgumentSuggestions2_2 */
 val arguments = listOf<Argument<*>>(
     PlayerArgument("friend").replaceSuggestions(ArgumentSuggestions.strings({ info ->
-		Friends.getFriends(info.sender())
+        Friends.getFriends(info.sender())
     }))
 )
 

commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt

@@ -1386,21 +1386,17 @@ commandAPICommand("mycommand") {
 fun argumentkillcmd() {
 /* ANCHOR: argumentkillcmd */
 commandAPICommand("kill") {
-    playerExecutor { player, _ ->
-        player.health = 0.0
+    optionalArgument(PlayerArgument("target"))
+    playerExecutor { player, args ->
+        val target: Player? = args["target"] as Player?
+        if (target != null) {
+            target.health = 0.0
+        } else {
+            player.health = 0.0
+        }
     }
 }
 /* ANCHOR_END: argumentkillcmd */
-
-/* ANCHOR: argumentkillcmd2 */
-// Register our second /kill <target> command#
-commandAPICommand("kill") {
-    playerArgument("target")
-    playerExecutor { _, args ->
-        (args[0] as Player).health = 0.0
-    }
-}
-/* ANCHOR_END: argumentkillcmd2 */
 }
 
 @Suppress("unused")

docssrc/src/arguments.md

@@ -161,15 +161,13 @@ The type to cast each argument (declared in the `dev.jorel.commandapi.arguments`
 
 ## 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 command syntax:
+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
 ```
 
-As shown by the command syntax, we need to register _two commands_.
-
 <div class="example">
 
 ### Example - /kill command with two separate arguments
@@ -181,7 +179,7 @@ For example, say we're registering a command `/kill`:
 /kill <target> - Kills a target player
 ```
 
-We first register the first `/kill` command as normal:
+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">
 
@@ -199,26 +197,23 @@ We first register the first `/kill` command as normal:
 
 </div>
 
-Now we declare our command with arguments for our second command. Then, we can register our second command `/kill <target>` as usual:
+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.
 
-<div class="multi-pre">
+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!
 
-```java,Java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentkillcmd2}}
-```
-
-```kotlin,Kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentkillcmd2}}
-```
-
-```kotlin,Kotlin_DSL
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentkillcmd2}}
-```
+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>
 
-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.
+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"))
+```
 
-In this example, we use the simpler, inline `.withArguments(Argument... arguments)` method to register our argument. There is no difference to using this method as opposed to explicitly declaring a list and using `.withArguments(List<Argument> arguments)`, so feel free to use whichever method you want!
+```java
+new CommandAPICommand("optional")
+    .withArguments(new PlayerArgument("target").setOptional(true))
+```
 
-</div>
+However, calling `withOptionalArguments` is safer because it makes sure that the argument is optional.