CommandAPI 9.3.0
An API for the command UI introduced in Minecraft 1.13
com.mojang.brigadier.CommandDispatcher< S > Class Template Reference

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

Public Member Functions

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

Static Public Attributes

static final String ARGUMENT_SEPARATOR = " "
 The string required to separate individual arguments in an input string. More...
 
static final char ARGUMENT_SEPARATOR_CHAR = ' '
 The char required to separate individual arguments in an input string. More...
 

Detailed Description

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

Parameters
<S>a custom "source" type, such as a user or originator of a command

Constructor & Destructor Documentation

◆ CommandDispatcher()

Create a new CommandDispatcher with the specified root node.

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

Parameters
rootthe existing RootCommandNode to use as the basis for this tree

Member Function Documentation

◆ execute() [1/3]

int com.mojang.brigadier.CommandDispatcher< S >.execute ( final 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
parsethe result of a successful parse(StringReader, Object)
Returns
a numeric result from a "command" that was performed
Exceptions
CommandSyntaxExceptionif the command failed to parse or execute
RuntimeExceptionif the command failed to execute and was not handled gracefully
See also
#parse(String, Object)
#parse(StringReader, Object)
#execute(String, Object)
#execute(StringReader, Object)

◆ execute() [2/3]

int com.mojang.brigadier.CommandDispatcher< S >.execute ( final String  input,
final 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
inputa command string to parse & execute
sourcea custom "source" object, usually representing the originator of this command
Returns
a numeric result from a "command" that was performed
Exceptions
CommandSyntaxExceptionif the command failed to parse or execute
RuntimeExceptionif the command failed to execute and was not handled gracefully
See also
#parse(String, Object)
#parse(StringReader, Object)
#execute(ParseResults)
#execute(StringReader, Object)

◆ execute() [3/3]

int com.mojang.brigadier.CommandDispatcher< S >.execute ( final StringReader  input,
final 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
inputa command string to parse & execute
sourcea custom "source" object, usually representing the originator of this command
Returns
a numeric result from a "command" that was performed
Exceptions
CommandSyntaxExceptionif the command failed to parse or execute
RuntimeExceptionif the command failed to execute and was not handled gracefully
See also
#parse(String, Object)
#parse(StringReader, Object)
#execute(ParseResults)
#execute(String, Object)

◆ findAmbiguities()

void com.mojang.brigadier.CommandDispatcher< S >.findAmbiguities ( final 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
consumera callback to be notified of potential ambiguities

◆ findNode()

CommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.findNode ( final 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
patha generated path to a node
Returns
the node at the given path, or null if not found

◆ getAllUsage()

String[] com.mojang.brigadier.CommandDispatcher< S >.getAllUsage ( final CommandNode< S >  node,
final S  source,
final 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
nodetarget node to get child usage strings for
sourcea custom "source" object, usually representing the originator of this command
restrictedif true, commands that the source cannot access will not be mentioned
Returns
array of full usage strings under the target node

◆ getCompletionSuggestions() [1/2]

CompletableFuture< Suggestions > com.mojang.brigadier.CommandDispatcher< S >.getCompletionSuggestions ( final 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, reading a file, 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
parsethe result of a parse(StringReader, Object)
Returns
a future that will eventually resolve into a Suggestions object

◆ getCompletionSuggestions() [2/2]

CompletableFuture< Suggestions > com.mojang.brigadier.CommandDispatcher< S >.getCompletionSuggestions ( final ParseResults< S >  parse,
int  cursor 
)

Gets suggestions for a parsed input string on what comes next, checking from the given cursor position.

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, reading a file, 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
parsethe result of a parse(StringReader, Object)
cursorthe index to fetch suggestions for
Returns
a future that will eventually resolve into a Suggestions object

◆ getPath()

Collection< String > com.mojang.brigadier.CommandDispatcher< S >.getPath ( final 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
targetthe target node you are finding a path for
Returns
a path to the resulting node, or an empty list if it was not found

◆ getRoot()

Gets the root of this command tree.

This is often useful as a target of a com.mojang.brigadier.builder.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

◆ getSmartUsage()

Map< CommandNode< S >, String > com.mojang.brigadier.CommandDispatcher< S >.getSmartUsage ( final CommandNode< S >  node,
final 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
nodetarget node to get child usage strings for
sourcea custom "source" object, usually representing the originator of this command
Returns
array of full usage strings under the target node

◆ parse() [1/2]

ParseResults< S > com.mojang.brigadier.CommandDispatcher< S >.parse ( final String  command,
final 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
commanda command string to parse
sourcea 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() [2/2]

ParseResults< S > com.mojang.brigadier.CommandDispatcher< S >.parse ( final StringReader  command,
final 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
commanda command string to parse
sourcea 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)

◆ register()

Utility method for registering new commands.

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

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

Parameters
commanda literal argument builder to add to this command tree
Returns
the node added to this tree

◆ setConsumer()

void com.mojang.brigadier.CommandDispatcher< S >.setConsumer ( final ResultConsumer< S >  consumer)

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

Parameters
consumerthe new result consumer to be called

Member Data Documentation

◆ ARGUMENT_SEPARATOR

final String com.mojang.brigadier.CommandDispatcher< S >.ARGUMENT_SEPARATOR = " "
static

The string required to separate individual arguments in an input string.

See also
ARGUMENT_SEPARATOR_CHAR

◆ ARGUMENT_SEPARATOR_CHAR

final char com.mojang.brigadier.CommandDispatcher< S >.ARGUMENT_SEPARATOR_CHAR = ' '
static

The char required to separate individual arguments in an input string.

See also
ARGUMENT_SEPARATOR