A flexible command framework which removes lots of boilerplate code used in commands

<h2>Annotated Commands</h2>
<code>command-flow</code> allows developers to create full command trees in a declarative way
using annotated classes and methods.
The annotated command API is just an alternative way to create <code>Command</code> instances,
we use this instead of the classic <code>Command.builder(String)</code> method.
<h3>Comparison</h3>
You can make a side-by-side comparison of the two approaches in the following table
and links:
<table>
<thead>
<tr>
<th>Imperative</th>
<th>Annotated</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/basic">Basic Command Creation</a></td>
<td><a href="/docs/command-flow/annotated/annotated/basic">Basic Command Creation</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/argument">Command with single Argument</a></td>
<td><a href="/docs/command-flow/annotated/annotated/argument">Command with single Argument</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/multiple-arguments">Command with multiple Arguments</a></td>
<td><a href="/docs/command-flow/annotated/annotated/multiple-arguments">Command with multiple Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/optional-arguments">Command with optional Arguments</a></td>
<td><a href="/docs/command-flow/annotated/annotated/optional-arguments">Command with optional Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/with-permission">Command with Permission</a></td>
<td><a href="/docs/command-flow/annotated/annotated/with-permission">Command with Permission</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/with-switches">Command with Switch Arguments</a></td>
<td><a href="/docs/command-flow/annotated/annotated/with-switches">Command with Switch Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/annotated/imperatively/with-value-flags">Command with Value Flags</a></td>
<td><a href="/docs/command-flow/annotated/annotated/with-value-flags">Command with Value Flags</a></td>
</tr>
</tbody>
</table>
<h3>Elements of the Annotated Command API</h3>
The annotated command API is composed of:
<ul>
<li>The <code>@Command</code> annotation and others.</li>
<li>The <code>AnnotatedCommandTreeBuilder</code> interface</li>
</ul>

Annotated Commands

<h2>#2 With Arguments</h2>
Check this command example with a single argument:
<pre><code class="hljs language-java">@Command(names = "hello")
public class TestCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name) {
 System.out.println("Hi " + name);
 }
 
}
</code></pre>
In this example:
<ul>
<li>Executing <code>hello yusshu</code> will print <code>Hi yusshu</code></li>
<li>Executing <code>hello Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>hello</code> will result in an error</li>
</ul>

#2 With Arguments

<h2>#1 Basic Command</h2>
Check this basic command example, with no arguments, no subcommands and no permissions,
using the annotated command creation approach:
<pre><code class="hljs language-java">@Command(names = "test")
public class TestCommand implements CommandClass {
 
 @Command(names = "")
 public void run() {
 System.out.println("Hello World!");
 }
 
}
</code></pre>
Executing <code>test</code> will print <code>Hello World!</code>

#1 Basic Command

<h2>Command Class</h2>
The annotated command API has a <code>CommandClass</code> interface used to mark a class as a container
of commands or a command itself.
To declare the commands, we use annotations:
<pre><code class="hljs language-java">@Command(names = "teleport")
public class TeleportCommand implements CommandClass {
 
 @Command(names = "") // empty name indicates the root command
 public void run(
 @Sender Player sender, // the sender player
 Player target // the target player (argument)
 ) {
 sender.teleport(target);
 } 
 
}
</code></pre>
In this example we have created a <code>/teleport</code> command that takes a player name
as an argument (command-flow will parse it and find the right Player) and
teleports the sender to the target player.
The <code>@Command</code> annotation is used to mark a method as a command, it can be used
on methods inside a <code>CommandClass</code> or on the class itself.
See this other example:
<pre><code class="hljs language-java">@Command(names = { "friends", "friend", "f", "fr" }) // name, ...aliases
public class FriendsCommand implements CommandClass {
 
 @Command(names = "add")
 public void add(@Sender Player sender, Player target) {
 // add 'target' to 'sender' friend list
 }
 
 @Command(names = "remove")
 public void remove(@Sender Player sender, Player target) {
 // remove 'target' from 'sender' friend list
 }
 
 @Command(names = "list")
 public void list(@Sender Player sender) {
 // list all 'sender' friends and show
 }
 
 @Command(names = "broadcast")
 public void broadcast(@Sender Player sender, @Text String message) {
 // send 'message' to all the friends of 'sender'
 }
 
}
</code></pre>
In this example we have created a <code>/friends</code> command with 4 subcommands:
<ul>
<li><code>/friends add &#x3C;player></code>: add a player to the sender friend list.</li>
<li><code>/friends remove &#x3C;player></code>: remove a player from the sender friend list.</li>
<li><code>/friends list</code>: list all the sender friends.</li>
<li><code>/friends broadcast &#x3C;...message></code>: send a message to all the sender friends.</li>
</ul>
In this new example we also see these new stuff:
<ul>
<li><code>@Command(names = {...})</code>: multiple names! The first one is considered the actual
command name and the rest are aliases.</li>
<li><code>@Text</code>: used to mark a parameter as a text argument, this means that it will
consume all the arguments left in the command and join them with spaces.</li>
</ul>
<h3>Registering them</h3>
To register command classes we must convert them to <code>Command</code> first, we can do
that using the <code>AnnotatedCommandTreeBuilder</code> interface, check the next page!

