org.spongepowered.api.command.dispatcher

Class SimpleDispatcher

java.lang.Object

org.spongepowered.api.command.dispatcher.SimpleDispatcher

All Implemented Interfaces:

CommandCallable, Dispatcher

public final class SimpleDispatcher
extends Object
implements Dispatcher

A simple implementation of a Dispatcher.

Field Summary

Fields

Modifier and Type	Field and Description
static Disambiguator	FIRST_DISAMBIGUATOR This is a disambiguator function that returns the first matching command.

Constructor Summary

Constructors

Constructor and Description
SimpleDispatcher() Creates a basic new dispatcher.
SimpleDispatcher(Disambiguator disambiguatorFunc) Creates a new dispatcher with a specific disambiguator.

Method Summary

Modifier and Type	Method and Description
boolean	containsAlias(String alias) Returns whether the dispatcher contains a registered command for the given alias.
boolean	containsMapping(CommandMapping mapping) Returns whether the dispatcher contains the given mapping.
Optional<CommandMapping>	get(String alias) Gets the CommandMapping associated with an alias.
Optional<CommandMapping>	get(String alias, CommandSource source) Gets the CommandMapping associated with an alias in the context of a given CommandSource.
Set<String>	getAliases() Gets a list of all the command aliases, which includes the primary alias.
Multimap<String,CommandMapping>	getAll() Gets all commands currently registered with this dispatcher.
Set<CommandMapping>	getAll(String alias) Gets all the CommandMappings associated with an alias.
Set<CommandMapping>	getCommands() Gets a list of commands.
Optional<Text>	getHelp(CommandSource source) Gets a longer formatted help message about this command.
Set<String>	getPrimaryAliases() Gets a list of primary aliases.
Optional<Text>	getShortDescription(CommandSource source) Gets a short one-line description of this command.
List<String>	getSuggestions(CommandSource src, String arguments, Location<World> targetPosition) Gets a list of suggestions based on input.
Text	getUsage(CommandSource source) Gets the usage string of this command.
CommandResult	process(CommandSource source, String commandLine) Execute the command based on input arguments.
Optional<CommandMapping>	register(CommandCallable callable, List<String> aliases) Register a given command using the given list of aliases.
Optional<CommandMapping>	register(CommandCallable callable, List<String> aliases, Function<List<String>,List<String>> callback) Register a given command using a given list of aliases.
Optional<CommandMapping>	register(CommandCallable callable, String... alias) Register a given command using the given list of aliases.
Collection<CommandMapping>	remove(String alias) Remove a mapping identified by the given alias.
boolean	removeAll(Collection<?> aliases) Remove all mappings identified by the given aliases.
Optional<CommandMapping>	removeMapping(CommandMapping mapping) Remove a command identified by the given mapping.
boolean	removeMappings(Collection<?> mappings) Remove all mappings contained with the given collection.
int	size() Gets the number of registered aliases.
boolean	testPermission(CommandSource source) Test whether this command can probably be executed by the given source.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FIRST_DISAMBIGUATOR

public static final Disambiguator FIRST_DISAMBIGUATOR

This is a disambiguator function that returns the first matching command.

Constructor Detail

SimpleDispatcher

public SimpleDispatcher()

Creates a basic new dispatcher.

SimpleDispatcher

public SimpleDispatcher(Disambiguator disambiguatorFunc)

Creates a new dispatcher with a specific disambiguator.

Parameters:

disambiguatorFunc - Function that returns the preferred command if multiple exist for a given alias

Method Detail

register

public Optional<CommandMapping> register(CommandCallable callable,
                                         String... alias)

Register a given command using the given list of aliases.

If there is a conflict with one of the aliases (i.e. that alias is already assigned to another command), then the alias will be skipped. It is possible for there to be no alias to be available out of the provided list of aliases, which would mean that the command would not be assigned to any aliases.

The first non-conflicted alias becomes the "primary alias."

Parameters:

callable - The command

alias - An array of aliases

Returns:

The registered command mapping, unless no aliases could be registered

register

public Optional<CommandMapping> register(CommandCallable callable,
                                         List<String> aliases)

Register a given command using the given list of aliases.

If there is a conflict with one of the aliases (i.e. that alias is already assigned to another command), then the alias will be skipped. It is possible for there to be no alias to be available out of the provided list of aliases, which would mean that the command would not be assigned to any aliases.

The first non-conflicted alias becomes the "primary alias."

Parameters:

callable - The command

aliases - A list of aliases

Returns:

The registered command mapping, unless no aliases could be registered

register

public Optional<CommandMapping> register(CommandCallable callable,
                                         List<String> aliases,
                                         Function<List<String>,List<String>> callback)

Register a given command using a given list of aliases.

The provided callback function will be called with a list of aliases that are not taken (from the list of aliases that were requested) and it should return a list of aliases to actually register. Aliases may be removed, and if no aliases remain, then the command will not be registered. It may be possible that no aliases are available, and thus the callback would receive an empty list. New aliases should not be added to the list in the callback as this may cause IllegalArgumentException to be thrown.

The first non-conflicted alias becomes the "primary alias."

Parameters:

callable - The command

aliases - A list of aliases

callback - The callback

Returns:

The registered command mapping, unless no aliases could be registered

remove

public Collection<CommandMapping> remove(String alias)

Remove a mapping identified by the given alias.

Parameters:

alias - The alias

Returns:

The previous mapping associated with the alias, if one was found

removeAll

