This is often useful to copy existing or pre-defined command trees.
+ * + * @param root the existing {@link RootCommandNode} to use as the basis for this tree + */ public CommandDispatcher(final RootCommandNodeThis is a shortcut for calling {@link RootCommandNode#addChild(CommandNode)} after building the provided {@code command}.
+ * + *As {@link RootCommandNode} can only hold literals, this method will only allow literal arguments.
+ * + * @param command a literal argument builder to add to this command tree + * @return the node added to this tree + */ public LiteralCommandNodeThis is a shortcut to first {@link #parse(StringReader, Object)} and then {@link #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 {@link CommandSyntaxException}, but it is possible that a {@link 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 {@link CommandNode#isFork()} then it will be 'forked'. + * A forked command will not bubble up any {@link CommandSyntaxException}s, and the 'result' returned will turn into + * 'amount of successful commands executes'.
+ * + *After each and any command is ran, a registered callback given to {@link #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.
+ * + * @param input a command string to parse & execute + * @param source a custom "source" object, usually representing the originator of this command + * @return a numeric result from a "command" that was performed + * @throws CommandSyntaxException if the command failed to parse or execute + * @throws RuntimeException if the command failed to execute and was not handled gracefully + * @see #parse(String, Object) + * @see #parse(StringReader, Object) + * @see #execute(ParseResults) + * @see #execute(StringReader, Object) + */ public int execute(final String input, final S source) throws CommandSyntaxException { return execute(new StringReader(input), source); } + /** + * Parses and executes a given command. + * + *This is a shortcut to first {@link #parse(StringReader, Object)} and then {@link #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 {@link CommandSyntaxException}, but it is possible that a {@link 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 {@link CommandNode#isFork()} then it will be 'forked'. + * A forked command will not bubble up any {@link CommandSyntaxException}s, and the 'result' returned will turn into + * 'amount of successful commands executes'.
+ * + *After each and any command is ran, a registered callback given to {@link #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.
+ * + * @param input a command string to parse & execute + * @param source a custom "source" object, usually representing the originator of this command + * @return a numeric result from a "command" that was performed + * @throws CommandSyntaxException if the command failed to parse or execute + * @throws RuntimeException if the command failed to execute and was not handled gracefully + * @see #parse(String, Object) + * @see #parse(StringReader, Object) + * @see #execute(ParseResults) + * @see #execute(String, Object) + */ public int execute(final StringReader input, final S source) throws CommandSyntaxException { final ParseResultsIf 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 {@link CommandSyntaxException}, but it is possible that a {@link 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 {@link CommandNode#isFork()} then it will be 'forked'. + * A forked command will not bubble up any {@link CommandSyntaxException}s, and the 'result' returned will turn into + * 'amount of successful commands executes'.
+ * + *After each and any command is ran, a registered callback given to {@link #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.
+ * + * @param parse the result of a successful {@link #parse(StringReader, Object)} + * @return a numeric result from a "command" that was performed. + * @throws CommandSyntaxException if the command failed to parse or execute + * @throws RuntimeException if the command failed to execute and was not handled gracefully + * @see #parse(String, Object) + * @see #parse(StringReader, Object) + * @see #execute(String, Object) + * @see #execute(StringReader, Object) + */ public int execute(final ParseResultsThe 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 {@link CommandNode#isFork()} then the resulting context will be marked as 'forked'. + * Forked contexts may contain child contexts, which may be modified by the {@link RedirectModifier} attached to the fork.
+ * + *Parsing a command can never fail, you will always be provided with a new {@link 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 {@link ParseResults#getReader()} {@link 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 {@link 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 {@link #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.
+ * + * @param command a command string to parse + * @param source a custom "source" object, usually representing the originator of this command + * @return the result of parsing this command + * @see #parse(StringReader, Object) + * @see #execute(ParseResults) + * @see #execute(String, Object) + */ public ParseResultsThe 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 {@link CommandNode#isFork()} then the resulting context will be marked as 'forked'. + * Forked contexts may contain child contexts, which may be modified by the {@link RedirectModifier} attached to the fork.
+ * + *Parsing a command can never fail, you will always be provided with a new {@link 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 {@link ParseResults#getReader()} {@link 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 {@link 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 {@link #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.
+ * + * @param command a command string to parse + * @param source a custom "source" object, usually representing the originator of this command + * @return the result of parsing this command + * @see #parse(String, Object) + * @see #execute(ParseResults) + * @see #execute(String, Object) + */ public ParseResultsYou may use {@link #getRoot()} as a target to get all usage data for the entire command tree.
+ * + *The returned syntax will be in "simple" form: {@code } and {@code 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:
+ *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.
+ * + * @param node target node to get child usage strings for + * @param source a custom "source" object, usually representing the originator of this command + * @param restricted if true, commands that the {@code source} cannot access will not be mentioned + * @return array of full usage strings under the target node + */ public String[] getAllUsage(final CommandNodeYou may use {@link #getRoot()} as a target to get usage data for the entire command tree.
+ * + *The returned syntax will be in "smart" form: {@code }, {@code literal}, {@code [optional]} and {@code (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:
+ *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 {@code source} can use.
+ * + * @param node target node to get child usage strings for + * @param source a custom "source" object, usually representing the originator of this command + * @return array of full usage strings under the target node + */ public MapAs 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 + * {@code foobar} but an argument preferred it to be {@code minecraft:foobar}, it will suggest a replacement for that + * whole segment of the input.
+ * + * @param parse the result of a {@link #parse(StringReader, Object)} + * @return a future that will eventually resolve into a {@link Suggestions} object + */ public CompletableFutureThis is often useful as a target of a {@link com.mojang.brigadier.builder.ArgumentBuilder#redirect(CommandNode)}, + * {@link #getAllUsage(CommandNode, Object, boolean)} or {@link #getSmartUsage(CommandNode, Object)}. + * You may also use it to clone the command tree via {@link #CommandDispatcher(RootCommandNode)}.
+ * + * @return root of the command tree + */ public RootCommandNodeThere 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 {@link #findNode(Collection)}, which should return the same node + * as provided to this method.
+ * + * @param target the target node you are finding a path for + * @return a path to the resulting node, or an empty list if it was not found + */ public CollectionPaths may be generated with {@link #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 {@code null} will be returned.
+ * + * @param path a generated path to a node + * @return the node at the given path, or null if not found + */ public CommandNodeThis is a shortcut for {@link CommandNode#findAmbiguities(AmbiguityConsumer)} on {@link #getRoot()}.
+ * + *Ambiguities are detected by testing every {@link 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.
+ * + * @param consumer a callback to be notified of potential ambiguities + */ public void findAmbiguities(final AmbiguityConsumer