Command Class

<h2>Command Builder</h2>
The <code>AnnotatedCommandTreeBuilder</code> is the interface responsible for building <code>Command</code>
instances from annotated commands and classes.
<h3>Creating an AnnotatedCommandTreeBuilder</h3>
To create a <code>AnnotatedCommandTreeBuilder</code> we must create a <code>PartInjector</code> first and
(optionally) a <code>SubCommandInstanceCreator</code>. More about this in the next pages.
<pre><code class="hljs language-java">PartInjector injector = ...;
SubCommandInstanceCreator instanceCreator = ...;

AnnotatedCommandTreeBuilder builder = AnnotatedCommandTreeBuilder.create(injector, instanceCreator);
</code></pre>
<h3>Building a Command</h3>
Now that we have a <code>AnnotatedCommandTreeBuilder</code> we can build a command (or multiple commands).
To do this we must call the <code>fromClass</code> method with the class of the command we want to build.
Note that this method returns a list of commands, since a single class may contain multiple
root commands on it.
<pre><code class="hljs language-java">// create the builder
AnnotatedCommandTreeBuilder builder = ...;

// build the Command list from our class
List&#x3C;Command> commands = builder.fromClass(MyCommand.class);

// now we can register them using the CommandManager#registerCommands convenience method
commandManager.registerCommands(commands);
</code></pre>

Command Builder

<h2>#3 Command with Multiple Args</h2>
This example shows how to create a command with multiple arguments
using the annotated approach:
<pre><code class="hljs language-java">@Command(names = "greet")
public class GreetingCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name, boolean formal) {
 if (formal) {
 System.out.println("Hello, " + name + "!");
 } else {
 System.out.println("Hi, " + name + "!");
 }
 }
 
}
</code></pre>
<ul>
<li>Executing <code>greet John false</code> will print <code>Hi, John!</code></li>
<li>Executing <code>greet John true</code> will print <code>Hello, John!</code></li>
<li>Executing <code>greet John</code> will result in a usage error</li>
<li>Executing <code>greet</code> will result in a usage error</li>
</ul>

#3 Command with Multiple Args

<h2>#4 With Optional Args</h2>
This example shows how to create a command with optional arguments
with the annotated approach:
<pre><code class="hljs language-java">@Command(names = "greet")
public class GreetingCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name, @OptArg("Mr.") String title) {
 System.out.println("Hello, " + title + " " + name + "!");
 }
 
}
</code></pre>
The <code>@OptArg</code> annotation is used to mark an argument as optional, and
it accepts a default value as a parameter, which will be used if the
argument is not present in the input.
<ul>
<li>Executing <code>greet John</code> will print <code>Hello, Mr. John!</code></li>
<li>Executing <code>greet John Dr.</code> will print <code>Hello, Dr. John!</code></li>
<li>Executing <code>greet John Mr.</code> will print <code>Hello, Mr. John!</code></li>
</ul>

#4 With Optional Args

<h2>Part Injector</h2>
The <code>PartInjector</code> is a registry which holds the registered PartFactories
and PartModifiers.
<ul>
<li>A <code>PartFactory</code> is a class that provides a way to create an specific type of part.</li>
<li>A <code>PartModifier</code> is like a PartFactory, the difference is that it may wrap the original part 
or modify it instead of creating a new one.</li>
</ul>
<h3>Creating a PartInjector</h3>
Creating a <code>PartInjector</code> is simple, just do the following:
<pre><code class="hljs language-java">PartInjector partInjector = PartInjector.create();

// install the default bindings!
// parts for native and core types like String, Boolean, Double, Float, Integer,
// Text(String), ArgumentStack, CommandContext, also modifiers like LimitModifier,
// OptionalModifier, ValueFlagModifier
partInjector.install(new DefaultsModule());
</code></pre>
<h3>Platform Specific</h3>
Some of the platform-specific subprojects include a <code>Module</code> for the <code>PartInjector</code>
that can be easily installed to obtain the default bindings for that platform.
For example, for Bukkit (<code>commandflow-bukkit</code> subproject):
<pre><code class="hljs language-java">// install bindings for the default bindings for Bukkit, such as
// CommandSender, OfflinePlayer, Player, World, GameMode and @Sender Player
partInjector.install(new BukkitModule());
</code></pre>

