Merge pull request CommandAPI#540 from JorelAli/dev/safe-arguments

Implement "safe-casting"

Author: DerEchtePilz

README.md

@@ -428,6 +428,8 @@ This is the current roadmap for the CommandAPI (as of 11th May 2023):
                     <li>Fixed implementation issues with <code>FunctionArgument</code></li>
                     <li>https://github.com/JorelAli/CommandAPI/issues/490 Adds (experimental) support for Mojang-mapped servers via the CommandAPI config</li>
                     <li>https://github.com/JorelAli/CommandAPI/issues/524 Fixes <code>CommandAPIBukkit.get().getTags()</code> erroring in 1.20.4</li>
+                    <li>https://github.com/JorelAli/CommandAPI/issues/536, https://github.com/JorelAli/CommandAPI/pull/537 Fixes <code>MultiLiteralArgument</code> help displaying the node name instead of the literal text</li>
+                    <li>https://github.com/JorelAli/CommandAPI/pull/540 Add methods to "safe-cast" arguments to <code>CommandArguments</code></li>
                 </ul>
                 <b>Minecraft Version Changes:</b>
                 <ul>

commandapi-core/src/main/java/dev/jorel/commandapi/executors/CommandArguments.java

@@ -1,9 +1,12 @@
 package dev.jorel.commandapi.executors;
 
+import dev.jorel.commandapi.arguments.AbstractArgument;
+
 import javax.annotation.Nullable;
 
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
 import java.util.function.Supplier;
