Allow developers to control Arguments' CommandSyntaxExceptions

commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPI.java

@@ -14,7 +14,7 @@
  * Class to register commands with the 1.13 command UI
  *
  */
-public class CommandAPI {
+public final class CommandAPI {
 	// Cannot be instantiated
 	private CommandAPI() {
 	}

commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIHandler.java

@@ -20,26 +20,8 @@
  *******************************************************************************/
 package dev.jorel.commandapi;
 
-import java.awt.Component;
-import java.io.File;
-import java.io.IOException;
-import java.lang.invoke.MethodHandles;
-import java.lang.invoke.VarHandle;
-import java.lang.reflect.Field;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Set;
-import java.util.TreeMap;
-import java.util.concurrent.CompletableFuture;
-import java.util.function.Predicate;
-
 import com.mojang.brigadier.Command;
+import com.mojang.brigadier.arguments.ArgumentType;
 import com.mojang.brigadier.builder.ArgumentBuilder;
 import com.mojang.brigadier.builder.LiteralArgumentBuilder;
 import com.mojang.brigadier.builder.RequiredArgumentBuilder;
@@ -51,20 +33,23 @@
 import com.mojang.brigadier.suggestion.Suggestions;
 import com.mojang.brigadier.suggestion.SuggestionsBuilder;
 import com.mojang.brigadier.tree.LiteralCommandNode;
-
-import dev.jorel.commandapi.arguments.AbstractArgument;
-import dev.jorel.commandapi.arguments.ArgumentSuggestions;
-import dev.jorel.commandapi.arguments.CustomProvidedArgument;
-import dev.jorel.commandapi.arguments.Literal;
-import dev.jorel.commandapi.arguments.MultiLiteral;
-import dev.jorel.commandapi.arguments.PreviewInfo;
-import dev.jorel.commandapi.arguments.Previewable;
+import dev.jorel.commandapi.arguments.*;
 import dev.jorel.commandapi.commandsenders.AbstractCommandSender;
 import dev.jorel.commandapi.executors.CommandArguments;
 import dev.jorel.commandapi.executors.ExecutionInfo;
 import dev.jorel.commandapi.preprocessor.RequireField;
 import dev.jorel.commandapi.wrappers.PreviewableFunction;
 
+import java.io.File;
+import java.io.IOException;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.VarHandle;
+import java.lang.reflect.Field;
+import java.util.List;
+import java.util.*;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Predicate;
+
 /**
  * The "brains" behind the CommandAPI.
  * Handles command registration
@@ -151,14 +136,15 @@ public void onDisable() {
 		platform.onDisable();
 		CommandAPIHandler.resetInstance();
 	}
-	
+
 	private static void resetInstance() {
 		CommandAPIHandler.instance = null;
 	}
 
-	public static CommandAPIHandler<?, ?, ?> getInstance() {
-		if(CommandAPIHandler.instance != null) {
-			return CommandAPIHandler.instance;
+	public static <Argument extends AbstractArgument<?, ?, Argument, CommandSender>, CommandSender, Source>
+		CommandAPIHandler<Argument, CommandSender, Source> getInstance() {
+		if (CommandAPIHandler.instance != null) {
+			return (CommandAPIHandler<Argument, CommandSender, Source>) CommandAPIHandler.instance;
 		} else {
 			throw new IllegalStateException("Tried to access CommandAPIHandler instance, but it was null! Are you using CommandAPI features before calling CommandAPI#onLoad?");
 		}
@@ -293,7 +279,7 @@ CommandArguments argsToCommandArgs(CommandContext<Source> cmdCtx, Argument[] arg
 	 */
 	Object parseArgument(CommandContext<Source> cmdCtx, String key, Argument value, CommandArguments previousArgs) throws CommandSyntaxException {
 		if (value.isListed()) {
-			return value.parseArgument(cmdCtx, key, previousArgs);
+			return value.parseArgumentHandleError(cmdCtx, key, previousArgs);
 		} else {
 			return null;
 		}
@@ -657,11 +643,11 @@ void register(CommandMetaData<CommandSender> meta, final Argument[] args,
 
 		platform.postCommandRegistration(resultantNode, aliasNodes);
 	}
-	
+
 	/**
 	 * Checks for duplicate argument node names and logs them as errors in the
 	 * console
-	 * 
+	 *
 	 * @param args                          the list of arguments
 	 * @param humanReadableCommandArgSyntax the human readable command argument
 	 *                                      syntax
@@ -691,7 +677,7 @@ private boolean checkForDuplicateArgumentNodeNames(Argument[] args, String human
 		}
 		return true;
 	}
-	
+
 	private void writeDispatcherToFile() {
 		File file = CommandAPI.getConfiguration().getDispatcherFile();
 		if (file != null) {
@@ -785,12 +771,27 @@ LiteralArgumentBuilder<Source> getLiteralArgumentBuilderArgument(String commandN
 		}
 
 		RequiredArgumentBuilder<Source, ?> requiredArgumentBuilder = RequiredArgumentBuilder
-				.argument(argument.getNodeName(), argument.getRawType());
+				.argument(argument.getNodeName(), wrapArgumentType(argument, argument.getRawType()));
 
 		return requiredArgumentBuilder.requires(css -> permissionCheck(platform.getCommandSenderFromCommandSource(css),
 				argument.getArgumentPermission(), argument.getRequirements())).suggests(newSuggestionsProvider);
 	}
 
+	<T> ArgumentType<T> wrapArgumentType(Argument argument, ArgumentType<T> rawType) {
+		if (argument instanceof ICustomArgument) {
+			argument = ((ICustomArgument<Argument>) argument).getBaseArgument();
+			// CustomArgument should set its raw type to baseArgument's raw type, so that is already correct
+		}
+
+		if (!(argument instanceof InitialParseExceptionArgument)) return rawType;
+
+		InitialParseExceptionArgument<T, ?> iPEA = (InitialParseExceptionArgument<T, ?>) argument.instance();
+
+		Optional<InitialParseExceptionHandler<T>> handler = iPEA.getInitialParseExceptionHandler();
+		if (handler.isEmpty()) return rawType;
+		return new ExceptionHandlingArgumentType<>(rawType, handler.get());
+	}
+
 	CommandArguments generatePreviousArguments(CommandContext<Source> context, Argument[] args, String nodeName)
 			throws CommandSyntaxException {
 		// Populate Object[], which is our previously filled arguments
@@ -850,7 +851,7 @@ SuggestionProvider<Source> toSuggestions(Argument theArgument, Argument[] args,
 	 * @param path a list of Strings representing the path (names of command nodes)
 	 *             to (and including) the previewable argument
 	 * @return a function that takes in a {@link PreviewInfo} and returns a
-	 *         {@link Component}. If such a function is not available, this will
+	 *         Component representing the preview. If such a function is not available, this will
 	 *         return a function that always returns null.
 	 */
 	@SuppressWarnings("unchecked")

commandapi-core/src/main/java/dev/jorel/commandapi/SafeStaticOneParameterMethodHandle.java

@@ -0,0 +1,40 @@
+package dev.jorel.commandapi;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+
+public class SafeStaticOneParameterMethodHandle<ReturnType, ParameterType> {
+
+	private final MethodHandle handle;
+
+	private SafeStaticOneParameterMethodHandle(MethodHandle handle) {
+		this.handle = handle;
+	}
+
+	private static <ReturnType, ParameterType> SafeStaticOneParameterMethodHandle<ReturnType, ParameterType> of(Class<?> classType, String fieldName, String mojangMappedFieldName, Class<? super ReturnType> returnType, Class<? super ParameterType> parameterType) throws ReflectiveOperationException {
+		return new SafeStaticOneParameterMethodHandle<>(MethodHandles.privateLookupIn(classType, MethodHandles.lookup()).findStatic(classType, SafeVarHandle.USING_MOJANG_MAPPINGS ? mojangMappedFieldName : fieldName, MethodType.methodType(returnType, parameterType)));
+	}
+
+	public static <ReturnType, ParameterType> SafeStaticOneParameterMethodHandle<ReturnType, ParameterType> ofOrNull(Class<?> classType, String fieldName, String mojangMappedFieldName, Class<? super ReturnType> returnType, Class<? super ParameterType> parameterType) {
+		try {
+			return of(classType, fieldName, mojangMappedFieldName, returnType, parameterType);
+		} catch (ReflectiveOperationException e) {
+			e.printStackTrace();
+			return null;
+		}
+	}
+
+	public ReturnType invoke(ParameterType parameter) throws Throwable {
+		return (ReturnType) handle.invoke(parameter);
+	}
+
+	public ReturnType invokeOrNull(ParameterType parameter) {
+		try {
+			return invoke(parameter);
+		} catch (Throwable e) {
+			e.printStackTrace();
+			return null;
+		}
+	}
+}

commandapi-core/src/main/java/dev/jorel/commandapi/SafeVarHandle.java

@@ -40,6 +40,10 @@ public FieldType get(Type instance) {
 		return (FieldType) handle.get(instance);
 	}
 
+	public FieldType getUnknownInstanceType(Object instance) {
+		return (FieldType) handle.get(instance);
+	}
+
 	public FieldType getStatic() {
 		return (FieldType) handle.get(null);
 	}

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/AbstractArgument.java

@@ -24,7 +24,9 @@
 import com.mojang.brigadier.context.CommandContext;
 import com.mojang.brigadier.exceptions.CommandSyntaxException;
 import dev.jorel.commandapi.AbstractArgumentTree;
+import dev.jorel.commandapi.CommandAPIHandler;
 import dev.jorel.commandapi.CommandPermission;
+import dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException;
 import dev.jorel.commandapi.executors.CommandArguments;
 
 import java.util.ArrayList;
@@ -94,6 +96,41 @@ public final String getNodeName() {
 		return this.nodeName;
 	}
 
+	/**
+	 * Parses an argument using {@link Argument#parseArgument(CommandContext, String, CommandArguments)}.
+	 * If the parse fails and a {@link CommandSyntaxException} is thrown, the exception is passed to
+	 * the active {@link ArgumentParseExceptionHandler} for this argument, which can be defined by
+	 * developer using {@link Argument#withArgumentParseExceptionHandler(ArgumentParseExceptionHandler)}.
+	 * This is intended for use by the internals of the CommandAPI and isn't expected to be used outside
+	 * the CommandAPI
+	 *
+	 * @param <CommandSourceStack> the command source type
+	 * @param cmdCtx               the context which ran this command
+	 * @param key                  the name of the argument node
+	 * @param previousArgs         a {@link CommandArguments} object holding previous parsed arguments
+	 * @return the parsed object represented by this argument, or the object returned by
+	 * the active {@link ArgumentParseExceptionHandler} if parsing fails
+	 * @throws CommandSyntaxException if parsing fails and
+	 * the active {@link ArgumentParseExceptionHandler} throws an exception as well
+	 */
+	public final <CommandSourceStack> T parseArgumentHandleError(CommandContext<CommandSourceStack> cmdCtx, String key, CommandArguments previousArgs) throws CommandSyntaxException {
+		try {
+			return parseArgument(cmdCtx, key, previousArgs);
+		} catch (CommandSyntaxException original) {
+			try {
+				return exceptionHandler.handleException(new ArgumentParseExceptionContext<>(
+					new WrapperCommandSyntaxException(original),
+					CommandAPIHandler.<Argument, CommandSender, CommandSourceStack>getInstance().getPlatform()
+						.getCommandSenderFromCommandSource(cmdCtx.getSource()).getSource(),
+					cmdCtx.getArgument(key, Object.class),
+					previousArgs
+				));
+			} catch (WrapperCommandSyntaxException newException) {
+				throw newException.getException();
+			}
+		}
+	}
+
 	/**
 	 * Parses an argument, returning the specific Bukkit object that the argument
 	 * represents. This is intended for use by the internals of the CommandAPI and
@@ -323,6 +360,31 @@ public final Impl combineWith(Argument... combinedArguments) {
 		return instance();
 	}
 
+	////////////////////////
+	// Exception Handling //
+	///////////////////////
+
+	private ArgumentParseExceptionHandler<T, CommandSender> exceptionHandler = context -> { throw context.exception(); };
+
+	/**
+	 * Sets the {@link ArgumentParseExceptionHandler} this Argument should use when it fails to parse its input.
+	 *
+	 * @param exceptionHandler The new {@link ArgumentParseExceptionHandler} this argument should use
+	 * @return this current argument
+	 */
+	public final Impl withArgumentParseExceptionHandler(ArgumentParseExceptionHandler<T, CommandSender> exceptionHandler) {
+		this.exceptionHandler = exceptionHandler;
+		return instance();
+	}
+
+	/**
+	 * Returns the {@link ArgumentParseExceptionHandler} this argument is using
+	 * @return The {@link ArgumentParseExceptionHandler} this argument is using
+	 */
+	public final ArgumentParseExceptionHandler<T, CommandSender> getArgumentParseExceptionHandler() {
+		return this.exceptionHandler;
+	}
+
 	///////////
 	// Other //
 	///////////
@@ -357,4 +419,4 @@ public void copyPermissionsAndRequirements(Argument argument) {
 	public String toString() {
 		return this.getNodeName() + "<" + this.getClass().getSimpleName() + ">";
 	}
-}
+}

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/ArgumentParseExceptionContext.java

@@ -0,0 +1,33 @@
+package dev.jorel.commandapi.arguments;
+
+import dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException;
+import dev.jorel.commandapi.executors.CommandArguments;
+
+/**
+ * A record containing information on why an Argument failed to parse.
+ *
+ * @param exception The CommandSyntaxException that was thrown when the Argument failed to parse
+ * @param sender The CommandSender who sent the command that caused the exception
+ * @param input The raw object returned by the initial Brigadier parse for the Argument
+ * @param previousArguments - a {@link CommandArguments} object holding previously declared (and parsed) arguments. This can
+ * 		 be used as if it were arguments in a command executor method
+ */
+public record ArgumentParseExceptionContext<CommandSender>(
+	/**
+	 * @param exception The CommandSyntaxException that was thrown when the Argument failed to parse
+	 */
+	WrapperCommandSyntaxException exception,
+	/**
+	 * @param sender The CommandSender who sent the command that caused the exception
+	 */
+	CommandSender sender,
+	/**
+	 * @param input The raw object returned by the initial Brigadier parse for the Argument
+	 */
+	Object input,
+	/**
+	 * @param previousArguments - a {@link CommandArguments} object holding previously declared (and parsed) arguments.
+	 *                             This can be used as if it were arguments in a command executor method
+	 */
+	CommandArguments previousArguments) {
+}

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/ArgumentParseExceptionHandler.java

@@ -0,0 +1,24 @@
+package dev.jorel.commandapi.arguments;
+
+import dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException;
+
+/**
+ * A FunctionalInterface for defining custom behavior when an Argument fails to parse.
+ * See {@link ArgumentParseExceptionHandler#handleException(ArgumentParseExceptionContext)}
+ *
+ * @param <T> The class of the object returned by the Argument this object is handling
+ * @param <CommandSender> The CommandSender class being used
+ */
+@FunctionalInterface
+public interface ArgumentParseExceptionHandler<T, CommandSender> {
+	/**
+	 * A method that handles when an Argument fails to parse.
+	 * It can either return an object or throw a different exception.
+	 *
+	 * @param context a {@link ArgumentParseExceptionContext} record that holds information
+	 *                   about why and when the Argument failed to parse
+	 * @return A new object in place of the failed parse
+	 * @throws WrapperCommandSyntaxException A new exception to pass on
+	 */
+	T handleException(ArgumentParseExceptionContext<CommandSender> context) throws WrapperCommandSyntaxException;
+}