Part Injector

<h2>SubCommand Instantiation</h2>
Sometimes we have a command that has subcommands declared with the <code>@SubCommandClasses</code>
annotation. In this case, the command framework needs to know how to instantiate the
subcommands.
We can specify how to instantiate the subcommands by implementing the <code>SubCommandInstanceCreator</code>
interface.
<h3>The <code>SubCommandInstanceCreator</code> interface</h3>
Functional interface that has a single method <code>createInstance(Class&#x3C;? extends CommandClass>, CommandClass)</code>,
that receives the subcommand class and its parent instance, and returns the sub command instance.
If we do not specify one, the annotated command tree builder will instantiate the subcommand
using Reflection, by looking for constructor that accepts the parent's class as the single
parameter an empty constructor.
The <code>SubCommandInstanceCreator</code> is set to the <code>AnnotatedCommandTreeBuilder</code> when instantiating
it, for example:
<pre><code class="hljs language-java">// will use the default SubCommandInstanceCreator
AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(partInjector);

// will use a custom SubCommandInstanceCreator
AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(
 partInjector,
 new MyCustomSubCommandInstanceCreator()
);
</code></pre>
<h3>Common Implementations</h3>
It is common for <code>command-flow</code> to be used along with dependency injection frameworks, so
you can just create a <code>SubCommandInstanceCreator</code> that does the following:
For <a href="https://github.com/google/guice">Google's Guice</a> or <a href="https://github.com/unnamed/inject">Unnamed Team's inject</a>:
<pre><code class="hljs language-java">// obtain the Injector instance
Injector injector = ...;

// create the SubCommandInstanceCreator
SubCommandInstanceCreator subCommandCreator = (clazz, parent) -> injector.getInstance(clazz);

// now set it when creating an AnnotatedCommandTreeBuilder
AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(
 partInjector,
 subCommandCreator
);
</code></pre>

SubCommand Instantiation

<h2>#5 With Permission</h2>
This example shows how to create a command with a permission requirement
with the annotated approach:
<pre><code class="hljs language-java">@Command(names = "greet", permission = "myperm.command.greet")
public class GreetingCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name) {
 System.out.println("Hello, " + name + "!");
 }
 
}
</code></pre>
The <code>@Command</code> annotation accepts a <code>permission</code> parameter, which is
used to specify the permission required to execute the command.
Check the <a href="/docs/command-flow/annotated/configuration/authorizer">Authorizer page</a> for more information
on how to specify how the <code>CommandManager</code> should check for permissions.

#5 With Permission

<h2>#6 With Switches</h2>
This example shows how to create a command with "switch" arguments
(boolean flags) with the imperative approach, note that switch arguments
values are always present. Presence of the switch argument indicates <code>true</code>,
and its absence indicates <code>false</code>.
<pre><code class="hljs language-java">@Command(names = "test")
public class TestCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name, @Switch("g") boolean goodBye) {
 if (goodBye) {
 System.out.println("Goodbye " + name);
 return;
 }
 System.out.println("Hi " + name);
 }
 
}
</code></pre>
<ul>
<li>Executing <code>test Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>test -g Fixed</code> will print <code>Goodbye Fixed</code></li>
<li>Executing <code>test Fixed -g</code> will print <code>Goodbye Fixed</code></li>
</ul>

#6 With Switches

<h2>#7 With Value Flags</h2>
This example shows how to create a command with value flag arguments
the main difference between a value flag and a switch is that the value flag
takes the next argument as its value, and the switch does not.
For example: <code>-g true</code>, <code>-p 25565</code>, <code>-n Fixed</code>
<pre><code class="hljs language-java">@Command(names = "test")
public class TestCommand implements CommandClass {
 
 @Command(names = "")
 public void run(String name, @Flag("g") String greeting) {
 System.out.println(greeting + " " + name);
 }
 
}
</code></pre>
<ul>
<li>Executing <code>test Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>test Fixed -g GoodBye</code> will print <code>GoodBye Fixed</code></li>
<li>Executing <code>test Fixed -g Hello</code> will print <code>Hello Fixed</code></li>
<li>Executing <code>test -g Fixed</code> will throw a <code>NoMoreArguments</code> exception, meaning that the parsing failed
because the <code>Fixed</code> argument was taken as the value for the flag and no argument
is remaining for the name.</li>
<li>Executing <code>test Fixed -g</code> will throw a <code>NoMoreArguments</code> exception, meaning that the parsing failed
because the flag doesn't has any argument left to use.</li>
</ul>

#7 With Value Flags

Annotated

