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< Suggestions >	getCompletionSuggestions (final ParseResults< S > parse)
	Gets suggestions for a parsed input string on what comes next. More...

CompletableFuture< Suggestions >	getCompletionSuggestions (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()

com.mojang.brigadier.CommandDispatcher< S >.CommandDispatcher ( final 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

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

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

Returns: a numeric result from a "command" that was performed

Exceptions

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)

◆ 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

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

Exceptions

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() [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

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

Exceptions

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)

◆ 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

consumer a 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

path	a 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

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

◆ 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

parse the 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

parse	the result of a `parse(StringReader, Object)`
cursor	the 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

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

◆ getRoot()

RootCommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.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

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

◆ 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

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() [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

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)

◆ register()

LiteralCommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.register ( final LiteralArgumentBuilder< S > command )

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

command a 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

consumer the 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

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CommandDispatcher()

Member Function Documentation

◆ execute() [1/3]

◆ execute() [2/3]

◆ execute() [3/3]

◆ findAmbiguities()

◆ findNode()

◆ getAllUsage()

◆ getCompletionSuggestions() [1/2]

◆ getCompletionSuggestions() [2/2]

◆ getPath()

◆ getRoot()

◆ getSmartUsage()

◆ parse() [1/2]

◆ parse() [2/2]

◆ register()

◆ setConsumer()

Member Data Documentation

◆ ARGUMENT_SEPARATOR

◆ ARGUMENT_SEPARATOR_CHAR