docs: add docs on command creation (now we have covered all the examples from the Examples module)

Author: yusshu

docs/annotated/annotated.md

@@ -11,12 +11,15 @@ we use this instead of the classic `Command.builder(String)` method.
 You can make a side-by-side comparison of the two approaches in the following table
 and links:
 
-| Imperative                                                                 | Annotated                                                               |
-|----------------------------------------------------------------------------|-------------------------------------------------------------------------|
-| [Basic Command Creation](../imperatively/basic.md)                         | [Basic Command Creation](../annotated/basic.md)                         |
-| [Command with single Argument](../imperatively/argument.md)                | [Command with single Argument](../annotated/argument.md)                |
-| [Command with multiple Arguments](../imperatively/multiple-arguments.md)   | [Command with multiple Arguments](../annotated/multiple-arguments.md)   |
-| [Command with optional Arguments](../imperatively/optional-arguments.md)   | [Command with optional Arguments](../annotated/optional-arguments.md)   |
+| Imperative                                                               | Annotated                                                             |
+|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
+| [Basic Command Creation](../imperatively/basic.md)                       | [Basic Command Creation](../annotated/basic.md)                       |
+| [Command with single Argument](../imperatively/argument.md)              | [Command with single Argument](../annotated/argument.md)              |
+| [Command with multiple Arguments](../imperatively/multiple-arguments.md) | [Command with multiple Arguments](../annotated/multiple-arguments.md) |
+| [Command with optional Arguments](../imperatively/optional-arguments.md) | [Command with optional Arguments](../annotated/optional-arguments.md) |
+| [Command with Permission](../imperatively/with-permission.md)            | [Command with Permission](../annotated/with-permission.md)            |
+| [Command with Switch Arguments](../imperatively/with-switches.md)        | [Command with Switch Arguments](../annotated/with-switches.md)        |
+| [Command with Value Flags](../imperatively/with-value-flags.md)          | [Command with Value Flags](../annotated/with-value-flags.md)          |
 
 ### Elements of the Annotated Command API
 

docs/annotated/index.txt

@@ -6,4 +6,7 @@ subcommand-instance-creator.md
 basic.md
 argument.md
 multiple-arguments.md
-optional-arguments.md
+optional-arguments.md
+with-permission.md
+with-switches.md
+with-value-flags.md

docs/annotated/with-permission.md

@@ -0,0 +1,22 @@
+## #5 With Permission
+
+This example shows how to create a command with a permission requirement
+with the annotated approach:
+
+```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 + "!");
+    }
+    
+}
+```
+
+The `@Command` annotation accepts a `permission` parameter, which is
+used to specify the permission required to execute the command.
+
+Check the [Authorizer page](../configuration/authorizer.md) for more information
+on how to specify how the `CommandManager` should check for permissions. 

docs/annotated/with-switches.md

@@ -0,0 +1,28 @@
+## #6 With Switches
+
+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 `true`,
+and its absence indicates `false`.
+
+<!--@formatter:off-->
+```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);
+    }
+    
+}
+```
+<!--@formatter:on-->
+
+- Executing `test Fixed` will print `Hi Fixed`
+- Executing `test -g Fixed` will print `Goodbye Fixed`
+- Executing `test Fixed -g` will print `Goodbye Fixed`

docs/annotated/with-value-flags.md

@@ -0,0 +1,30 @@
+## #7 With Value Flags
+
+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: `-g true`, `-p 25565`, `-n Fixed`
+
+<!--@formatter:off-->
+```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);
+    }
+    
+}
+```
+<!--@formatter:on-->
+
+- Executing `test Fixed` will print `Hi Fixed`
+- Executing `test Fixed -g GoodBye` will print `GoodBye Fixed`
+- Executing `test Fixed -g Hello` will print `Hello Fixed`
+- Executing `test -g Fixed` will throw a `NoMoreArguments` exception, meaning that the parsing failed
+  because the `Fixed` argument was taken as the value for the flag and no argument
+  is remaining for the name.
+- Executing `test Fixed -g` will throw a `NoMoreArguments` exception, meaning that the parsing failed
+  because the flag doesn't has any argument left to use.

docs/execution/context.md

@@ -0,0 +1,48 @@
+## Command Context
+
+As we have seen in [Command Execution](./execution.md), 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.
+
+### Information
+
+The `CommandContext` contains information about the command execution, such as:
+- A reference to the command *(it may be root or sub command)* being executed
+- A reference to the root command being executed
+- The execution path
+- The input tokens or arguments
+- The used labels (which name/alias was used for every command and sub-command)
+- A command part value
+- All the data from the execution namespace
+
+### Example
+
+<!--@formatter:off-->
+```java
+// create the command manager
+CommandManager manager = ...;
+
+// create & 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'
+```
+<!--@formatter:on-->

docs/execution/execution.md

