com.mojang.brigadier

Class CommandDispatcher<S>

java.lang.Object

com.mojang.brigadier.CommandDispatcher<S>

Type Parameters:

S - a custom "source" type, such as a user or originator of a command

public class CommandDispatcher<S>
extends Object

The core command dispatcher, for registering, parsing, and executing commands.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ARGUMENT_SEPARATOR The string required to separate individual arguments in an input string
static char	ARGUMENT_SEPARATOR_CHAR The char required to separate individual arguments in an input string

Constructor Summary

Constructors

Constructor and Description
CommandDispatcher() Creates a new CommandDispatcher with an empty command tree.
CommandDispatcher(RootCommandNode<S> root) Create a new CommandDispatcher with the specified root node.

Method Summary

Modifier and Type	Method and Description
int	execute(ParseResults<S> parse) Executes a given pre-parsed command.
int	execute(StringReader input, S source) Parses and executes a given command.
int	execute(String input, S source) Parses and executes a given command.
void	findAmbiguities(AmbiguityConsumer<S> consumer) Scans the command tree for potential ambiguous commands.
CommandNode<S>	findNode(Collection<String> path) Finds a node by its path
String[]	getAllUsage(CommandNode<S> node, S source, boolean restricted) Gets all possible executable commands following the given node.
CompletableFuture<Suggestions>	getCompletionSuggestions(ParseResults<S> parse) Gets suggestions for a parsed input string on what comes next.
CompletableFuture<Suggestions>	getCompletionSuggestions(ParseResults<S> parse, int cursor)
Collection<String>	getPath(CommandNode<S> target) Finds a valid path to a given node on the command tree.
RootCommandNode<S>	getRoot() Gets the root of this command tree.
Map<CommandNode<S>,String>	getSmartUsage(CommandNode<S> node, S source) Gets the possible executable commands from a specified node.
ParseResults<S>	parse(StringReader command, S source) Parses a given command.
ParseResults<S>	parse(String command, S source) Parses a given command.
LiteralCommandNode<S>	register(LiteralArgumentBuilder<S> command) Utility method for registering new commands.
void	setConsumer(ResultConsumer<S> consumer) Sets a callback to be informed of the result of every command.

Methods inherited from class java.lang.Object

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

Field Detail

ARGUMENT_SEPARATOR

public static final String ARGUMENT_SEPARATOR

The string required to separate individual arguments in an input string

See Also:

ARGUMENT_SEPARATOR_CHAR, Constant Field Values

ARGUMENT_SEPARATOR_CHAR

public static final char ARGUMENT_SEPARATOR_CHAR

The char required to separate individual arguments in an input string

See Also:

ARGUMENT_SEPARATOR, Constant Field Values

Constructor Detail

CommandDispatcher

public CommandDispatcher(RootCommandNode<S> root)

Create a new CommandDispatcher with the specified root node.

This is often useful to copy existing or pre-defined command trees.

Parameters:

root - the existing RootCommandNode to use as the basis for this tree

CommandDispatcher

public CommandDispatcher()

Creates a new CommandDispatcher with an empty command tree.

Method Detail

register

public LiteralCommandNode<S> register(LiteralArgumentBuilder<S> command)

Utility method for registering new commands.

This is a shortcut for calling CommandNode.addChild(CommandNode) after building the provided command.

As RootCommandNode can only hold literals, this method will only allow literal arguments.

Parameters:

command - a literal argument builder to add to this command tree

Returns:

the node added to this tree

setConsumer

public void setConsumer(ResultConsumer<S> consumer)

Sets a callback to be informed of the result of every command.

Parameters:

consumer - the new result consumer to be called

execute

public int execute(String input,
                   S source)
            throws CommandSyntaxException

Parses and executes a given command.

This is a shortcut to first parse(StringReader, Object) and then execute(ParseResults).

It is recommended to parse and execute as separate steps, as parsing is often the most expensive step, and easiest to cache.

If this command returns a value, then it successfully executed something. If it could not parse the command, or the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException, but it is possible that a RuntimeException may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.

If the command passes through a node that is CommandNode.isFork() then it will be 'forked'. A forked command will not bubble up any CommandSyntaxExceptions, and the 'result' returned will turn into 'amount of successful commands executes'.

After each and any command is ran, a registered callback given to setConsumer(ResultConsumer) will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.

Parameters:

input - a command string to parse & execute

source - a custom "source" object, usually representing the originator of this command

Returns:

a numeric result from a "command" that was performed

Throws:

