feat(minimessage): named arguments

text-minimessage/src/jmh/java/net/kyori/adventure/text/minimessage/benchmark/MiniMessageBenchmark.java

@@ -23,21 +23,24 @@
  */
 package net.kyori.adventure.text.minimessage.benchmark;
 
+import java.util.List;
 import java.util.concurrent.TimeUnit;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.NamedTextColor;
 import net.kyori.adventure.text.format.TextColor;
 import net.kyori.adventure.text.minimessage.MiniMessage;
+import net.kyori.adventure.text.minimessage.internal.parser.Token;
+import net.kyori.adventure.text.minimessage.internal.parser.TokenParser;
 import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
 import org.openjdk.jmh.annotations.Fork;
 import org.openjdk.jmh.annotations.Mode;
 import org.openjdk.jmh.annotations.OutputTimeUnit;
 
-@Fork(value = 1, warmups = 1)
+@Fork(value = 2, warmups = 5)
 @BenchmarkMode(Mode.SampleTime)
-@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
 public class MiniMessageBenchmark {
   private static final Component MANY_COLORS = Component.textOfChildren(
     Component.text("red", NamedTextColor.RED),
@@ -47,6 +50,12 @@ public class MiniMessageBenchmark {
     Component.text("another", TextColor.color(0xf6a6a6))
   );
 
+  @Benchmark
+  public List<Token> testTokenization() {
+    final String input = "<red>A very <gradient:red:blue>cool<b> but also</b> <i>some <!i>what <i>complex<!i> and <click:run_command:/lol>crazy (<click:open_url:https://youtube.com/>click here for cool video</click>) <b><st><gold>MiniMessage String.";
+    return TokenParser.tokenize(input, true);
+  }
+
   @Benchmark
   public Component testNiceMix() {
     final String input = "<yellow><test> random <gradient:red:blue:green><bold>stranger</gradient></bold><click:run_command:test command><underlined><red>click here</click><blue> to <rainbow><b>FEEL</rainbow></underlined> it";

text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/ArgumentQueueImpl.java

@@ -23,62 +23,69 @@
  */
 package net.kyori.adventure.text.minimessage;
 
-import java.util.List;
 import java.util.function.Supplier;
+import net.kyori.adventure.text.minimessage.internal.util.ListMapHolder;
 import net.kyori.adventure.text.minimessage.tag.Tag;
 import net.kyori.adventure.text.minimessage.tag.resolver.ArgumentQueue;
+import net.kyori.adventure.util.TriState;
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
 import static java.util.Objects.requireNonNull;
 
+/*
+ * Note to anyone looking at this class and wondering about the {@link NonNull}s. For
+ * some reason, IntelliJ completely ignores any {@link NullMarked} annotations on the package
+ * or on the class, so these pop methods had to be annotated explicitly ¯\_(ツ)_/¯.
+ */
 final class ArgumentQueueImpl<T extends Tag.Argument> implements ArgumentQueue {
   private final Context context;
-  private final List<T> args;
+  private final ListMapHolder<T, String, T> args;
   private int ptr = 0;
 
-  ArgumentQueueImpl(final Context context, final List<T> args) {
+  ArgumentQueueImpl(final Context context, final ListMapHolder<T, String, T> args) {
     this.context = context;
     this.args = args;
   }
 
-  public List<T> args() {
+  public ListMapHolder<T, String, T> args() {
     return this.args;
   }
 
   @Override
-  public T pop() {
+  public @NonNull T pop() {
     if (!this.hasNext()) {
       throw this.context.newException("Missing argument for this tag!", this);
     }
-    return this.args.get(this.ptr++);
+    return this.args.list().get(this.ptr++);
   }
 
   @Override
-  public T popOr(final String errorMessage) {
+  public @NonNull T popOr(final String errorMessage) {
     requireNonNull(errorMessage, "errorMessage");
     if (!this.hasNext()) {
       throw this.context.newException(errorMessage, this);
     }
-    return this.args.get(this.ptr++);
+    return this.args.list().get(this.ptr++);
   }
 
   @Override
-  public T popOr(final Supplier<String> errorMessage) {
+  public @NonNull T popOr(final Supplier<String> errorMessage) {
     requireNonNull(errorMessage, "errorMessage");
     if (!this.hasNext()) {
       throw this.context.newException(requireNonNull(errorMessage.get(), "errorMessage.get()"), this);
     }
-    return this.args.get(this.ptr++);
+    return this.args.list().get(this.ptr++);
   }
 
   @Override
   public @Nullable T peek() {
-    return this.hasNext() ? this.args.get(this.ptr) : null;
+    return this.hasNext() ? this.args.list().get(this.ptr) : null;
   }
 
   @Override
   public boolean hasNext() {
-    return this.ptr < this.args.size();
+    return this.ptr < this.args.list().size();
   }
 
   @Override
@@ -90,4 +97,60 @@ public void reset() {
   public String toString() {
     return this.args.toString();
   }
+
+  @Override
+  public boolean isPresent(final String name) {
+    requireNonNull(name, "name");
+    return this.args.map().containsKey(name);
+  }
+
+  @Override
+  public Tag.@Nullable Argument get(final String name) {
+    requireNonNull(name, "name");
+    return this.args.map().get(name);
+  }
+
+  @Override
+  public TriState flag(final String name) {
+    final Tag.Argument argument = this.get(name);
+    if (argument == null) {
+      // The normal flag is not preset, so try the inverted flag
+      final Tag.Argument invertedArgument = this.get('!' + name);
+      if (invertedArgument == null) {
+        return TriState.NOT_SET;
+      }
+
+      return TriState.FALSE;
+    }
+
+    return TriState.TRUE;
+  }
+
+  @Override
+  public boolean isFlagPresent(final String name) {
+    if (this.isPresent(name)) {
+      return true;
+    }
+    return this.isPresent('!' + name);
+  }
+
+  @Override
+  public Tag.Argument orThrow(final String name, final String errorMessage) {
+    requireNonNull(errorMessage, "errorMessage");
+    final Tag.Argument arg = this.get(name);
+    if (arg == null) {
+      throw this.context.newException(errorMessage);
+    }
+    return arg;
+  }
+
+  @Override
+  public Tag.Argument orThrow(final String name, final Supplier<String> errorMessage) {
+    requireNonNull(errorMessage, "errorMessage");
+    final Tag.Argument arg = this.get(name);
+    if (arg == null) {
+      throw this.context.newException(errorMessage.get());
+    }
+    return arg;
+  }
 }

text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/ContextImpl.java

@@ -23,6 +23,7 @@
  */
 package net.kyori.adventure.text.minimessage;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Consumer;
 import java.util.function.UnaryOperator;
@@ -31,6 +32,7 @@
 import net.kyori.adventure.text.minimessage.internal.parser.ParsingExceptionImpl;
 import net.kyori.adventure.text.minimessage.internal.parser.Token;
 import net.kyori.adventure.text.minimessage.internal.parser.node.TagPart;
+import net.kyori.adventure.text.minimessage.internal.util.ListMapHolder;
 import net.kyori.adventure.text.minimessage.tag.Tag;
 import net.kyori.adventure.text.minimessage.tag.resolver.ArgumentQueue;
 import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
@@ -177,11 +179,17 @@ private Component deserializeWithOptionalTarget(final String message, final TagR
     }
   }
 
-  private static Token[] tagsToTokens(final List<? extends Tag.Argument> tags) {
-    final Token[] tokens = new Token[tags.size()];
-    for (int i = 0, length = tokens.length; i < length; i++) {
-      tokens[i] = ((TagPart) tags.get(i)).token();
+  private static <T extends Tag.Argument> Token[] tagsToTokens(final ListMapHolder<T, String, T> tags) {
+    final List<Token> tokens = new ArrayList<>(tags.map().size() + tags.list().size());
+
+    for (final Tag.Argument value : tags.map().values()) {
+      tokens.add(((TagPart) value).token());
+    }
+
+    for (final T tag : tags.list()) {
+      tokens.add(((TagPart) tag).token());
     }
-    return tokens;
+
+    return tokens.toArray(Token[]::new);
   }
 }

text-minimessage/src/main/java/net/kyori/adventure/text/minimessage/MiniMessageParser.java

@@ -42,6 +42,7 @@
 import net.kyori.adventure.text.minimessage.tag.Modifying;
 import net.kyori.adventure.text.minimessage.tag.Tag;
 import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
+import org.jspecify.annotations.Nullable;
 
 record MiniMessageParser(TagResolver tagResolver) {
 
@@ -61,7 +62,7 @@ private void escapeTokens(final StringBuilder sb, final String richMessage, fina
       if (token.type() == TokenType.CLOSE_TAG) {
         builder.append(TokenParser.CLOSE_TAG);
       }
-      final List<Token> childTokens = token.childTokens();
+      final List<Token> childTokens = Objects.requireNonNull(token.childTokens());
       for (int i = 0; i < childTokens.size(); i++) {
         if (i != 0) {
           builder.append(TokenParser.SEPARATOR);
@@ -91,7 +92,7 @@ private void processTokens(final StringBuilder sb, final String richMessage, fin
         case TEXT -> sb.append(richMessage, token.startIndex(), token.endIndex());
         case OPEN_TAG, CLOSE_TAG, OPEN_CLOSE_TAG -> {
           // extract tag name
-          if (token.childTokens().isEmpty()) {
+          if (Objects.requireNonNull(token.childTokens()).isEmpty()) {
             sb.append(richMessage, token.startIndex(), token.endIndex());
             continue;
           }
@@ -107,7 +108,7 @@ private void processTokens(final StringBuilder sb, final String richMessage, fin
     }
   }
 
-  RootNode parseToTree(final ContextImpl context) {
+  <T extends Tag.Argument> RootNode parseToTree(final ContextImpl context) {
     final TagResolver combinedResolver = TagResolver.resolver(this.tagResolver, context.extraTags());
     final String processedMessage = context.preProcessor().apply(context.message());
     final Consumer<String> debug = context.debugOutput();
@@ -117,7 +118,29 @@ RootNode parseToTree(final ContextImpl context) {
       debug.accept("\n");
     }
 
-    final TokenParser.TagProvider transformationFactory;
+    final TokenParser.TagProvider<T> transformationFactory = this.transformationFactory(context, debug, combinedResolver);
+
+    final Predicate<String> tagNameChecker = name -> {
+      final String sanitized = TokenParser.TagProvider.sanitizePlaceholderName(name);
+      return combinedResolver.has(sanitized);
+    };
+
+    final String preProcessed = TokenParser.resolvePreProcessTags(processedMessage, transformationFactory);
+    context.message(preProcessed);
+    // Then, once MiniMessage placeholders have been inserted, we can do the real parse
+    final RootNode root = TokenParser.parse(transformationFactory, tagNameChecker, preProcessed, processedMessage, context.strict());
+
+    if (debug != null) {
+      debug.accept("Text parsed into element tree:\n");
+      debug.accept(root.toString());
+    }
+
+    return root;
+  }
+
+  private <T extends Tag.Argument> TokenParser.TagProvider<T> transformationFactory(final ContextImpl context, final @Nullable Consumer<String> debug, final TagResolver combinedResolver) {
+    final TokenParser.TagProvider<T> transformationFactory;
+
     if (debug != null) {
       transformationFactory = (name, args, token) -> {
         try {
@@ -132,30 +155,9 @@ RootNode parseToTree(final ContextImpl context) {
 
           final Tag transformation = combinedResolver.resolve(name, new ArgumentQueueImpl<>(context, args), context);
 
-          if (transformation == null) {
-            debug.accept("Could not match node '");
-            debug.accept(name);
-            debug.accept("'\n");
-          } else {
-            debug.accept("Successfully matched node '");
-            debug.accept(name);
-            debug.accept("' to tag ");
-            debug.accept(transformation.getClass().getName());
-            debug.accept("\n");
-          }
-
-          return transformation;
+          return this.debugPrintTransformation(debug, name, transformation);
         } catch (final ParsingException e) {
-          if (token != null && e instanceof final ParsingExceptionImpl impl) {
-            if (impl.tokens().length == 0) {
-              impl.tokens(new Token[]{token});
-            }
-          }
-          debug.accept("Could not match node '");
-          debug.accept(name);
-          debug.accept("' - ");
-          debug.accept(e.getMessage());
-          debug.accept("\n");
+          this.handleParsingException(e, token, debug, name);
           return null;
         }
       };
@@ -168,22 +170,36 @@ RootNode parseToTree(final ContextImpl context) {
         }
       };
     }
-    final Predicate<String> tagNameChecker = name -> {
-      final String sanitized = TokenParser.TagProvider.sanitizePlaceholderName(name);
-      return combinedResolver.has(sanitized);
-    };
+    return transformationFactory;
+  }
 
-    final String preProcessed = TokenParser.resolvePreProcessTags(processedMessage, transformationFactory);
-    context.message(preProcessed);
-    // Then, once MiniMessage placeholders have been inserted, we can do the real parse
-    final RootNode root = TokenParser.parse(transformationFactory, tagNameChecker, preProcessed, processedMessage, context.strict());
+  private void handleParsingException(final ParsingException exception, final @Nullable Token token, final Consumer<String> debug, final String name) {
+    if (token != null && exception instanceof final ParsingExceptionImpl impl) {
+      if (impl.tokens().length == 0) {
+        impl.tokens(new Token[]{token});
+      }
+    }
+    debug.accept("Could not match node '");
+    debug.accept(name);
+    debug.accept("' - ");
+    debug.accept(exception.getMessage());
+    debug.accept("\n");
+  }
 
-    if (debug != null) {
-      debug.accept("Text parsed into element tree:\n");
-      debug.accept(root.toString());
+  private @Nullable Tag debugPrintTransformation(final Consumer<String> debug, final String name, final @Nullable Tag transformation) {
+    if (transformation == null) {
+      debug.accept("Could not match node '");
+      debug.accept(name);
+      debug.accept("'\n");
+    } else {
+      debug.accept("Successfully matched node '");
+      debug.accept(name);
+      debug.accept("' to tag ");
+      debug.accept(transformation.getClass().getName());
+      debug.accept("\n");
     }
 
-    return root;
+    return transformation;
   }
 
   Component parseFormat(final ContextImpl context) {