<h2>Command</h2>
Commands are the most fundamental component of the framework. It contains all the
information related to a command, included but not limited to name, aliases, permission,
parts, etc.
Commands are created using the <code>Command.builder(String)</code> method, which returns an
<code>Command.Builder</code> instance where you can set all the information of the command.
Example:
<pre><code class="hljs language-java">Command command = Command.builder("Test")
 .action(context -> {
 System.out.println("Hi!");
 })
 .build();
</code></pre>

Command

<h2>Command Context</h2>
A mutable object which contains the context for a command execution, including but not
limited to the values for every parsed part, the raw arguments list and the raw arguments
for every part, the labels and the Command execution path (which path of subcommands was taken).

Command Context

<h2>Command Manager</h2>
The CommandManager manages the command registration, parsing and execution. Also provides
a way to obtain command suggestions (which can be used for tab-completion in programs like
CLI applications or Minecraft plugins) for a given input.
<h3>Creating a Command Manager</h3>
Depending on your platform, you may want to use a different implementation of the
<code>CommandManager</code>. Check your <a href="/docs/command-flow/concepts/platforms/platforms">platform</a>'s documentation
to get more information.
However, there is a default implementation called <code>SimpleCommandManager</code> which can be
used in any platform, but it doesn't provide any implementation-specific features.
<pre><code class="hljs language-java">CommandManager commandManager = new SimpleCommandManager();
</code></pre>
<h3>Registering commands</h3>
To register a command, you need to create a <code>Command</code> object and register it using
the <code>CommandManager.registerCommand(Command)</code> method.
<pre><code class="hljs language-java">// create CommandManager
CommandManager manager = ...;

// create Command using builder
Command command = Command.builder("test")
 .description("A test command")
 .action(context -> {
 System.out.println("Hello world!");
 })
 .build();

// register the command
manager.registerCommand(command);
</code></pre>

Command Manager

<h2>Command Part</h2>
This is the second most fundamental component, it can be understood as every argument
of a <a href="/docs/command-flow/concepts/command">Command</a>, including things like subcommands, flags, non positional
arguments, etc.
It can use arguments from the argument list, or provide them using any other means. They
can also forward the parsing responsibility to another part and just act as a modifier.
Most of the default parts can be found at the <code>Parts</code> class.

Command Part

<h2>Namespaces</h2>
(If you use an already implemented platform and annotated commands, you don't need
to use Namespaces, yay!)
A namespace is a mapping/set of the arguments that are injected into the execution.
For example, we can inject the user executor of a command and use it later.
Creating a namespace:
<pre><code class="hljs language-java">// Create a namespace
Namespace namespace = Namespace.create();
</code></pre>
Now we can set any object in the namespace, by type and name, for example, suppose we
have a <code>User</code> class:
<pre><code class="hljs language-java">namespace.setObject(User.class, "USER", new User("Fixed", 16));
</code></pre>
And now, we can retrieve the object from the namespace, using the exact same
type and name, for example:
<pre><code class="hljs language-java">User user = namespace.getObject(User.class, "USER");

System.out.println(user.getName()); // Fixed
</code></pre>

Namespaces

Concepts

<h2>Authorizer</h2>
<code>command-flow</code> has a functional interface <code>Authorizer</code> with a single method responsible for
determining if a command should be executed.
<h3>Platform Specific</h3>
There are some platform specific implementations of <code>Authorizer</code>, which are automatically
set if you use the specific <code>CommandManager</code> class, for example, if you instantiate the
<code>BukkitCommandManager</code>, it will already use the <code>BukkitAuthorizer</code> by default, awesome!
<h3>Implementation</h3>
The <code>Authorizer</code> single method accepts a <code>Namespace</code> and the actual permission string,
and returns a boolean value indicating if the command should be executed or not.
Check the following implementation example, suppose we have a <code>User</code> class, and we have
previously set the sender user instance in the execution namespace (Check page about
Command Dispatch)
<pre><code class="hljs language-java">public class MyAuthorizer implements Authorizer {
 @Override
 public boolean isAuthorized(Namespace namespace, String permission) {
 User user = namespace.getObject(User.class, "USER");

 // User not set!
 if (user == null) {
 return false;
 }

 return user.hasPermission(permission);
 }
}
</code></pre>
Now we can set our <code>Authorizer</code> in the <code>CommandManager</code>
<pre><code class="hljs language-java">CommandManager commandManager = ...;

commandManager.setAuthorizer(new MyAuthorizer());
</code></pre>
<h3>Permission String</h3>
The permission string is an optional attribute for <code>Command</code> instances, set during
its instantiation, for example:
Using builders:
<pre><code class="hljs language-java">Command command = Command.builder("test")
 .permission("this.is.the.permission.string")
 .action(context -> {
 System.out.println("Hello World!");
 })
 .build();
