From 114cbda3174e1c93d1658ccbdccb52a3d98983ee Mon Sep 17 00:00:00 2001 From: Daniel Naylor Date: Sun, 2 May 2021 18:26:40 +0100 Subject: [PATCH] Add CommandCompletion for command completion tooltips * Rename command methods that use the word "suggest" to "complete" --- .../spongepowered/api/command/Command.java | 7 +- .../api/command/CommandCompletion.java | 93 +++++++++++++++++++ .../api/command/manager/CommandManager.java | 15 +-- .../api/command/parameter/Parameter.java | 3 +- .../parameter/managed/ValueCompleter.java | 3 +- .../parameter/managed/ValueParameter.java | 6 +- .../managed/ValueParameterModifier.java | 5 +- .../command/registrar/CommandRegistrar.java | 7 +- 8 files changed, 119 insertions(+), 20 deletions(-) create mode 100644 src/main/java/org/spongepowered/api/command/CommandCompletion.java diff --git a/src/main/java/org/spongepowered/api/command/Command.java b/src/main/java/org/spongepowered/api/command/Command.java index 985a124085f..512a169c070 100644 --- a/src/main/java/org/spongepowered/api/command/Command.java +++ b/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,9 +99,9 @@ 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. * - *

If a suggestion is chosen by the user, it will replace the last + *

If a completion is chosen by the user, it will replace the last * word.

* * @param cause The {@link CommandCause} of the command @@ -110,7 +109,7 @@ static Builder builder() { * @return A list of suggestions * @throws CommandException Thrown if there was a parsing error */ - List suggestions(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException; + List complete(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException; /** * Test whether this command can probably be executed given this diff --git a/src/main/java/org/spongepowered/api/command/CommandCompletion.java b/src/main/java/org/spongepowered/api/command/CommandCompletion.java new file mode 100644 index 00000000000..82af23f4261 --- /dev/null +++ b/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 + * 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 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); + + } + +} diff --git a/src/main/java/org/spongepowered/api/command/manager/CommandManager.java b/src/main/java/org/spongepowered/api/command/manager/CommandManager.java index 7e92fae3f9f..a9b70bd5cb2 100644 --- a/src/main/java/org/spongepowered/api/command/manager/CommandManager.java +++ b/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 suggest(String arguments); + List 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 The type of receiver * @param subjectReceiver The {@link Subject} & {@link Audience} * @param arguments The arguments - * @param The type of receiver * @return The completions */ - List suggest(T subjectReceiver, String arguments); + List 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 suggest(Subject subject, Audience receiver, String arguments); + List complete(Subject subject, Audience receiver, String arguments); /** * Gets all the command aliases known to this command manager. diff --git a/src/main/java/org/spongepowered/api/command/parameter/Parameter.java b/src/main/java/org/spongepowered/api/command/parameter/Parameter.java index 735848c9770..57e27c027f3 100644 --- a/src/main/java/org/spongepowered/api/command/parameter/Parameter.java +++ b/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 extends Parameter { * @throws ArgumentParseException thrown if the parameter could not be * parsed */ - List complete(ArgumentReader.@NonNull Immutable reader, @NonNull CommandContext context) throws ArgumentParseException; + List complete(ArgumentReader.@NonNull Immutable reader, @NonNull CommandContext context) throws ArgumentParseException; /** * Gets the usage of this parameter. diff --git a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueCompleter.java b/src/main/java/org/spongepowered/api/command/parameter/managed/ValueCompleter.java index 9b280ee32c4..e146229eb00 100644 --- a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueCompleter.java +++ b/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 complete(CommandContext context, String currentInput); + List complete(CommandContext context, String currentInput); } diff --git a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameter.java b/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameter.java index 563c681b778..f9da53e978f 100644 --- a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameter.java +++ b/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 parseValue( * @param currentInput The current input for this argument * @return The list of values */ - List complete(CommandCause context, String currentInput); + List 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 complete(final CommandContext context, final String currentInput) { + default List complete(final CommandContext context, final String currentInput) { return this.complete(context.cause(), currentInput); } diff --git a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameterModifier.java b/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameterModifier.java index e2036e0b7d4..e236fba6d2e 100644 --- a/src/main/java/org/spongepowered/api/command/parameter/managed/ValueParameterModifier.java +++ b/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 modifyResult( * @param completions The completions suggested by the chained parameter * @return The modified completions */ - default List modifyCompletion( - final CommandContext context, final String currentInput, final List completions) { + default List modifyCompletion( + final CommandContext context, final String currentInput, final List completions) { return completions; } diff --git a/src/main/java/org/spongepowered/api/command/registrar/CommandRegistrar.java b/src/main/java/org/spongepowered/api/command/registrar/CommandRegistrar.java index 869a4428f55..6569bf8ff85 100644 --- a/src/main/java/org/spongepowered/api/command/registrar/CommandRegistrar.java +++ b/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. * *

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 suggestions(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException; + List complete(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException; /** * Returns help text for the invoked command.