feat: finish executors

Author: MC-XiaoHei

docs/en/create-commands/executors/handle-failures.md

@@ -29,13 +29,9 @@ Therefore, to gracefully handle this with a proper error message, we use one of
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandFailures1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/HandleFailures.java#handleFailuresExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandFailures1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/HandleFailures.kt#handleFailuresExample
 :::
 
 ::::

docs/en/create-commands/executors/native-sender.md

@@ -52,17 +52,11 @@ As you can see, this command takes no arguments. This is fine, since our "argume
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:native1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/NativeSender.java#breakCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:native1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/NativeSender.kt#breakCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:native1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/NativeSender.kt#breakCommandExampleDSL
 :::
 
 This can now be used via the following command examples:

docs/en/create-commands/executors/proxy-sender.md

@@ -16,17 +16,11 @@ Say we have a command which kills the sender of a command. This is easily implem
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:proxySender1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/ProxySender.java#simpleKillCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:proxySender1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ProxySender.kt#simpleKillCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:proxySender1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ProxySender.kt#simpleKillCommandExampleDSL
 :::
 
 But what if the sender of the command is _not_ a player? By using Minecraft's `/execute` command, we could execute the command as _any_ arbitrary entity, as shown with the command below:
@@ -39,17 +33,11 @@ To handle this case, we can use the `.executesProxy()` method to ensure that the
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:proxySender2}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/ProxySender.java#proxyKillCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:proxySender2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ProxySender.kt#proxyKillCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:proxySender2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ProxySender.kt#proxyKillCommandExampleDSL
 :::
 
 This allows the command above to run successfully, killing all chickens it can find.

docs/en/create-commands/executors/resulting-executors.md

@@ -32,17 +32,11 @@ Say we want a command that returns a random number as a result. This can then be
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:resultingCommandExecutors1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/ResultingExecutors.java#randomResultCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:resultingCommandExecutors1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#randomResultCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:resultingCommandExecutors1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#randomResultCommandExampleDSL
 :::
 
 This returns a **success value of 1** _(Because no errors or `CommandAPI.failWithString(String)` was thrown)_ and a **result value of a random number**.
@@ -64,34 +58,22 @@ Since we're declaring commands that are to be used in `/execute`, we must ensure
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:resultingCommandExecutors2}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/ResultingExecutors.java#randomNumberCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:resultingCommandExecutors2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#randomNumberCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:resultingCommandExecutors2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#randomNumberCommandExampleDSL
 :::
 
 Now we write our implementation for `/givereward`. In this example, we use the `EntitySelectorArgument` to select a single player. We cast it to `Player` and then add the items to their inventory.
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:resultingCommandExecutors3}}
-```
+<<< @/../reference-code/src/main/java/createcommands/executors/ResultingExecutors.java#giverewardCommandExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:resultingCommandExecutors3}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#giverewardCommandExample
 ===Kotlin DSL
-```kotlin
-// todo {#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:resultingCommandExecutors3}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/ResultingExecutors.kt#giverewardCommandExampleDSL
 :::
 
 Now that we've declared these commands, we can now use them in practice. We can use a command block to store a random number under the scoreboard score `randVal` for a player called `SomePlayer`, by executing the command `/randomnumber`. Since `/randomnumber` **returns** an integer, this value is stored in the scoreboard score:

reference-code/src/main/java/createcommands/executors/HandleFailures.java

@@ -0,0 +1,32 @@
+package createcommands.executors;
+
+import dev.jorel.commandapi.CommandAPI;
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.ArgumentSuggestions;
+import dev.jorel.commandapi.arguments.StringArgument;
+
+import java.util.Arrays;
+
+class HandleFailures {
+    {
+        // #region handleFailuresExample
+        // Array of fruit
+        String[] fruit = new String[]{"banana", "apple", "orange"};
+
+        // Register the command
+        new CommandAPICommand("getfruit")
+            .withArguments(new StringArgument("item").replaceSuggestions(ArgumentSuggestions.strings(fruit)))
+            .executes((sender, args) -> {
+                String inputFruit = (String) args.get("item");
+
+                if (Arrays.asList(fruit).contains(inputFruit)) {
+                    // Do something with inputFruit
+                } else {
+                    // The sender's input is not in the list of fruit
+                    throw CommandAPI.failWithString("That fruit doesn't exist!");
+                }
+            })
+            .register();
+        // #endregion handleFailuresExample
+    }
+}

reference-code/src/main/java/createcommands/executors/NativeSender.java

@@ -0,0 +1,19 @@
+package createcommands.executors;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import org.bukkit.Location;
+
+class NativeSender {
+    {
+        // #region breakCommandExample
+        new CommandAPICommand("break")
+            .executesNative((sender, args) -> {
+                Location location = sender.getLocation();
+                if (location != null) {
+                    location.getBlock().breakNaturally();
+                }
+            })
+            .register();
+        // #endregion breakCommandExample
+    }
+}

reference-code/src/main/java/createcommands/executors/ProxySender.java

@@ -0,0 +1,30 @@
+package createcommands.executors;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import org.bukkit.entity.LivingEntity;
+
+class ProxySender {
+    {
+        // #region simpleKillCommandExample
+        new CommandAPICommand("killme")
+            .executesPlayer((player, args) -> {
+                player.setHealth(0);
+            })
+            .register();
+        // #endregion simpleKillCommandExample
+
+        // #region proxyKillCommandExample
+        new CommandAPICommand("killme")
+            .executesPlayer((player, args) -> {
+                player.setHealth(0);
+            })
+            .executesProxy((proxy, args) -> {
+                // Check if the callee (target) is an Entity and kill it
+                if (proxy.getCallee() instanceof LivingEntity target) {
+                    target.setHealth(0);
+                }
+            })
+            .register();
+        // #endregion proxyKillCommandExample
+    }
+}

reference-code/src/main/java/createcommands/executors/ResultingExecutors.java

@@ -0,0 +1,43 @@
+package createcommands.executors;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.EntitySelectorArgument;
+import org.bukkit.Bukkit;
+import org.bukkit.Material;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemStack;
+
+import java.util.concurrent.ThreadLocalRandom;
+
+class ResultingExecutors {
+    {
+        // #region randomResultCommandExample
+        new CommandAPICommand("randnum")
+            .executes((sender, args) -> {
+                return ThreadLocalRandom.current().nextInt();
+            })
+            .register();
+        // #endregion randomResultCommandExample
+
+        // #region randomNumberCommandExample
+        // Register random number generator command from 1 to 99 (inclusive)
+        new CommandAPICommand("randomnumber")
+            .executes((sender, args) -> {
+                return ThreadLocalRandom.current().nextInt(1, 100); // Returns random number from 1 <= x < 100
+            })
+            .register();
+        // #endregion randomNumberCommandExample
+
+        // #region giverewardCommandExample
+        // Register reward giving system for a target player
+        new CommandAPICommand("givereward")
+            .withArguments(new EntitySelectorArgument.OnePlayer("target"))
+            .executes((sender, args) -> {
+                Player player = (Player) args.get("target");
+                player.getInventory().addItem(new ItemStack(Material.DIAMOND, 64));
+                Bukkit.broadcastMessage(player.getName() + " won a rare 64 diamonds from a loot box!");
+            })
+            .register();
+        // #endregion giverewardCommandExample
+    }
+}