Add CommandCompletion and associated builder

src/main/java/org/spongepowered/api/command/Command.java

@@ -44,7 +44,6 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -100,17 +99,17 @@ static Builder builder() {
     CommandResult process(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException;
 
     /**
-     * Gets a list of suggestions based on input.
+     * Gets a list of completions based on input.
      *
-     * <p>If a suggestion is chosen by the user, it will replace the last
+     * <p>If a completion is chosen by the user, it will replace the last
      * word.</p>
      *
      * @param cause The {@link CommandCause} of the command
      * @param arguments The arguments entered up to this point
      * @return A list of suggestions
      * @throws CommandException Thrown if there was a parsing error
      */
-    List<String> suggestions(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException;
+    List<CommandCompletion> complete(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException;
 
     /**
      * Test whether this command can probably be executed given this

src/main/java/org/spongepowered/api/command/CommandCompletion.java

@@ -0,0 +1,93 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.command;
+
+import net.kyori.adventure.text.Component;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.spongepowered.api.Sponge;
+
+import java.util.Optional;
+
+/**
+ * A potential completion of a command argument.
+ */
+public interface CommandCompletion {
+
+    /**
+     * Creates a basic completion that only contains {@link String} that a given
+     * input may be completed to.
+     *
+     * @param completion The potential completion
+     * @return The {@link CommandCompletion} object
+     */
+    static CommandCompletion of(final @NonNull String completion) {
+        return CommandCompletion.of(completion, null);
+    }
+
+    /**
+     * Creates a completion that contains {@link String} that a given
+     * input may be completed to, and an associated tooltip.
+     *
+     * @param completion The potential completion
+     * @param tooltip The tooltip
+     * @return The {@link CommandCompletion} object
+     */
+    static CommandCompletion of(final @NonNull String completion, final @Nullable Component tooltip) {
+        return Sponge.game().factoryProvider().provide(Factory.class).completion(completion, tooltip);
+    }
+
+    /**
+     * The potential completion that this object represents.
+     *
+     * @return The completion
+     */
+    String completion();
+
+    /**
+     * The tooltip that may be displayed by the client when hovering over this
+     * completion.
+     *
+     * @return The tooltip, if any
+     */
+    Optional<Component> tooltip();
+
+    /**
+     * A factory for constructing {@link CommandCompletion}s
+     */
+    interface Factory {
+
+        /**
+         * Creates a {@link CommandCompletion}
+         *
+         * @param completion The completion
+         * @param tooltip The {@link Component} to display, if any
+         * @return A {@link CommandCompletion}
+         */
+        CommandCompletion completion(String completion, @Nullable Component tooltip);
+
+    }
+
+}

src/main/java/org/spongepowered/api/command/manager/CommandManager.java

@@ -26,6 +26,7 @@
 
 import io.leangen.geantyref.TypeToken;
 import net.kyori.adventure.audience.Audience;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.CommandResult;
 import org.spongepowered.api.command.exception.CommandException;
 import org.spongepowered.api.command.registrar.CommandRegistrar;
@@ -125,27 +126,27 @@ public interface CommandManager {
     CommandResult process(Subject subject, Audience channel, String arguments) throws CommandException;
 
     /**
-     * Suggests possible completions based on the input argument string.
+     * Provides possible completions based on the input argument string.
      *
      * @param arguments The arguments
      * @return The completions
      */
-    List<String> suggest(String arguments);
+    List<CommandCompletion> complete(String arguments);
 
     /**
-     * Suggests possible completions based on the input argument string,
+     * Provides possible completions based on the input argument string,
      * with a provided object that is both a {@link Subject} for permission
      * checks and a {@link Audience} to return command messages to.
      *
+     * @param <T> The type of receiver
      * @param subjectReceiver The {@link Subject} &amp; {@link Audience}
      * @param arguments The arguments
-     * @param <T> The type of receiver
      * @return The completions
      */
-    <T extends Subject & Audience> List<String> suggest(T subjectReceiver, String arguments);
+    <T extends Subject & Audience> List<CommandCompletion> complete(T subjectReceiver, String arguments);
 
     /**
-     * Suggests possible completions based on the input argument string,
+     * Provides possible completions based on the input argument string,
      * with a provided a {@link Subject} for permission checks and a
      * {@link Audience} to return command messages to.
      *
@@ -154,7 +155,7 @@ public interface CommandManager {
      * @param arguments The arguments
      * @return The completions
      */
-    List<String> suggest(Subject subject, Audience receiver, String arguments);
+    List<CommandCompletion> complete(Subject subject, Audience receiver, String arguments);
 
     /**
      * Gets all the command aliases known to this command manager.

src/main/java/org/spongepowered/api/command/parameter/Parameter.java

@@ -35,6 +35,7 @@
 import org.spongepowered.api.block.BlockState;
 import org.spongepowered.api.command.Command;
 import org.spongepowered.api.command.CommandCause;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.CommandExecutor;
 import org.spongepowered.api.command.exception.ArgumentParseException;
 import org.spongepowered.api.command.parameter.managed.ValueCompleter;
@@ -1039,7 +1040,7 @@ interface Value<T> extends Parameter {
          * @throws ArgumentParseException thrown if the parameter could not be
          *      parsed
          */
-        List<String> complete(ArgumentReader.@NonNull Immutable reader, @NonNull CommandContext context) throws ArgumentParseException;
+        List<CommandCompletion> complete(ArgumentReader.@NonNull Immutable reader, @NonNull CommandContext context) throws ArgumentParseException;
 
         /**
          * Gets the usage of this parameter.

src/main/java/org/spongepowered/api/command/parameter/managed/ValueCompleter.java

@@ -25,6 +25,7 @@
 package org.spongepowered.api.command.parameter.managed;
 
 import org.spongepowered.api.command.CommandCause;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.parameter.CommandContext;
 
 import java.util.List;
@@ -45,6 +46,6 @@ public interface ValueCompleter {
      * @param currentInput The current input for this argument
      * @return The list of values
      */
-    List<String> complete(CommandContext context, String currentInput);
+    List<CommandCompletion> complete(CommandContext context, String currentInput);
 
 }

src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameter.java

@@ -26,6 +26,7 @@
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.spongepowered.api.command.CommandCause;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.exception.ArgumentParseException;
 import org.spongepowered.api.command.parameter.ArgumentReader;
 import org.spongepowered.api.command.parameter.CommandContext;
@@ -103,16 +104,17 @@ default Optional<? extends T> parseValue(
          * @param currentInput The current input for this argument
          * @return The list of values
          */
-        List<String> complete(CommandCause context, String currentInput);
+        List<CommandCompletion> complete(CommandCause context, String currentInput);
 
         /**
          * This should not be overridden by implementations of this class. If
          * you wish to do so, implement {@link ValueParameter} instead.
          *
          * {@inheritDoc}
+         * @return
          */
         @Override
-        default List<String> complete(final CommandContext context, final String currentInput) {
+        default List<CommandCompletion> complete(final CommandContext context, final String currentInput) {
             return this.complete(context.cause(), currentInput);
         }
 

src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameterModifier.java

@@ -26,6 +26,7 @@
 
 import net.kyori.adventure.text.Component;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.CommandExecutor;
 import org.spongepowered.api.command.exception.ArgumentParseException;
 import org.spongepowered.api.command.parameter.ArgumentReader;
@@ -129,8 +130,8 @@ Optional<? extends T> modifyResult(
      * @param completions The completions suggested by the chained parameter
      * @return The modified completions
      */
-    default List<String> modifyCompletion(
-            final CommandContext context, final String currentInput, final  List<String> completions) {
+    default List<CommandCompletion> modifyCompletion(
+            final CommandContext context, final String currentInput, final  List<CommandCompletion> completions) {
         return completions;
     }
 

src/main/java/org/spongepowered/api/command/registrar/CommandRegistrar.java

@@ -26,6 +26,7 @@
 
 import net.kyori.adventure.text.Component;
 import org.spongepowered.api.command.CommandCause;
+import org.spongepowered.api.command.CommandCompletion;
 import org.spongepowered.api.command.CommandResult;
 import org.spongepowered.api.command.exception.CommandException;
 import org.spongepowered.api.command.manager.CommandFailedRegistrationException;
@@ -121,7 +122,7 @@ CommandMapping register(
     CommandResult process(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException;
 
     /**
-     * Provides a list of suggestions associated with the provided argument
+     * Provides a list of completions associated with the provided argument
      * string.
      *
      * <p>See {@link #process(CommandCause, CommandMapping, String, String)} for any
@@ -135,10 +136,10 @@ CommandMapping register(
      *                  with the command alias removed, so if
      *                  {@code /sponge test test2} is invoked, arguments will
      *                  contain {@code test test2}.)
-     * @return The suggestions
+     * @return The completions
      * @throws CommandException if there is an error providing the suggestions
      */
-    List<String> suggestions(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException;
+    List<CommandCompletion> complete(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException;
 
     /**
      * Returns help text for the invoked command.