Adds documentation for safe arguments

Author: DerEchtePilz

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

@@ -1366,6 +1366,31 @@ void commandArguments() {
     })
     .register();
 /* ANCHOR_END: commandArguments3 */
+
+/* ANCHOR: commandArguments4 */
+StringArgument nameArgument = new StringArgument("name");
+IntegerArgument amountArgument = new IntegerArgument("amount");
+PlayerArgument playerArgument = new PlayerArgument("player");
+PlayerArgument targetArgument = new PlayerArgument("target");
+GreedyStringArgument messageArgument = new GreedyStringArgument("message");
+
+new CommandAPICommand("mycommand")
+    .withArguments(nameArgument)
+    .withArguments(amountArgument)
+    .withOptionalArguments(playerArgument)
+    .withOptionalArguments(targetArgument)
+    .withOptionalArguments(messageArgument)
+    .executesPlayer((player, args) -> {
+        String name = args.getByArgument(nameArgument);
+        int amount = args.getByArgument(amountArgument);
+        Player p = args.getByArgumentOrDefault(playerArgument, player);
+        Player target = args.getByArgumentOrDefault(targetArgument, player);
+        String message = args.getOptionalByArgument(messageArgument).orElse("Hello!");
+
+        // Do whatever with these values
+    })
+    .register();
+/* ANCHOR_END: commandArguments4 */
 }
 
 void commandFailures() {

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

@@ -1287,6 +1287,31 @@ CommandAPICommand("mycommand")
     })
     .register();
 /* ANCHOR_END: commandArguments3 */
+
+/* ANCHOR: commandArguments4 */
+val nameArgument = StringArgument("name")
+val amountArgument = IntegerArgument("amount")
+val playerArgument = PlayerArgument("player")
+val targetArgument = PlayerArgument("target")
+val messageArgument = GreedyStringArgument("message")
+
+CommandAPICommand("mycommand")
+    .withArguments(nameArgument)
+    .withArguments(amountArgument)
+    .withOptionalArguments(playerArgument)
+    .withOptionalArguments(targetArgument)
+    .withOptionalArguments(messageArgument)
+    .executesPlayer(PlayerCommandExecutor { player, args ->
+        val name: String = args.getByArgument(nameArgument)!!
+        val amount: Int = args.getByArgument(amountArgument)!!
+        val p: Player = args.getByArgumentOrDefault(playerArgument, player)
+        val target: Player = args.getByArgumentOrDefault(targetArgument, player)
+        val message: String = args.getOptionalByArgument(messageArgument).orElse("Hello!")
+
+        // Do whatever with these values
+    })
+    .register();
+/* ANCHOR_END: commandArguments4 */
 }
 
 fun commandFailures() {

docssrc/src/commandarguments.md

@@ -8,6 +8,7 @@ While the argument array just gives the possibility to access the arguments via
 - [Access arguments](#access-arguments)
 - [Access raw arguments](#access-raw-arguments)
 - [Access unsafe arguments](#access-unsafe-arguments)
+- [Access safe arguments](#access-safe-arguments)
 
 -----
 
@@ -254,3 +255,67 @@ Here, we don't actually want to cast the argument, so we use unsafe arguments to
 </div>
 
 </div>
+
+-----
+
+## Access safe arguments
+
+<div class="warning">
+
+**Developer's Note:**
+
+The following methods can not be used to access a value returned by a `CustomArgument` as its return type depends on the base argument for it.
+
+</div>
+
+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
+index or their node name:
+
+```java
+T getByClass(String nodeName, Class<T> argumentType);
+T getByClassOrDefault(String nodeName, Class<T> argumentType, T defaultValue);
+T getOptionalByClass(String nodeName, Class<T> argumentType);
+T getByClass(int index, Class<T> argumentType);
+T getByClassOrDefault(int index, Class<T> argumentType, T defaultValue);
+T getOptionalByClass(int index, Class<T> argumentType);
+```
+
+The main addition in contrast to all the other methods the `CommandArguments` class offers, these methods take an additional parameter of type `Class<T>` where `T` is the return type
+of the argument with the given node name or index.
+
+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:
+
+```java
+String value = args.getByClass("value", String.class);
+```
+
+### Access safe arguments using an argument instance
+
+Finally, there is one more, even safer way of accessing safe arguments: by using an argument instance:
+
+```java
+T getByArgument(Argument<T> argumentType);
+T getByArgumentOrDefault(Argument<T> argumentType, T defaultValue);
+T getOptionalByArgument(Argument<T> argumentType);
+```
+
+However, while safer, this also introduces the need to first initialize your arguments before you can start implementing your command.
+To visualize this, we want to implement the command from [Access arguments by node name and index](#example---access-arguments-by-node-name-and-index) again, this time using safe arguments with an argument instance:
+
+<div class="example">
+
+### Example - Access safe arguments using an argument instance
+
+<div class="multi-pre">
+
+```java,Java
+{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments4}}
+```
+
+```kotlin,Kotlin
+{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments4}}
+```
+
+</div>
+
+</div>

docssrc/src/intro.md

@@ -40,6 +40,7 @@ Here's the list of changes to the documentation between each update. You can vie
 ### Documentation changes 9.3.0 \\(\rightarrow\\) 9.4.0
 
 - Adds [Velocity](./velocity_intro.md) page to outline how to setup the CommandAPI for Velocity
+- Updates [CommandArguments](./commandarguments.md) to document new additions for safe arguments
 
 ### Documentation changes 9.2.0 \\(\rightarrow\\) 9.3.0