Package org.spongepowered.api.command.registrar

Interface CommandRegistrar<T>

Type Parameters:

T - The type of command interface this handles.

@DoNotStore
public interface CommandRegistrar<T>

CommandRegistrars are the entry point for plugins wishing to provide their own command framework. The CommandManager will proxy calls to the correct registrar and will handle the final CommandResult.

This interface defines a way to register commands. This registration method must call CommandManager.Mutable.registerAlias(CommandRegistrar, PluginContainer, CommandTreeNode.Root, String, String...) to indicate that they wish to take control of certain aliases. Beyond this call, the CommandRegistrar will only need to retain the link between the CommandMapping and its command (of type) T to execute, as the CommandManager will always supply the mapping of the command being invoked at runtime. The alias that was matched will also be supplied.

For a command that wishes to investigate the command string that was executed, they may investigate the context in CommandCause.cause(), looking for the EventContextKeys.COMMAND context key.

Command frameworks are free to choose how they parse commands. However, a framework's CommandRegistrar must do the following in order to be successfully registered and receive their commands:

• The registrar must have its type registered during the RegisterRegistryValueEvent for CommandRegistrarTypes; and
• Commands registered through the registrar must be synced back to the CommandManager, otherwise such commands will not be passed back to this registrar.

Method Summary

Modifier and Type	Method	Description
boolean	canExecute(CommandCause cause, CommandMapping mapping)	Gets whether the given CommandCause can execute the command associated with the given CommandMapping.
List<CommandCompletion>	complete(CommandCause cause, CommandMapping mapping, String command, String arguments)	Provides a list of completions associated with the provided argument string.
Optional<Component>	help(CommandCause cause, CommandMapping mapping)	Returns help text for the invoked command, if one is available.
CommandResult	process(CommandCause cause, CommandMapping mapping, String command, String arguments)	Process the provided command.
CommandMapping	register(org.spongepowered.plugin.PluginContainer container, T command, String primaryAlias, String... secondaryAliases)	Registers a command.
default Optional<Component>	shortDescription(CommandCause cause, CommandMapping mapping)	Returns a short description for the invoked command, if one is available.
CommandRegistrarType<T>	type()	Get the type defining this command registrar.

Method Detail

type

CommandRegistrarType<T> type()

Get the type defining this command registrar.

Returns:

the type

register

CommandMapping register(org.spongepowered.plugin.PluginContainer container,
                        T command,
                        String primaryAlias,
                        String... secondaryAliases)
                 throws CommandFailedRegistrationException

Registers a command.

Parameters:

container - The PluginContainer performing the registration

command - The command to register

primaryAlias - The primary alias

secondaryAliases - Any secondary aliases. May be empty.

Returns:

The CommandMapping

Throws:

CommandFailedRegistrationException - if the registration failed

process

CommandResult process(CommandCause cause,
                      CommandMapping mapping,
                      String command,
                      String arguments)
               throws CommandException

Process the provided command.

Note for implementors: the provided command will be the one registered as the primary alias when registering with the CommandManager.

Parameters:

cause - The CommandCause that caused the command to be executed

mapping - The CommandMapping for the command being invoked

command - The alias that was used to invoke the command

arguments - The arguments of the command (that is, the raw string with the command alias removed, so if /sponge test test2 is invoked, arguments will contain test test2.)

Returns:

The CommandResult

Throws:

CommandException - if there is an error executing the command

complete

List<CommandCompletion> complete(CommandCause cause,
                                 CommandMapping mapping,
                                 String command,
                                 String arguments)
                          throws CommandException

Provides a list of completions associated with the provided argument string.

See process(CommandCause, CommandMapping, String, String) for any implementation notes.

Parameters:

cause - The CommandCause that caused the command to be executed

mapping - The CommandMapping for the command being invoked

command - The alias that was used to invoke the command

arguments - The arguments of the command (that is, the raw string with the command alias removed, so if /sponge test test2 is invoked, arguments will contain test test2.)

Returns:

The completions

Throws:

CommandException - if there is an error providing the suggestions

shortDescription

default Optional<Component> shortDescription(CommandCause cause,
                                             CommandMapping mapping)

Returns a short description for the invoked command, if one is available.

A good short description is not necessarily help, rather, it should be a short description of the command's function. This short description may also be part of the standard help for the function.

It is recommended that any description here is kept very short as such a description may be used in a command listing.

Parameters:

cause - The CommandCause that caused the command to be executed

mapping - The CommandMapping that is associated with the command

Returns:

The help, if any

help

Optional<Component> help(CommandCause cause,
                         CommandMapping mapping)

Returns help text for the invoked command, if one is available.

Parameters:

cause - The CommandCause that caused the command to be executed

mapping - The CommandMapping that is associated with the command

Returns:

The help, if any

canExecute

boolean canExecute(CommandCause cause,
                   CommandMapping mapping)

Gets whether the given CommandCause can execute the command associated with the given CommandMapping.

Parameters:

cause - The CommandCause

mapping - The CommandMapping

Returns:

true of the command can execute the command