Class CommandDispatcher<S>

Method Details

• 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)

• parseNodes

  private ParseResults<S> parseNodes(CommandNode<S> node, StringReader originalReader, CommandContextBuilder<S> contextSoFar)

• 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

• getAllUsage

  private void getAllUsage(CommandNode<S> node, S source, ArrayList<String> result, String prefix, boolean restricted)

• 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

• getSmartUsage

  private String getSmartUsage(CommandNode<S> node, S source, boolean optional, boolean deep)

• 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

• addPaths

  private void addPaths(CommandNode<S> node, List<List<CommandNode<S>>> result, List<CommandNode<S>> parents)