</code></pre>
Or annotations:
<pre><code class="hljs language-java">@Command(names = "test", permission = "this.is.the.permission.string")
public class TestCommand implements CommandClass {
 ...
}
</code></pre>

Authorizer

<h2>Configuring the Command Manager</h2>
The <code>CommandManager</code> allows developers to fully configurate its behavior and
how to determine certain aspects of the command parsing &#x26; dispatching process.
The <code>CommandManager</code> can also be extended for platform-specific features and
native integration, like, automatically registering commands in a platform
command registry.

Configuring the Command Manager

<h2>Input Tokenizer</h2>
The input tokenizer is responsible for converting a simple input string into a
list of tokens. The tokens are then used by the parser to enter the desired
command path and either dispatch a command or get suggestions for the next
token.
The <code>InputTokenizer</code> is a functional interface that can be set to the
<code>CommandManager</code> via the <code>CommandManager#setInputTokenizer</code> method.
For example:
<pre><code class="hljs language-java">// create a tokenizer
InputTokenizer tokenizer = ...;

// set the tokenizer
CommandManager manager = ...;
manager.setInputTokenizer(tokenizer);
</code></pre>
<h3>Default Implementations</h3>
<code>command-flow</code> provides two default implementations of the <code>InputTokenizer</code>
interface, <code>StringSpaceTokenizer</code> and <code>QuotedSpaceTokenizer</code>:
<ul>
<li><code>StringSpaceTokenizer</code> - This tokenizer splits the input string by spaces
and returns the resulting tokens. This is the default tokenizer used by
<code>CommandManager</code> if no other tokenizer is set.</li>
<li><code>QuotedSpaceTokenizer</code> - This tokenizer splits the input string by spaces
but also supports quoted strings. For example, the input string
<code>hello "world of commands"</code> would be split into the tokens <code>hello</code> and
<code>world of commands</code>.</li>
</ul>

Input Tokenizer

Configuration

<h2>Command Context</h2>
As we have seen in <a href="/docs/command-flow/execution/execution">Command Execution</a>, we can access previously set
variables in the execution namespace, from a command action, awesome!
But now, we are going to explore more about the command context, and how we can
access more information about the command execution.
<h3>Information</h3>
The <code>CommandContext</code> contains information about the command execution, such as:
<ul>
<li>A reference to the command (it may be root or sub command) being executed</li>
<li>A reference to the root command being executed</li>
<li>The execution path</li>
<li>The input tokens or arguments</li>
<li>The used labels (which name/alias was used for every command and sub-command)</li>
<li>A command part value</li>
<li>All the data from the execution namespace</li>
</ul>
<h3>Example</h3>
<pre><code class="hljs language-java">// create the command manager
CommandManager manager = ...;

// create &#x26; register our command
Command command = Command.builder("test")
 .addAlias("testalias")
 .action(context -> {
 // Here we have an action of the command, and here we can use the context for this command
 // The CommandContext is the result of parsing the arguments of a command.
 // It also extends Namespace, so you can use the Namespace methods on it.
 
 // The labels are the names for every command/subcommand executed.
 // This is the name of the last subcommand/command
 String label = context.getLabels().get(context.getLabels().size() - 1);
 
 System.out.println("Label: " + label);
 })
 .build();
manager.registerCommand(command);

// execute the command
manager.execute(Namespace.create(), "testalias"); // Will print 'Label: testalias'
manager.execute(Namespace.create(), "test"); // Will print 'Label: test'
</code></pre>

<h2>Command Execution</h2>
We already know how to create commands and register them, but now we need to
actually execute the commands.
<blockquote>
Note that, in certain platforms like Bukkit, Velocity, Discord with JDA, you will not
have to worry about executing commands since the platform-specific <code>CommandManager</code> implementation
will listen to native events and automatically execute the commands for you, awesome!
</blockquote>
We can execute a command by calling the <code>CommandManager#execute</code> method, which will
parse and execute the command from a string command line.
For example:
<pre><code class="hljs language-java">// create a command manager
CommandManager manager = ...;

// set up the variables passed to the command
Namespace namespace = Namespace.create();
namespace.setObject(User.class, "USER", new User("Fixed", 16));

// executes the command "greet" with an argument "Yusshu"
manager.execute(namespace, "greet Yusshu");
</code></pre>
Note that a <code>Namespace</code> is given to the <code>execute</code> command, namespaces are used to
store variables that can be accessed by the command. For example, the <code>greet</code> command
can access the <code>USER</code> variable that we set in the namespace.
Here is an example where we access a previously set variable from inside the <code>Command</code>
action:
<pre><code class="hljs language-java">// create a command manager
CommandManager manager = ...;

