Package org.spongepowered.api.command

Interface Command

All Known Subinterfaces:

Command.Parameterized, Command.Raw

public interface Command

The Command interface is the low-level interface that all commands in the Sponge ecosystem inherit.

Most plugins are highly recommended (but not obligated) to use builder() to create commands. The Command.Builder allows plugins to take advantage of a higher level of abstraction, such as argument parsers and simple child command handling, removing the need for boilerplate code. Such Command.Parameterized commands should register themselves during the RegisterCommandEvent<Command.Parameterized> event.

Plugins that do not want to use the Command.Builder or any third-party command system should implement the Command.Raw sub-interface instead. Such Command.Raw commands should register themselves during the RegisterCommandEvent<Command.Raw> event.

Plugins must not implement the Command.Parameterized sub-interface themselves.

Upon execution, commands are provided with a CommandCause, providing the Cause and EventContext that invoked the command. See the CommandCause documentation for more information of the structure of this cause.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Command.Builder	A high level Command.Builder for creating a Command.Parameterized.
static interface	Command.Parameterized	A Command that has distinct steps for parsing arguments and executing a command based on those arguments.
static interface	Command.Raw	A raw command that also contains a CommandTreeNode to provide hints to the client for command completion.

Method Summary

Modifier and Type	Method	Description
static Command.Builder	builder()	Gets a builder for building a Command.
boolean	canExecute(CommandCause cause)	Test whether this command can probably be executed given this Cause.
java.util.List<CommandCompletion>	complete(CommandCause cause, ArgumentReader.Mutable arguments)	Gets a list of completions based on input.
java.util.Optional<Component>	extendedDescription(CommandCause cause)	Gets a longer formatted help message about this command.
default java.util.Optional<Component>	help(@NonNull CommandCause cause)	Gets a longer formatted help message about this command.
CommandResult	process(CommandCause cause, ArgumentReader.Mutable arguments)	Execute the command based on input arguments.
java.util.Optional<Component>	shortDescription(CommandCause cause)	Gets a short one-line description of this command.
Component	usage(CommandCause cause)	Gets the usage string of this command.

Method Detail

builder

static Command.Builder builder()

Gets a builder for building a Command.

Returns:

The Command.Builder

process

CommandResult process(CommandCause cause,
                      ArgumentReader.Mutable arguments)
               throws CommandException

Execute the command based on input arguments.

The implementing class must perform the necessary permission checks.

Parameters:

cause - The CommandCause of the invocation of command

arguments - The raw arguments for this command

Returns:

The result of a command being processed

Throws:

CommandException - Thrown on a command error

complete

java.util.List<CommandCompletion> complete(CommandCause cause,
                                           ArgumentReader.Mutable arguments)
                                    throws CommandException

Gets a list of completions based on input.

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

Parameters:

cause - The CommandCause of the command

arguments - The arguments entered up to this point

Returns:

A list of suggestions

Throws:

CommandException - Thrown if there was a parsing error

canExecute

boolean canExecute(CommandCause cause)

Test whether this command can probably be executed given this Cause.

If implementations are unsure if the command can be executed by the source, true should be returned. Return values of this method may be used to determine whether this command is listed in command listings.

Parameters:

cause - The Cause to check

Returns:

Whether this command will execute

shortDescription

java.util.Optional<Component> shortDescription(CommandCause cause)

Gets a short one-line description of this command.

The help system may display the description in the command list, or in any other function that displays a command list. It is therefore recommended that any description here is kept very short.

Parameters:

cause - The CommandCause of the help request

Returns:

A description

See Also:

CommandRegistrar.shortDescription(CommandCause, CommandMapping)

extendedDescription

java.util.Optional<Component> extendedDescription(CommandCause cause)

Gets a longer formatted help message about this command.

The help system may display this description when displaying details about this specific command. It should not contain the description provided by shortDescription(CommandCause).

Parameters:

cause - The Cause of the help request

Returns:

A description

help

default java.util.Optional<Component> help(@NonNull CommandCause cause)

Gets a longer formatted help message about this command. This will typically comprise of shortDescription(CommandCause) and extendedDescription(CommandCause) together.

The help system may display this message when a source requests detailed information about a command.

Parameters:

cause - The Cause of the help request

Returns:

A help text

See Also:

CommandRegistrar.help(CommandCause, CommandMapping)

usage

Component usage(CommandCause cause)

Gets the usage string of this command.

A usage string may look like [<world>] <var1> <var2>.

The string must not contain the command alias.

Parameters:

cause - The Cause of the help request

Returns:

A usage string