✨ Add named suggestion providers

This allows for pre-registration of command suggestion providers, that can then be used in annotated command methods.

cloud-annotations/src/main/java/cloud/commandframework/annotations/AnnotationParser.java

@@ -52,7 +52,9 @@ import java.util.Arrays;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Queue;
 import java.util.function.BiFunction;
 import java.util.function.Function;
@@ -300,7 +302,7 @@ public final class AnnotationParser<C> {
         final TypeToken<?> token = TypeToken.get(parameter.getParameterizedType());
         final ParserParameters parameters = this.manager.getParserRegistry()
                 .parseAnnotations(token, annotations);
-
+        /* Create the argument parser */
         final ArgumentParser<C, ?> parser;
         if (argumentPair.getArgument().parserName().isEmpty()) {
             parser = this.manager.getParserRegistry()
@@ -323,17 +325,19 @@ public final class AnnotationParser<C> {
                                     token.toString()
                             )));
         }
-
+        /* Check whether or not the corresponding method parameter actually exists */
         if (syntaxFragment == null || syntaxFragment.getArgumentMode() == ArgumentMode.LITERAL) {
             throw new IllegalArgumentException(String.format(
                     "Invalid command argument '%s' in method '%s': "
                             + "Missing syntax mapping", argumentPair.getArgument().value(), method.getName()));
         }
         final Argument argument = argumentPair.getArgument();
+        /* Create the argument builder */
         @SuppressWarnings("ALL") final CommandArgument.Builder argumentBuilder = CommandArgument.ofType(
                 parameter.getType(),
                 argument.value()
         );
+        /* Set the argument requirement status */
         if (syntaxFragment.getArgumentMode() == ArgumentMode.OPTIONAL) {
             if (argument.defaultValue().isEmpty()) {
                 argumentBuilder.asOptional();
@@ -343,9 +347,21 @@ public final class AnnotationParser<C> {
         } else {
             argumentBuilder.asRequired();
         }
-
+        /* Check whether or not a suggestion provider should be set */
+        if (!argument.suggestions().isEmpty()) {
+            final String suggestionProviderName = argument.suggestions();
+            final Optional<BiFunction<CommandContext<C>, String, List<String>>> suggestionsFunction =
+                    this.manager.getParserRegistry().getSuggestionProvider(suggestionProviderName);
+            argumentBuilder.withSuggestionsProvider(
+                    suggestionsFunction.orElseThrow(() ->
+                    new IllegalArgumentException(String.format(
+                            "There is no suggestion provider with name '%s'. Did you forget to register it?",
+                            suggestionProviderName
+                    )))
+            );
+        }
+        /* Build the argument */
         final CommandArgument<C, ?> builtArgument = argumentBuilder.manager(this.manager).withParser(parser).build();
-
         /* Add preprocessors */
         for (final Annotation annotation : annotations) {
             @SuppressWarnings("ALL") final Function preprocessorMapper =
@@ -357,7 +373,7 @@ public final class AnnotationParser<C> {
                 builtArgument.addPreprocessor(preprocessor);
             }
         }
-
+        /* Yay, we're done */
         return builtArgument;
     }
 

cloud-annotations/src/main/java/cloud/commandframework/annotations/Argument.java

@@ -27,6 +27,7 @@ import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.function.BiFunction;
 
 /**
  * Annotation used to indicate that a method parameter is a command argument
@@ -49,6 +50,22 @@ public @interface Argument {
      */
     String parserName() default "";
 
+    /**
+     * Name of the suggestions provider to use. If the string is left empty, the default
+     * provider for the argument parser will be used. Otherwise,
+     * the {@link cloud.commandframework.arguments.parser.ParserRegistry} instance in the
+     * {@link cloud.commandframework.CommandManager} will be queried for a matching suggestion provider.
+     * <p>
+     * For this to work, the suggestion needs to be registered in the parser registry. To do this, use
+     * {@link cloud.commandframework.arguments.parser.ParserRegistry#registerSuggestionProvider(String, BiFunction)}.
+     * The registry instance can be retrieved using {@link cloud.commandframework.CommandManager#getParserRegistry()}.
+     *
+     * @return The name of the suggestion provider, or {@code ""} if the default suggestion provider for the argument parser
+     *         should be used instead
+     * @since 1.1.0
+     */
+    String suggestions() default "";
+
     /**
      * Get the default value
      *

cloud-annotations/src/test/java/cloud/commandframework/annotations/AnnotationParserTest.java

@@ -32,12 +32,16 @@ import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.List;
 import java.util.concurrent.CompletionException;
 
 class AnnotationParserTest {
 
+    private static final List<String> NAMED_SUGGESTIONS = Arrays.asList("Dancing-Queen", "Gimme!-Gimme!-Gimme!", "Waterloo");
+
     private static CommandManager<TestCommandSender> manager;
     private static AnnotationParser<TestCommandSender> annotationParser;
 
@@ -47,6 +51,11 @@ class AnnotationParserTest {
         annotationParser = new AnnotationParser<>(manager, TestCommandSender.class, p -> SimpleCommandMeta.empty());
         manager.getParserRegistry().registerNamedParserSupplier("potato", p -> new StringArgument.StringParser<>(
                 StringArgument.StringMode.SINGLE, (c, s) -> Collections.singletonList("potato")));
+        /* Register a suggestion provider */
+        manager.getParserRegistry().registerSuggestionProvider(
+                "some-name",
+                (context, input) -> NAMED_SUGGESTIONS
+        );
     }
 
     @Test
@@ -62,6 +71,11 @@ class AnnotationParserTest {
         manager.executeCommand(new TestCommandSender(), "flagcommand --print --word peanut").join();
     }
 
+    @Test
+    void testNamedSuggestionProvider() {
+        Assertions.assertEquals(NAMED_SUGGESTIONS, manager.suggest(new TestCommandSender(), "namedsuggestions "));
+    }
+
     @ProxiedBy("proxycommand")
     @CommandMethod("test|t literal <int> [string]")
     public void testCommand(
@@ -75,12 +89,18 @@ class AnnotationParserTest {
     @CommandMethod("flagcommand")
     public void testFlags(
             final TestCommandSender sender,
-            @Flag(value = "print", aliases = "p") boolean print,
-            @Flag(value = "word", aliases = "w") String word
+            @Flag(value = "print", aliases = "p") final boolean print,
+            @Flag(value = "word", aliases = "w") final String word
     ) {
         if (print) {
             System.out.println(word);
         }
     }
 
+    @CommandMethod("namedsuggestions <input>")
+    public void testNamedSuggestionProviders(
+            @Argument(value = "input", suggestions = "some-name") final String argument
+    ) {
+    }
+
 }