// create &#x26; register the command
Command command = Command.builder("test")
 .action(context -> {
 User sender = context.getObject(User.class, "SENDER");
 System.out.println("'test' command used by " + sender.getName());
 })
 .build();
manager.registerCommand(command);

// set up the variables passed to the command
Namespace namespace = Namespace.create();
namespace.setObject(User.class, "SENDER", new User("Yusshu", 18));

// executes the command "test"
manager.execute(namespace, "test");
</code></pre>

Command Execution

Execution

<h2>Getting Started</h2>
Welcome to the <code>command-flow</code> documentation
<code>command-flow</code> is a flexible and platform-agnostic command framework
for Java. With this framework you can imperatively create command trees
using builders or declaratively using annotated classes and methods.
See the following example:
<pre><code class="hljs language-java">@Command("test")
public class TestCommand implements CommandClass {
 
 @Command("hello")
 public void hello(CommandSender sender) {
 sender.sendMessage("Hello World!");
 }
 
}
</code></pre>
<h3>Features</h3>
<ul>
<li>Easily create commands using builders or annotations</li>
</ul>

Getting Started

<h2>#2 With Arguments</h2>
Check this command example with a single argument:
<pre><code class="hljs language-java">import static me.fixeddev.commandflow.part.Parts.*;

//...

// create an (argument) part of type string, with the name 'name'
CommandPart nameArg = string("name");

// create the command
Command helloCommand = Command.builder("hello")
 .addPart(nameArg)
 .action(context -> {
 // get the value of the name argument and print 'Hi &#x3C;name>'
 context.&#x3C;String>getValue(nameArg).ifPresent(name -> {
 System.out.println("Hi " + name);
 });
 })
 .build();
</code></pre>
In this example:
<ul>
<li>Executing <code>hello yusshu</code> will print <code>Hi yusshu</code></li>
<li>Executing <code>hello Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>hello</code> will print nothing</li>
</ul>

<h2>#1 Basic Command</h2>
Check this basic command example, with no arguments, no subcommands and no permissions,
using the imperative command creation approach:
<pre><code class="hljs language-java">Command testCommand = Command.builder("test")
 .action(context -> {
 System.out.println("Hello World!");
 })
 .build();
</code></pre>
Executing <code>test</code> will print <code>Hello World!</code>

<h2>Imperative Command Creation</h2>
We can imperatively create commands using the command builder interface. This
way to create commands is the most flexible one, but also the most verbose.
An alternative to this approach is to use the <a href="/docs/command-flow/imperatively/annotated/annotated">annotation-based command creation</a>.
<h3>Comparison</h3>
You can make a side-by-side comparison of the two approaches in the following table
and links:
<table>
<thead>
<tr>
<th>Imperative</th>
<th>Annotated</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/basic">Basic Command Creation</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/basic">Basic Command Creation</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/argument">Command with single Argument</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/argument">Command with single Argument</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/multiple-arguments">Command with multiple Arguments</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/multiple-arguments">Command with multiple Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/optional-arguments">Command with optional Arguments</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/optional-arguments">Command with optional Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/with-permission">Command with Permission</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/with-permission">Command with Permission</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/with-switches">Command with Switch Arguments</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/with-switches">Command with Switch Arguments</a></td>
</tr>
<tr>
<td><a href="/docs/command-flow/imperatively/imperatively/with-value-flags">Command with Value Flags</a></td>
<td><a href="/docs/command-flow/imperatively/annotated/with-value-flags">Command with Value Flags</a></td>
</tr>
</tbody>
</table>

Imperative Command Creation

<h2>#3 Command with Multiple Args</h2>
This example shows how to create a command with multiple arguments
using the imperative approach:
<pre><code class="hljs language-java">// Here we create a StringPart(String argument) with the name "name"
CommandPart name = string("name");

// Here we create a BooleanPart(boolean argument) with the name "formal"
CommandPart formalPart = booleanPart("formal");

Command greetCommand = Command.builder("greet")
 // Here we add a part into the Command
 .addPart(name)
 // You can add multiple parts into a command
 // They will be added into a main part called SequentialCommandPart
 // Which will call every part of the Command in a sequence to parse every argument.
 .addPart(formalPart)
 .action(context -> {
 // The values for a Part(argument) may not be present, check if they're
 // before trying to use them
 boolean formal = context.&#x3C;Boolean>getValue(formalPart).orElse(false);
 context.&#x3C;String>getValue(name).ifPresent(s -> {
 if (formal) {
 System.out.println("Hello, " + s + "!");
 } else {
 System.out.println("Hi, " + s + "!");
 }
 });
 })
 .build();