CommandSyntaxException - if the command failed to parse or execute

RuntimeException - if the command failed to execute and was not handled gracefully

See Also:

parse(String, Object), parse(StringReader, Object), execute(ParseResults), execute(StringReader, Object)

execute

public int execute(StringReader input,
                   S source)
            throws CommandSyntaxException

Parses and executes a given command.

This is a shortcut to first parse(StringReader, Object) and then execute(ParseResults).

It is recommended to parse and execute as separate steps, as parsing is often the most expensive step, and easiest to cache.

If this command returns a value, then it successfully executed something. If it could not parse the command, or the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException, but it is possible that a RuntimeException may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.

If the command passes through a node that is CommandNode.isFork() then it will be 'forked'. A forked command will not bubble up any CommandSyntaxExceptions, and the 'result' returned will turn into 'amount of successful commands executes'.

After each and any command is ran, a registered callback given to setConsumer(ResultConsumer) will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.

Parameters:

input - a command string to parse & execute

source - a custom "source" object, usually representing the originator of this command

Returns:

a numeric result from a "command" that was performed

Throws:

CommandSyntaxException - if the command failed to parse or execute

RuntimeException - if the command failed to execute and was not handled gracefully

See Also:

parse(String, Object), parse(StringReader, Object), execute(ParseResults), execute(String, Object)

execute

public int execute(ParseResults<S> parse)
            throws CommandSyntaxException

Executes a given pre-parsed command.

If this command returns a value, then it successfully executed something. If the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException, but it is possible that a RuntimeException may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.

If the command passes through a node that is CommandNode.isFork() then it will be 'forked'. A forked command will not bubble up any CommandSyntaxExceptions, and the 'result' returned will turn into 'amount of successful commands executes'.

After each and any command is ran, a registered callback given to setConsumer(ResultConsumer) will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.

Parameters:

parse - the result of a successful parse(StringReader, Object)

Returns:

a numeric result from a "command" that was performed.

Throws:

CommandSyntaxException - if the command failed to parse or execute

RuntimeException - if the command failed to execute and was not handled gracefully

See Also:

parse(String, Object), parse(StringReader, Object), execute(String, Object), execute(StringReader, Object)

parse

public ParseResults<S> parse(String command,
                             S source)

Parses a given command.

The result of this method can be cached, and it is advised to do so where appropriate. Parsing is often the most expensive step, and this allows you to essentially "precompile" a command if it will be ran often.

If the command passes through a node that is CommandNode.isFork() then the resulting context will be marked as 'forked'. Forked contexts may contain child contexts, which may be modified by the RedirectModifier attached to the fork.

Parsing a command can never fail, you will always be provided with a new ParseResults. However, that does not mean that it will always parse into a valid command. You should inspect the returned results to check for validity. If its ParseResults.getReader() StringReader.canRead() then it did not finish parsing successfully. You can use that position as an indicator to the user where the command stopped being valid. You may inspect ParseResults.getExceptions() if you know the parse failed, as it will explain why it could not find any valid commands. It may contain multiple exceptions, one for each "potential node" that it could have visited, explaining why it did not go down that node.

When you eventually call execute(ParseResults) with the result of this method, the above error checking will occur. You only need to inspect it yourself if you wish to handle that yourself.

Parameters:

command - a command string to parse

source - a custom "source" object, usually representing the originator of this command

Returns:

the result of parsing this command

See Also:

parse(StringReader, Object), execute(ParseResults), execute(String, Object)

parse

public ParseResults<S> parse(StringReader command,
                             S source)

Parses a given command.

The result of this method can be cached, and it is advised to do so where appropriate. Parsing is often the most expensive step, and this allows you to essentially "precompile" a command if it will be ran often.

If the command passes through a node that is CommandNode.isFork() then the resulting context will be marked as 'forked'. Forked contexts may contain child contexts, which may be modified by the RedirectModifier attached to the fork.

Parsing a command can never fail, you will always be provided with a new ParseResults. However, that does not mean that it will always parse into a valid command. You should inspect the returned results to check for validity. If its ParseResults.getReader() StringReader.canRead() then it did not finish parsing successfully. You can use that position as an indicator to the user where the command stopped being valid. You may inspect ParseResults.getExceptions() if you know the parse failed, as it will explain why it could not find any valid commands. It may contain multiple exceptions, one for each "potential node" that it could have visited, explaining why it did not go down that node.

When you eventually call execute(ParseResults) with the result of this method, the above error checking will occur. You only need to inspect it yourself if you wish to handle that yourself.