@@ -0,0 +1,57 @@
+## Command Execution
+
+We already know how to create commands and register them, but now we need to
+actually execute the commands.
+
+> Note that, in certain platforms like Bukkit, Velocity, Discord with JDA, you will not
+have to worry about executing commands since the platform-specific `CommandManager` implementation
+will listen to native events and automatically execute the commands for you, awesome!
+
+We can execute a command by calling the `CommandManager#execute` method, which will
+parse and execute the command from a string command line.
+
+For example:
+
+<!--@formatter:off-->
+```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");
+```
+<!--@formatter:on-->
+
+Note that a `Namespace` is given to the `execute` command, namespaces are used to
+store variables that can be accessed by the command. For example, the `greet` command
+can access the `USER` variable that we set in the namespace.
+
+Here is an example where we access a previously set variable from inside the `Command`
+action:
+
+<!--@formatter:off-->
+```java
+// create a command manager
+CommandManager manager = ...;
+
+// create & 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");
+```
+<!--@formatter:on-->

docs/dispatch/index.txt renamed to docs/execution/index.txt

@@ -2,4 +2,7 @@ intro.md
 basic.md
 argument.md
 multiple-arguments.md
-optional-arguments.md
+optional-arguments.md
+with-permission.md
+with-switches.md
+with-value-flags.md

docs/imperatively/index.txt

@@ -10,9 +10,12 @@ An alternative to this approach is to use the [annotation-based command creation
 You can make a side-by-side comparison of the two approaches in the following table
 and links:
 
-| Imperative                                                                 | Annotated                                                               |
-|----------------------------------------------------------------------------|-------------------------------------------------------------------------|
-| [Basic Command Creation](../imperatively/basic.md)                         | [Basic Command Creation](../annotated/basic.md)                         |
-| [Command with single Argument](../imperatively/argument.md)                | [Command with single Argument](../annotated/argument.md)                |
-| [Command with multiple Arguments](../imperatively/multiple-arguments.md)   | [Command with multiple Arguments](../annotated/multiple-arguments.md)   |
-| [Command with optional Arguments](../imperatively/optional-arguments.md)   | [Command with optional Arguments](../annotated/optional-arguments.md)   |
+| Imperative                                                               | Annotated                                                             |
+|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
+| [Basic Command Creation](../imperatively/basic.md)                       | [Basic Command Creation](../annotated/basic.md)                       |
+| [Command with single Argument](../imperatively/argument.md)              | [Command with single Argument](../annotated/argument.md)              |
+| [Command with multiple Arguments](../imperatively/multiple-arguments.md) | [Command with multiple Arguments](../annotated/multiple-arguments.md) |
+| [Command with optional Arguments](../imperatively/optional-arguments.md) | [Command with optional Arguments](../annotated/optional-arguments.md) |
+| [Command with Permission](../imperatively/with-permission.md)            | [Command with Permission](../annotated/with-permission.md)            |
+| [Command with Switch Arguments](../imperatively/with-switches.md)        | [Command with Switch Arguments](../annotated/with-switches.md)        |
+| [Command with Value Flags](../imperatively/with-value-flags.md)          | [Command with Value Flags](../annotated/with-value-flags.md)          |

docs/imperatively/intro.md

@@ -0,0 +1,22 @@
+## #5 With Permission
+
+This example shows how to create a command with a permission requirement
+with the annotated approach:
+
+<!--@formatter:off-->
+```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();
+```
+<!--@formatter:on-->
+
+Executing the `testUserCommand` will print `Hi` if the user has the `admin`
+permission, but will result in a `NoPermissionException` if the user does not.
+
+Check the [Authorizer page](../configuration/authorizer.md) for more information
+on how to specify how the `CommandManager` should check for permissions.

docs/imperatively/with-permission.md

@@ -0,0 +1,39 @@
+## #6 With Switches
+
+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 `true`,
+and its absence indicates `false`.
+
+<!--@formatter:off-->
+```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.<Boolean>getValue(goodByeSwitch).get();
+
+            context.<String>getValue(name).ifPresent(s -> {
+                if (goodBye) {
+                    System.out.println("Goodbye " + s);
+                    return;
+                }
+                System.out.println("Hi " + s);
+            });
+        })
+        .build();
+```
+<!--@formatter:on-->
+
+- Executing `test Fixed` will print `Hi Fixed`
+- Executing `test -g Fixed` will print `Goodbye Fixed`
+- Executing `test Fixed -g` will print `Goodbye Fixed`

docs/imperatively/with-switches.md

@@ -0,0 +1,40 @@
+## #7 With Value Flags
+
+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: `-g true`, `-p 25565`, `-n Fixed`
+
+<!--@formatter:off-->
+```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.<String>getValue(greetingValue).orElse("Hi");
+            context.<String>getValue(name).ifPresent(s -> {
+                System.out.println(greeting + " " + s);
+            });
+        })
+        .build();
+```
+<!--@formatter:on-->
+
+- Executing `test Fixed` will print `Hi Fixed`
+- Executing `test Fixed -g GoodBye` will print `GoodBye Fixed`
+- Executing `test Fixed -g Hello` will print `Hello Fixed`
+- Executing `test -g Fixed` will throw a `NoMoreArguments` exception, meaning that the parsing failed
+  because the `Fixed` argument was taken as the value for the flag and no argument
+  is remaining for the name.
+- Executing `test Fixed -g` will throw a `NoMoreArguments` exception, meaning that the parsing failed
+  because the flag doesn't has any argument left to use.

docs/imperatively/with-value-flags.md

@@ -3,4 +3,5 @@ installation.md
 concepts
 configuration
 annotated
+execution
 platforms