Package org.spongepowered.api.command.parameter.managed

Interface ValueParameterModifier<T>

public interface ValueParameterModifier<T>

A value parameter modifier is an alternative to attempting to create an element that extends/wraps around a ValueParameter, particularly those that are provided by Sponge on behalf of Minecraft or other underlying implementation.

The primary intention of a modifier is to enable custom filtering logic on in-built parameters so that plugins can refine the user experience when using their commands while retaining most of the properties of the underlying parameter. In general, plugins should not use modifiers on their own value parameters or associated classes. Further, modifiers are not designed to perform any post-processing on any parsed elements, they should generally only be used to validate or filter results and completions - post-processing should be performed in the command's exectuor instead, as by this point you know that your command has been selected.

These modifier methods are provided the same information as the original parameter, along with the result of the original parameter - that is, these modifiers run after the associated parameter has run. The main takeaway here is that modifiers cannot add new entries to the parameter, only modify what they return and filter out entries that are not supported by your operation.

Modifiers are not designed to transform the returned type - this is to maintain the integrity of the key typing and to discourage additional logic in parameter parsing that should actually exist in the CommandExecutor of the command instead.

Users of modifiers should consider the following when modifying the result:

• Any supplied parameters may have been modified by the associated parameter that this is modifying, and are not snapshots from before.
• The ArgumentReader is immutable. This is to prevent accidental continued parsing. If you want to use a modifier to further parse the input string based on the result of chained parameter, create a custom ValueParameter that follows on from the node in question instead - the result of this parse will be available in the CommandContext.Builder in later nodes.
• Modifiers may choose to not return a value and instead add to the CommandContext.Builder directly. While this is permissible, do not be tempted to use modifiers as a way to perform logic this is not directly related to parsing a string to avoid unnecessary processing that may not be used if a later node fails to parse and this node's result is discarded.
• Modifiers cannot prevent the chained parameter from throwing an exception, in the case that they do so this modifier will not be called. Instead, add a second ValueParser to the parameter, and account for this in your modifier.
• The use of a modifier will require that any completion requests are sent to the server, regardless of whether completions are actually modified. If completions are not being modified, consider whether it would be better to process the parsed result in the body of your executor instead.

With all this in mind, modifiers should be used sparingly, preferring the use of other constructs when at all possible.

Method Summary

Modifier and Type	Method	Description
default List<CommandCompletion>	modifyCompletion(CommandContext context, String currentInput, List<CommandCompletion> completions)	Modifies the result of the chained parameter's completions.
default @Nullable Component	modifyExceptionMessage(@Nullable Component exceptionMessage)	Modifies the message provided in a ArgumentParseException if the modified ValueParser throws this exception.
Optional<? extends T>	modifyResult(Parameter.Key<? super T> parameterKey, ArgumentReader.Immutable reader, CommandContext.Builder context, @Nullable T value)	Modifies the result of the chained parameter's parse result.

Method Detail

modifyResult

Optional<? extends T> modifyResult(Parameter.Key<? super T> parameterKey,
                                   ArgumentReader.Immutable reader,
                                   CommandContext.Builder context,
                                   @Nullable T value)
                            throws ArgumentParseException

Modifies the result of the chained parameter's parse result.

Parameters:

parameterKey - The target Parameter.Key to fill in the context

reader - The ArgumentReader.Immutable that may have been advanced by the parser

context - The CommandContext.Builder that may have been modified by the parser

value - The value returned by the parser, if any

Returns:

The value to associate with the parameterKey

Throws:

ArgumentParseException - if the modifier wishes to halt processing of this element

modifyCompletion

default List<CommandCompletion> modifyCompletion(CommandContext context,
                                                 String currentInput,
                                                 List<CommandCompletion> completions)

Modifies the result of the chained parameter's completions.

Parameters:

context - The CommandContext

currentInput - The input that suggestions are built from

completions - The completions suggested by the chained parameter

Returns:

The modified completions

modifyExceptionMessage

default @Nullable Component modifyExceptionMessage(@Nullable Component exceptionMessage)

Modifies the message provided in a ArgumentParseException if the modified ValueParser throws this exception.

Parameters:

exceptionMessage - The message provided by the ValueParser

Returns:

The modified message, or the parameter if it is not to be modified.