feat: add DefaultExecutes annotation (#32)

Accidentally also did a minor (actually it was kinda major) rewrite of the path logic back into single argument nodes, as it turns out that it makes a lot of steps much simpler.

Author: Strokkur424

.editorconfig

@@ -30,6 +30,7 @@ export default defineConfig({
             { slug: "docs" },
             { slug: "docs/dependency" },
             { slug: "docs/commands" },
+            { slug: "docs/default-executors" },
             { slug: "docs/arguments" },
             { slug: "docs/permissions" },
             { slug: "docs/records" },

docs/astro.config.mjs

@@ -0,0 +1,102 @@
+---
+title: Default executors
+description: A guide to setting default executors on commands.
+---
+
+Since **StrokkCommands v1.5**, you can now define executors to be put on command node by default if not explicit
+executor is present. This feature is meant to act as a simple way of adding help descriptions or other miscellaneous
+'default' behavior.
+
+## The `@DefaultExecutor` annotation
+This annotation has the exact same syntax as `@Executor`. It behaves the same way (in fact, you can annotate
+the same method both `@Executor` *and* `@DefaultExecutor`) and takes in the same parameter input for a preceding
+literal path.
+
+The only difference is that it will also apply itself to all child notes, instead of only the current argument path.
+
+So if you have a structure similar to this:
+```java title=MyCommand.java
+@Command("command")
+class MyCommand {
+
+  @DefaultExecutes
+  void help(CommandSender sender, String[] extraArgs) {
+    sender.sendPlainMessage("/" + String.join(" ", extraArgs) + " is missing some arguments!");
+  }
+
+  @Executes("some literals")
+  void logic(CommandSender sender, int num, String word) {
+    // ...
+  }
+}
+```
+The following paths will be valid for execution:
+```
+/command                             - MyCommand#help
+/command some                        - MyCommand#help
+/command some literals               - MyCommand#help
+/command some literals <num>         - MyCommand#help
+/command some literals <num> <word>  - MyCommand#logic
+```
+
+You can optionally add either a `String[]` or `List<String>` parameter to the end of the method parameters
+to obtain all arguments (including the command name, without the slash) a user has provided.
+This acts as a way to retrieving the command name (and alias) a user has used and for getting any additional
+input.
+
+## A practical example: extending `MyFirstCommand`
+In [Creating your first command](/docs/commands) we have created a super simple command with a bunch of literals.
+The large number of literals might feel very unintuitive to users. For this reason, it makes sense to add a `@DefaultExecutor`
+for both the `two three four` sequence and for the general `/firstcommand` command.
+
+Doing this is incredibly easy; we simply need to add two default executors for those cases.
+```diff lang=java title=MyFirstCommand.java
+ @Command("firstcommand")
+ @Aliases("fc")
+ @Description("My first StrokkCommands-command!")
+ class MyFirstCommand {
+
++  @DefaultExecutes
++  void help(CommandSender sender, String[] args) {
++    sender.sendRichMessage("""
++            <blue>Command Help for /<cmd></blue><dark_gray>
++             - <gray><aqua>/<cmd> two three four</aqua> a regular fun command >_<</gray>
++             - <gray><aqua>/<cmd> fling</aqua> yeet yourself!</gray>""",
++        Placeholder.parsed("cmd", args[0])
++    );
++  }
++
++  @DefaultExecutes("two")
++  @RequiresOP
++  void helpTwo(CommandSender sender, String[] args) {
++    sender.sendRichMessage("<aqua>/<cmd></aqua> is incomplete! You probably meant <gold>/<cmd_name> two three four<gold> :^)",
++        Placeholder.parsed("cmd", String.join(" ", args)),
++        Placeholder.parsed("cmd_name", args[0])
++    );
++  }
+
+   @Executes("two three four")
+   @RequiresOP
+   void onExecute(CommandSender sender, @Executor Player player) {
+     sender.sendRichMessage("<#f29def>Hey there! You just executed your first command ^-^");
+   }
+
+   @Executes("fling")
+   @Permission("some.permission")
+   void onFling(CommandSender sender, @Executor Player player) {
+     player.setVelocity(player.getVelocity().add(new Vector(0, 10, 0)));
+     player.sendRichMessage("<b><#c4e6ff>WOOSH</b> <#c4fffd>You've been flung!");
+   }
+ }
+```
+
+### In-game preview
+This simple edit behaves exactly how one would expect! Running the command with no arguments will
+display the help declared in the `help` method. It will even include the command name exactly how
+a user has entered it into the chat bar.
+
+![](./assets/default-executors-preview-1.png)
+
+As soon as you enter the `two` literal argument, it will use the `helpTwo` method.
+
+![](./assets/default-executors-preview-2.png)

docs/src/content/docs/docs/assets/default-executors-preview-1.png

@@ -0,0 +1,82 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.List;
+
+/// The default method to call if an invalid number of arguments were declared
+///
+/// This annotation acts very similar to the standard [Executes] annotation, with
+/// the only difference being that it will also apply itself to all child notes.
+///
+/// So if you have a structure similar to this:
+/// ```java
+/// @Command("command")
+/// class MyCommand {
+///
+///   @DefaultExecutes
+///   void help(CommandSender sender, String[] extraArgs) {
+///     sender.sendPlainMessage("/" + String.join(" ", extraArgs) + " is missing some arguments!")
+///   }
+///
+///   @Executes("some literals")
+///   void logic(CommandSender sender, int num, String word) {
+///     // ...
+///   }
+/// }
+/// ```
+/// The following paths will be valid for execution:
+/// ```
+/// /command                             - MyCommand#help
+/// /command some                        - MyCommand#help
+/// /command some literals               - MyCommand#help
+/// /command some literals <num>         - MyCommand#help
+/// /command some literals <num> <word>  - MyCommand#logic
+/// ```
+///
+/// You can add either a `String[]` or `List<String>` parameter to the end of the method parameters
+/// to obtain all arguments (including the command name, without the slash) a user has provided. The [List] is **immutable**.
+///
+/// You can provide a literal path to precede to the [DefaultExecutes] method, exactly the same way as
+/// with the [Executes] annotation. You can also add arguments the exactly same way.
+///
+/// If multiple [DefaultExecutes]-annotated methods are present, the **deeper one** in the tree takes precedence.
+/// If multiple [DefaultExecutes]-annotated methods are present on the same path, the first declared one takes precedence.
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.METHOD)
+public @interface DefaultExecutes {
+  /// A literal path to prepend to the method.
+  ///
+  /// This
+  /// ```java
+  /// @DefaultExecutes("the literal path")
+  /// void help(CommandSender sender, /* rest of arguments */);
+  /// ```
+  /// is the same as writing
+  /// ```java
+  /// @DefaultExecutes
+  /// void help(CommandSender sender, @Literal("the literal path") String lit, /* rest of arguments */);
+  /// ```
+  ///
+  /// @return the literal path to prepend to the argument path
+  String value() default "";
+}

docs/src/content/docs/docs/assets/default-executors-preview-2.png

@@ -23,8 +23,8 @@
 import net.strokkur.commands.annotations.Description;
 import net.strokkur.commands.internal.arguments.BrigadierArgumentConverter;
 import net.strokkur.commands.internal.intermediate.CommandInformation;
-import net.strokkur.commands.internal.intermediate.paths.CommandPath;
-import net.strokkur.commands.internal.intermediate.paths.PathFlattener;
+import net.strokkur.commands.internal.intermediate.TreePostProcessor;
+import net.strokkur.commands.internal.intermediate.tree.CommandNode;
 import net.strokkur.commands.internal.parsing.CommandParser;
 import net.strokkur.commands.internal.parsing.CommandParserImpl;
 import net.strokkur.commands.internal.printer.CommandTreePrinter;
@@ -85,7 +85,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
     final MessagerWrapper messagerWrapper = MessagerWrapper.wrap(super.processingEnv.getMessager());
     final BrigadierArgumentConverter converter = new BrigadierArgumentConverter(messagerWrapper);
     final CommandParser parser = new CommandParserImpl(messagerWrapper, converter);
-    final PathFlattener pathFlattener = new PathFlattener(messagerWrapper);
+    final TreePostProcessor treePostProcessor = new TreePostProcessor(messagerWrapper);
 
     final String debugOnly = System.getProperty(MessagerWrapper.DEBUG_ONLY_SYSTEM_PROPERTY);
     if (debugOnly != null) {
@@ -103,7 +103,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
       }
 
       try {
-        processElement(typeElement, messagerWrapper, parser, pathFlattener);
+        processElement(typeElement, messagerWrapper, parser, treePostProcessor);
       } catch (Exception e) {
         messagerWrapper.errorElement("An error occurred: {}", typeElement, e.getMessage());
         e.printStackTrace(new PrintWriter(System.out));
@@ -119,31 +119,27 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
     return true;
   }
 
-  private void processElement(TypeElement typeElement, MessagerWrapper messagerWrapper, CommandParser parser, PathFlattener pathFlattener) {
+  private void processElement(TypeElement typeElement, MessagerWrapper messagerWrapper, CommandParser parser, TreePostProcessor treePostProcessor) {
     boolean debug = System.getProperty(MessagerWrapper.DEBUG_SYSTEM_PROPERTY) != null;
 
     final CommandInformation commandInformation = getCommandInformation(typeElement);
-    final CommandPath<?> commandPath = parser.createCommandTree(typeElement);
-
-    if (debug) {
-      // debug log all paths.
-      messagerWrapper.debug("Before flatten: \n{}\n ", commandPath.toString());
+    final CommandNode commandTree = parser.createCommandTree(typeElement.getAnnotation(Command.class).value(), typeElement);
+    if (commandTree == null) {
+      return;
     }
 
-    // Before we print the paths, we do a step I like to refer to as "flattening".
-    // This does not actually change the structure of the paths, but it moves up any attributes
-    // relevant for certain things to print correctly (a.e. executor requirements).
-    pathFlattener.cleanupEmptyPaths(commandPath);
-    pathFlattener.cleanupPath(commandPath);
-    pathFlattener.flattenPath(commandPath);
+    // Before we print the paths we do some post-processing to move some stuff around, which
+    // is relevant for certain things to print correctly (a.e. executor requirements).
+    treePostProcessor.cleanupPath(commandTree);
+    treePostProcessor.applyDefaultExecutorPaths(commandTree);
 
     if (debug) {
       // debug log all paths.
-      messagerWrapper.debug("After flatten: \n{}\n ", commandPath.toString());
+      messagerWrapper.debug("Command Tree: \n\n{}\n ", commandTree.toString());
     }
 
     try {
-      final CommandTreePrinter printer = new CommandTreePrinter(0, null, commandPath, commandInformation);
+      final CommandTreePrinter printer = new CommandTreePrinter(0, null, commandTree, commandInformation);
       final JavaFileObject obj = processingEnv.getFiler().createSourceFile(printer.getPackageName() + "." + printer.getBrigadierClassName());
 
       try (PrintWriter out = new PrintWriter(obj.openWriter())) {
@@ -178,4 +174,4 @@ private CommandInformation getCommandInformation(@NonNull TypeElement typeElemen
         aliases != null ? aliases.value() : null
     );
   }
-}
+}

docs/src/content/docs/docs/default-executors.mdx

@@ -15,20 +15,24 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, see <https://www.gnu.org/licenses/>.
  */
-package net.strokkur.commands.internal.intermediate.paths;
+package net.strokkur.commands.internal.arguments;
 
-import net.strokkur.commands.internal.arguments.LiteralCommandArgument;
+import org.jetbrains.annotations.UnmodifiableView;
 
-import java.util.List;
+import javax.lang.model.element.Element;
+import java.util.Set;
 
-public class LiteralCommandPath extends SimpleCommandPathImpl<LiteralCommandArgument> {
+public interface MultiLiteralCommandArgument extends CommandArgument {
 
-  public LiteralCommandPath(final List<LiteralCommandArgument> arguments) {
-    super(arguments);
+  static MultiLiteralCommandArgument multiLiteral(Set<String> literals, Element element) {
+    return new MultiLiteralCommandArgumentImpl(literals, element);
   }
 
+  @UnmodifiableView
+  Set<String> literals();
+
   @Override
-  SimpleCommandPathImpl<LiteralCommandArgument> createLeftSplit(final List<LiteralCommandArgument> args) {
-    return new LiteralCommandPath(args);
+  default String getName() {
+    return "<multiliteral>";
   }
 }

strokk-commands-annotations/src/main/java/net/strokkur/commands/annotations/DefaultExecutes.java

@@ -0,0 +1,32 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands.internal.arguments;
+
+import org.jetbrains.annotations.UnmodifiableView;
+
+import javax.lang.model.element.Element;
+import java.util.Collections;
+import java.util.Set;
+
+record MultiLiteralCommandArgumentImpl(Set<String> literals, Element element) implements MultiLiteralCommandArgument {
+
+  @Override
+  public @UnmodifiableView Set<String> literals() {
+    return Collections.unmodifiableSet(this.literals);
+  }
+}

strokk-commands-processor/src/main/java/net/strokkur/commands/internal/StrokkCommandsProcessor.java

@@ -24,7 +24,6 @@
 import java.util.Objects;
 
 public class RequiredCommandArgumentImpl implements RequiredCommandArgument {
-
   private final BrigadierArgumentType argumentType;
   private final String name;
   private final Element element;
@@ -37,7 +36,7 @@ public RequiredCommandArgumentImpl(final BrigadierArgumentType argumentType, fin
     this.suggestionProvider = null;
   }
 
-  public RequiredCommandArgumentImpl(final BrigadierArgumentType argumentType, final String name, final Element element, final SuggestionProvider suggestionProvider) {
+  public RequiredCommandArgumentImpl(final BrigadierArgumentType argumentType, final String name, final Element element, final @Nullable SuggestionProvider suggestionProvider) {
     this.argumentType = argumentType;
     this.name = name;
     this.element = element;