Parameters:

command - a command string to parse

source - a custom "source" object, usually representing the originator of this command

Returns:

the result of parsing this command

See Also:

parse(String, Object), execute(ParseResults), execute(String, Object)

getAllUsage

public String[] getAllUsage(CommandNode<S> node,
                            S source,
                            boolean restricted)

Gets all possible executable commands following the given node.

You may use getRoot() as a target to get all usage data for the entire command tree.

The returned syntax will be in "simple" form: <param> and literal. "Optional" nodes will be listed as multiple entries: the parent node, and the child nodes. For example, a required literal "foo" followed by an optional param "int" will be two nodes:

• foo
• foo <int>

The path to the specified node will not be prepended to the output, as there can theoretically be many ways to reach a given node. It will only give you paths relative to the specified node, not absolute from root.

Parameters:

node - target node to get child usage strings for

source - a custom "source" object, usually representing the originator of this command

restricted - if true, commands that the source cannot access will not be mentioned

Returns:

array of full usage strings under the target node

getSmartUsage

public Map<CommandNode<S>,String> getSmartUsage(CommandNode<S> node,
                                                S source)

Gets the possible executable commands from a specified node.

You may use getRoot() as a target to get usage data for the entire command tree.

The returned syntax will be in "smart" form: <param>, literal, [optional] and (either|or). These forms may be mixed and matched to provide as much information about the child nodes as it can, without being too verbose. For example, a required literal "foo" followed by an optional param "int" can be compressed into one string:

• foo [<int>]

The path to the specified node will not be prepended to the output, as there can theoretically be many ways to reach a given node. It will only give you paths relative to the specified node, not absolute from root.

The returned usage will be restricted to only commands that the provided source can use.

Parameters:

node - target node to get child usage strings for

source - a custom "source" object, usually representing the originator of this command

Returns:

array of full usage strings under the target node

getCompletionSuggestions

public CompletableFuture<Suggestions> getCompletionSuggestions(ParseResults<S> parse)

Gets suggestions for a parsed input string on what comes next.

As it is ultimately up to custom argument types to provide suggestions, it may be an asynchronous operation, for example getting in-game data or player names etc. As such, this method returns a future and no guarantees are made to when or how the future completes.

The suggestions provided will be in the context of the end of the parsed input string, but may suggest new or replacement strings for earlier in the input string. For example, if the end of the string was foobar but an argument preferred it to be minecraft:foobar, it will suggest a replacement for that whole segment of the input.

Parameters:

parse - the result of a parse(StringReader, Object)

Returns:

a future that will eventually resolve into a Suggestions object

getCompletionSuggestions

public CompletableFuture<Suggestions> getCompletionSuggestions(ParseResults<S> parse,
                                                               int cursor)

getRoot

public RootCommandNode<S> getRoot()

Gets the root of this command tree.

This is often useful as a target of a ArgumentBuilder.redirect(CommandNode), getAllUsage(CommandNode, Object, boolean) or getSmartUsage(CommandNode, Object). You may also use it to clone the command tree via CommandDispatcher(RootCommandNode).

Returns:

root of the command tree

getPath

public Collection<String> getPath(CommandNode<S> target)

Finds a valid path to a given node on the command tree.

There may theoretically be multiple paths to a node on the tree, especially with the use of forking or redirecting. As such, this method makes no guarantees about which path it finds. It will not look at forks or redirects, and find the first instance of the target node on the tree.

The only guarantee made is that for the same command tree and the same version of this library, the result of this method will always be a valid input for findNode(Collection), which should return the same node as provided to this method.

Parameters:

target - the target node you are finding a path for

Returns:

a path to the resulting node, or an empty list if it was not found

findNode

public CommandNode<S> findNode(Collection<String> path)

Finds a node by its path

Paths may be generated with getPath(CommandNode), and are guaranteed (for the same tree, and the same version of this library) to always produce the same valid node by this method.

If a node could not be found at the specified path, then null will be returned.

Parameters:

path - a generated path to a node

Returns:

the node at the given path, or null if not found

findAmbiguities

public void findAmbiguities(AmbiguityConsumer<S> consumer)

Scans the command tree for potential ambiguous commands.

This is a shortcut for CommandNode.findAmbiguities(AmbiguityConsumer) on getRoot().

Ambiguities are detected by testing every CommandNode.getExamples() on one node verses every sibling node. This is not fool proof, and relies a lot on the providers of the used argument types to give good examples.

Parameters:

consumer - a callback to be notified of potential ambiguities