@@ -46,6 +49,17 @@ public record CommandArguments(
 	String fullInput
 ) {
 
+	private static final Map<Class<?>, Class<?>> PRIMITIVE_TO_WRAPPER = Map.of(
+		boolean.class, Boolean.class,
+		char.class, Character.class,
+		byte.class, Byte.class,
+		short.class, Short.class,
+		int.class, Integer.class,
+		long.class, Long.class,
+		float.class, Float.class,
+		double.class, Double.class
+	);
+
 	// Access the inner structure directly
 
 	/**
@@ -79,7 +93,7 @@ public String getFullInput() {
 	public int count() {
 		return args.length;
 	}
-	
+
 	// Main accessing methods. In Kotlin, methods named get() allows it to
 	// access these methods using array notation, as a part of operator overloading.
 	// More information about operator overloading in Kotlin can be found here:
@@ -342,7 +356,7 @@ public Optional<String> getRawOptional(String nodeName) {
 		}
 		return Optional.of(rawArgsMap.get(nodeName));
 	}
-	
+
 	/** Unchecked methods. These are the same as the methods above, but use
 	 * unchecked generics to conform to the type they are declared as. In Java,
 	 * the normal methods (checked) require casting:
@@ -367,7 +381,7 @@ public Optional<String> getRawOptional(String nodeName) {
 	public <T> T getUnchecked(int index) {
 		return (T) get(index);
 	}
-	
+
 	/**
 	 * Returns an argument by its node name
 	 *
@@ -443,4 +457,147 @@ public <T> Optional<T> getOptionalUnchecked(String nodeName) {
 		return (Optional<T>) getOptional(nodeName);
 	}
 
+	/*****************************************
+	 ********** SAFE-CAST ARGUMENTS **********
+	 *****************************************/
+
+	/**
+	 * Returns an argument purely based on its CommandAPI representation. This also attempts to directly cast the argument to the type represented by {@link dev.jorel.commandapi.arguments.AbstractArgument#getPrimitiveType()}
+	 *
+	 * @param argumentType The argument instance used to create the argument
+	 * @return The argument represented by the CommandAPI argument, or null if the argument was not found.
+	 */
+	@Nullable
+	public <T> T getByArgument(AbstractArgument<T, ?, ?, ?> argumentType) {
+		return castArgument(get(argumentType.getNodeName()), argumentType.getPrimitiveType(), argumentType.getNodeName());
+	}
+
+	/**
+	 * Returns an argument purely based on its CommandAPI representation or a default value if the argument wasn't found.
+	 * <p>
+	 * If the argument was found, this also attempts to directly cast the argument to the type represented by {@link dev.jorel.commandapi.arguments.AbstractArgument#getPrimitiveType()}
+	 *
+	 * @param argumentType The argument instance used to create the argument
+	 * @param defaultValue The default value to return if the argument wasn't found
+	 * @return The argument represented by the CommandAPI argument, or the default value if the argument was not found.
+	 */
+	public <T> T getByArgumentOrDefault(AbstractArgument<T, ?, ?, ?> argumentType, T defaultValue) {
+		T argument = getByArgument(argumentType);
+		return (argument != null) ? argument : defaultValue;
+	}
+
+	/**
+	 * Returns an <code>Optional</code> holding the provided argument. This <code>Optional</code> can be empty if the argument was not given when running the command.
+	 * <p>
+	 * This attempts to directly cast the argument to the type represented by {@link dev.jorel.commandapi.arguments.AbstractArgument#getPrimitiveType()}
+	 *
+	 * @param argumentType The argument instance used to create the argument
+	 * @return An <code>Optional</code> holding the argument, or an empty <code>Optional</code> if the argument was not found.
+	 */
+	public <T> Optional<T> getOptionalByArgument(AbstractArgument<T, ?, ?, ?> argumentType) {
+		return Optional.ofNullable(getByArgument(argumentType));
+	}
+
+	/**
+	 * Returns an argument based on its node name. This also attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param nodeName The node name of the argument
+	 * @param argumentType The class that represents the argument
+	 * @return The argument with the given node name, or null if the argument was not found.
+	 */
+	@Nullable
+	public <T> T getByClass(String nodeName, Class<T> argumentType) {
+		return castArgument(get(nodeName), argumentType, nodeName);
+	}
+
+	/**
+	 * Returns an argument based on its node name or a default value if the argument wasn't found.
+	 * <p>
+	 * If the argument was found, this method attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param nodeName The node name of the argument
+	 * @param argumentType The class that represents the argument
+	 * @param defaultValue The default value to return if the argument wasn't found
+	 * @return The argument with the given node name, or the default value if the argument was not found.
+	 */
+	public <T> T getByClassOrDefault(String nodeName, Class<T> argumentType, T defaultValue) {
+		T argument = getByClass(nodeName, argumentType);
+		return (argument != null) ? argument : defaultValue;
+	}
+
+	/**
+	 * Returns an <code>Optional</code> holding the argument with the given node name. This <code>Optional</code> can be empty if the argument was not given when running the command.
+	 * <p>
+	 * This attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param nodeName The node name of the argument
+	 * @param argumentType The class that represents the argument
+	 * @return An <code>Optional</code> holding the argument, or an empty <code>Optional</code> if the argument was not found.
+	 */
+	public <T> Optional<T> getOptionalByClass(String nodeName, Class<T> argumentType) {
+		return Optional.ofNullable(getByClass(nodeName, argumentType));
+	}
+
+	/**
+	 * Returns an argument based on its index. This also attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param index The index of the argument
+	 * @param argumentType The class that represents the argument
+	 * @return The argument at the given index, or null if the argument was not found.
+	 */
+	@Nullable
+	public <T> T getByClass(int index, Class<T> argumentType) {
+		return castArgument(get(index), argumentType, index);
+	}
+
+	/**
+	 * Returns an argument based on its index or a default value if the argument wasn't found.
+	 * <p>
+	 * If the argument was found, this method attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param index The index of the argument
+	 * @param argumentType The class that represents the argument
+	 * @param defaultValue The default value to return if the argument wasn't found
+	 * @return The argument at the given index, or the default value if the argument was not found.
+	 */
+	public <T> T getByClassOrDefault(int index, Class<T> argumentType, T defaultValue) {
+		T argument = getByClass(index, argumentType);
+		return (argument != null) ? argument : defaultValue;
+	}
+
+	/**
+	 * Returns an <code>Optional</code> holding the argument at the given index. This <code>Optional</code> can be empty if the argument was not given when running the command.
+	 * <p>
+	 * This attempts to directly cast the argument to the type represented by the {@code argumentType} parameter.
+	 *
+	 * @param index The index of the argument
+	 * @param argumentType The class that represents the argument
+	 * @return An <code>Optional</code> holding the argument, or an empty <code>Optional</code> if the argument was not found.
+	 */
+	public <T> Optional<T> getOptionalByClass(int index, Class<T> argumentType) {
+		return Optional.ofNullable(getByClass(index, argumentType));
+	}
+
+	private <T> T castArgument(Object argument, Class<T> argumentType, Object argumentNameOrIndex) {
+		if (argument == null) {
+			return null;
+		}
+		if (!PRIMITIVE_TO_WRAPPER.getOrDefault(argumentType, argumentType).isAssignableFrom(argument.getClass())) {
+			throw new IllegalArgumentException(buildExceptionMessage(argumentNameOrIndex, argument.getClass().getSimpleName(), argumentType.getSimpleName()));
+		}
+		return (T) argument;
+	}
+
+	private String buildExceptionMessage(Object argumentNameOrIndex, String expectedClass, String actualClass) {
+		if (argumentNameOrIndex instanceof Integer i) {
+			return "Argument at index '" + i + "' is defined as " + expectedClass + ", not " + actualClass;
+		}
+		if (argumentNameOrIndex instanceof String s) {
+			return "Argument '" + s + "' is defined as " + expectedClass + ", not " + actualClass;
+		}
+		throw new IllegalStateException("Unexpected behaviour detected while building exception message!" +
+			"This should never happen - if you're seeing this message, please" +
+			"contact the developers of the CommandAPI, we'd love to know how you managed to get this error!");
+	}
+
 }

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,75 @@ 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 cannot 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);
+```
+
+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
+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:
+
+<div class="multi-pre">
+
+```java,Java
+String value = args.getByClass("value", String.class);
+```
+
+```kotlin,Kotlin
+val value = args.getByClass("value", String::class.java)
+```
+
+</div>
+
+### 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, but 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