</code></pre>
<ul>
<li>Executing <code>greet John false</code> will print <code>Hi, John!</code></li>
<li>Executing <code>greet John true</code> will print <code>Hello, John!</code></li>
<li>Executing <code>greet John</code> will print <code>Hi, John!</code></li>
<li>Executing <code>greet</code> will print nothing</li>
</ul>

<h2>#4 With Optional Args</h2>
This example shows how to create a command with optional arguments
with the imperative approach:
<pre><code class="hljs language-java">CommandPart titleValue = string("title");

// This makes the titleValue argument optional, with the default value "Mr."
CommandPart title = optional(titleValue, Collections.singletonList("Mr."));

CommandPart name = string("name");

Command greetCommand = Command.builder("greet")
 .addPart(name)
 .addPart(title)
 .action(context -> {
 String nameString = context.&#x3C;String>getValue(nameValue).orElse("User");

 // Should be present every time, since it has a default value
 // If the default value is not valid for the specified part, then the argument could be absent
 String titleString = context.&#x3C;String>getValue(titleValue).get();
 
 System.out.println("Hello, " + titleString + " " + nameString);
 })
 .build();
</code></pre>
<ul>
<li>Executing <code>greet John</code> will print <code>Hello, Mr. John!</code></li>
<li>Executing <code>greet John Dr.</code> will print <code>Hello, Dr. John!</code></li>
<li>Executing <code>greet John Mr.</code> will print <code>Hello, Mr. John!</code></li>
</ul>

<h2>#5 With Permission</h2>
This example shows how to create a command with a permission requirement
with the annotated approach:
<pre><code class="hljs language-java">Command testUserCommand = Command.builder("test")
 // We set the permission of the test command into admin
 .permission("admin")
 .action(context -> {
 System.out.println("Hi");
 })
 .build();
</code></pre>
Executing the <code>testUserCommand</code> will print <code>Hi</code> if the user has the <code>admin</code>
permission, but will result in a <code>NoPermissionException</code> if the user does not.
Check the <a href="/docs/command-flow/imperatively/configuration/authorizer">Authorizer page</a> for more information
on how to specify how the <code>CommandManager</code> should check for permissions.

<h2>#6 With Switches</h2>
This example shows how to create a command with "switch" arguments
(boolean flags) with the imperative approach, note that switch arguments
values are always present. Presence of the switch argument indicates <code>true</code>,
and its absence indicates <code>false</code>.
<pre><code class="hljs language-java">CommandPart name = string("name");

// If the -g argument is present, then the switch value will be true, otherwise false
// It can be in any position, but the parts registered before will take priority,
// that means that if the name part is registered before the switch part, the -g only
// can be after the name
CommandPart goodByeSwitch = switchPart("goodBye", "g");

Command testUserCommand = Command.builder("test")
 .addPart(goodByeSwitch)
 .addPart(name)
 .action(context -> {
 // The value for a switch is never absent
 boolean goodBye = context.&#x3C;Boolean>getValue(goodByeSwitch).get();

 context.&#x3C;String>getValue(name).ifPresent(s -> {
 if (goodBye) {
 System.out.println("Goodbye " + s);
 return;
 }
 System.out.println("Hi " + s);
 });
 })
 .build();
</code></pre>
<ul>
<li>Executing <code>test Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>test -g Fixed</code> will print <code>Goodbye Fixed</code></li>
<li>Executing <code>test Fixed -g</code> will print <code>Goodbye Fixed</code></li>
</ul>

<h2>#7 With Value Flags</h2>
This example shows how to create a command with value flag arguments
the main difference between a value flag and a switch is that the value flag
takes the next argument as its value, and the switch does not.
For example: <code>-g true</code>, <code>-p 25565</code>, <code>-n Fixed</code>
<pre><code class="hljs language-java">CommandPart name = string("name");

// This part is like a switch part, the difference is that when the main "switch" is found
// the part provided in the first argument takes the parsing, consuming one or more arguments
// from the stack at that position.
CommandPart greetingValue = string("greeting");
CommandPart greetingValueFlag = valueFlag(greetingValue, "g");

Command testUserCommand = Command.builder("test")
 .addPart(greetingValueFlag)
 .addPart(name)
 .action(context -> {
 // The value for a value flag can be absent
 String greeting = context.&#x3C;String>getValue(greetingValue).orElse("Hi");
 context.&#x3C;String>getValue(name).ifPresent(s -> {
 System.out.println(greeting + " " + s);
 });
 })
 .build();
</code></pre>
<ul>
<li>Executing <code>test Fixed</code> will print <code>Hi Fixed</code></li>
<li>Executing <code>test Fixed -g GoodBye</code> will print <code>GoodBye Fixed</code></li>
<li>Executing <code>test Fixed -g Hello</code> will print <code>Hello Fixed</code></li>
<li>Executing <code>test -g Fixed</code> will throw a <code>NoMoreArguments</code> exception, meaning that the parsing failed
because the <code>Fixed</code> argument was taken as the value for the flag and no argument
is remaining for the name.</li>
<li>Executing <code>test Fixed -g</code> will throw a <code>NoMoreArguments</code> exception, meaning that the parsing failed
because the flag doesn't has any argument left to use.</li>
</ul>