public boolean removeAll(Collection<?> aliases)

Remove all mappings identified by the given aliases.

Parameters:

aliases - A collection of aliases

Returns:

Whether any were found

removeMapping

public Optional<CommandMapping> removeMapping(CommandMapping mapping)

Remove a command identified by the given mapping.

Parameters:

mapping - The mapping

Returns:

The previous mapping associated with the alias, if one was found

removeMappings

public boolean removeMappings(Collection<?> mappings)

Remove all mappings contained with the given collection.

Parameters:

mappings - The collection

Returns:

Whether the at least one command was removed

getCommands

public Set<CommandMapping> getCommands()

Description copied from interface: Dispatcher

Gets a list of commands. Each command, regardless of how many aliases it may have, will only appear once in the returned set.

The returned collection cannot be modified.

Specified by:

getCommands in interface Dispatcher

Returns:

A list of registrations

getPrimaryAliases

public Set<String> getPrimaryAliases()

Description copied from interface: Dispatcher

Gets a list of primary aliases.

The returned collection cannot be modified.

Specified by:

getPrimaryAliases in interface Dispatcher

Returns:

A list of aliases

getAliases

public Set<String> getAliases()

Description copied from interface: Dispatcher

Gets a list of all the command aliases, which includes the primary alias.

A command may have more than one alias assigned to it. The returned collection cannot be modified.

Specified by:

getAliases in interface Dispatcher

Returns:

A list of aliases

get

public Optional<CommandMapping> get(String alias)

Description copied from interface: Dispatcher

Gets the CommandMapping associated with an alias. Returns null if no command is named by the given alias.

Specified by:

get in interface Dispatcher

Parameters:

alias - The alias

Returns:

The command mapping, if available

get

public Optional<CommandMapping> get(String alias,
                                    @Nullable
                                    CommandSource source)

Description copied from interface: Dispatcher

Gets the CommandMapping associated with an alias in the context of a given CommandSource. Returns null if no command is named by the given alias.

Specified by:

get in interface Dispatcher

Parameters:

alias - The alias to look up

source - The source this alias is being looked up for

Returns:

The command mapping, if available

containsAlias

public boolean containsAlias(String alias)

Description copied from interface: Dispatcher

Returns whether the dispatcher contains a registered command for the given alias.

Specified by:

containsAlias in interface Dispatcher

Parameters:

alias - The alias

Returns:

True if a registered command exists

containsMapping

public boolean containsMapping(CommandMapping mapping)

Description copied from interface: Dispatcher

Returns whether the dispatcher contains the given mapping.

Specified by:

containsMapping in interface Dispatcher

Parameters:

mapping - The mapping

Returns:

True if a mapping exists

process

public CommandResult process(CommandSource source,
                             String commandLine)
                      throws CommandException

Description copied from interface: CommandCallable

Execute the command based on input arguments.

The implementing class must perform the necessary permission checks.

Specified by:

process in interface CommandCallable

Parameters:

source - The caller of the command

commandLine - The raw arguments for this command

Returns:

The result of a command being processed

Throws:

CommandException - Thrown on a command error

getSuggestions

public List<String> getSuggestions(CommandSource src,
                                   String arguments,
                                   @Nullable
                                   Location<World> targetPosition)
                            throws CommandException

Description copied from interface: CommandCallable

Gets a list of suggestions based on input.

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

Specified by:

getSuggestions in interface CommandCallable

Parameters:

src - The command source

arguments - The arguments entered up to this point

targetPosition - The position the source is looking at when performing tab completion

Returns:

A list of suggestions

Throws:

CommandException - Thrown if there was a parsing error

testPermission

public boolean testPermission(CommandSource source)

Description copied from interface: CommandCallable

Test whether this command can probably be executed by the given source.

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.

Specified by:

testPermission in interface CommandCallable

Parameters:

source - The caller of the command

Returns:

Whether permission is (probably) granted

getShortDescription

public Optional<Text> getShortDescription(CommandSource source)

Description copied from interface: CommandCallable

Gets a short one-line description of this command.

The help system may display the description in the command list.

Specified by:

getShortDescription in interface CommandCallable

Parameters:

source - The source of the help request

Returns:

A description

getHelp

public Optional<Text> getHelp(CommandSource source)

Description copied from interface: CommandCallable

Gets a longer formatted help message about this command.

It is recommended to use the default text color and style. Sections with text actions (e.g. hyperlinks) should be underlined.

Multi-line messages can be created by separating the lines with \n.

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

Specified by:

getHelp in interface CommandCallable

Parameters:

source - The source of the help request

Returns:

A help text

size

public int size()

Gets the number of registered aliases.

Returns:

The number of aliases

getUsage

public Text getUsage(CommandSource source)

Description copied from interface: CommandCallable

Gets the usage string of this command.

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

The string must not contain the command alias.

Specified by:

getUsage in interface CommandCallable

Parameters:

source - The source of the help request

Returns:

A usage string

getAll

public Set<CommandMapping> getAll(String alias)

Description copied from interface: Dispatcher

Gets all the CommandMappings associated with an alias.

Specified by:

getAll in interface Dispatcher

Parameters:

alias - The alias

Returns:

The command mappings associated with the alias

getAll

public Multimap<String,CommandMapping> getAll()

Description copied from interface: Dispatcher

Gets all commands currently registered with this dispatcher. The returned value is immutable.

Specified by:

getAll in interface Dispatcher

Returns:

a multimap from alias to mapping of every registered command