Imperatively

<h2>Installation</h2>
You can add <code>command-flow</code> to your project using <a href="https://gradle.org/">Gradle</a>,
<a href="https://maven.apache.org/">Maven</a> or manually downloading the JAR files
<h3>Gradle</h3>
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
<pre><code class="hljs language-kotlin">dependencies {
 implementation("me.fixeddev:commandflow-universal:0.6.0")
}
</code></pre>
<h3>Maven</h3>
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>me.fixeddev&#x3C;/groupId>
 &#x3C;artifactId>commandflow-universal&#x3C;/artifactId>
 &#x3C;version>0.6.0&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Installation

Bukkit with Brigadier

<h2>Bukkit</h2>
<code>command-flow</code> provides a Bukkit implementation of the <code>CommandManager</code> interface and
some other common interfaces. These implementations are provided by the <code>commandflow-bukkit</code>
subproject that can be included in your project by doing the following:
Gradle:
<pre><code class="hljs language-kotlin">dependencies {
 // ...
 implementation("me.fixeddev:commandflow-bukkit:0.6.0")
}
</code></pre>
Maven:
<pre><code class="hljs language-xml">&#x3C;dependencies>
 &#x3C;!-- ... -->
 &#x3C;dependency>
 &#x3C;groupId>me.fixeddev&#x3C;/groupId>
 &#x3C;artifactId>commandflow-bukkit&#x3C;/artifactId>
 &#x3C;version>0.6.0&#x3C;/version>
 &#x3C;/dependency>
&#x3C;/dependencies>
</code></pre>
<h3>Usage</h3>
The <code>commandflow-bukkit</code> subproject consists on providing the following classes:
<ul>
<li><code>CommandManager</code> -> <code>BukkitCommandManager</code>: Bukkit's CommandManager implementation</li>
<li><code>Authorizer</code> -> <code>BukkitAuthorizer</code>: Checks permissions using <code>CommandSender#hasPermission</code></li>
<li><code>Module</code> -> <code>BukkitModule</code>: Provides part factories for <code>CommandSender</code>, <code>GameMode</code>,
<code>OfflinePlayer</code>, <code>Player</code>, <code>@Sender Player</code>, <code>World</code></li>
<li><code>@Sender</code>, <code>@PlayerOrSource</code>, <code>@Exact</code> extra annotations</li>
</ul>
<h3>Example</h3>
<pre><code class="hljs language-java">@Command(names = "gamemode", permission = "myplugin.gamemode")
class GameModeCommand implements CommandClass {
 
 @Command(names = "")
 public void run(@Sender Player sender, GameMode gameMode, @OptArg Player target) {
 if (target == null) {
 sender.setGameMode(gameMode);
 } else {
 target.setGameMode(gameMode);
 }
 sender.sendMessage("Success!");
 }
 
}

class MyPlugin extends JavaPlugin {
 
 @Override
 public void onEnable() {
 registerCommands();
 
 // now you can use '/gamemode &#x3C;gamemode> [target]' in game!
 }
 
 private void registerCommands() {
 CommandManager manager = new BukkitCommandManager("myplugin"); // &#x3C;-- your plugin name
 
 // annotated!
 PartInjector injector = PartInjector.create();
 injector.install(new DefaultsModule());
 injector.install(new BukkitModule()); // &#x3C;-- BukkitModule!
 AnnotatedCommandTreeBuilder builder = AnnotatedCommandTreeBuilder.create(injector);
 
 // register
 manager.registerCommands(builder.fromClass(new GameModeCommand()));
 }
 
}
</code></pre>

Bukkit

BungeeCord

Discord (JDA)

<h2>Platforms</h2>
<code>command-flow</code> core is platform-agnostic, however, it provides a way to integrate with
platform-specific features, such as native command registration, tab-completion/suggestions,
etc.
At the moment we support the following platforms:
<ul>
<li><a href="/docs/command-flow/platforms/bukkit">Bukkit</a></li>
<li><a href="/docs/command-flow/platforms/brigadier">Bukkit with Brigadier</a></li>
<li><a href="/docs/command-flow/platforms/bungeecord">BungeeCord</a></li>
<li><a href="/docs/command-flow/platforms/discord-jda">Discord with JDA</a></li>
<li><a href="/docs/command-flow/platforms/velocity">Velocity</a></li>
</ul>
However, you can make your own platform implementation easily.