minimessage: Unify transformations and placeholders

.checkstyle/suppressions.xml

@@ -5,12 +5,9 @@
   <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]Adventure.java" checks="SummaryJavadoc"/>
 
   <!-- no javadoc on test and internal classes -->
-  <suppress files="src[\\/](test|jmh)[\\/]java[\\/].*" checks="FilteringWriteTag"/>
-  <suppress files="src[\\/](test|jmh)[\\/]java[\\/].*" checks="JavadocPackage"/>
-  <suppress files="src[\\/](test|jmh)[\\/]java[\\/].*" checks="MissingJavadoc.*"/>
-  <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]internal[\\/].*" checks="FilteringWriteTag"/>
-  <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]internal[\\/].*" checks="JavadocPackage"/>
-  <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]internal[\\/].*" checks="MissingJavadoc.*"/>
+  <suppress files="src[\\/](test|jmh)[\\/]java[\\/].*" checks="(FilteringWriteTag|JavadocPackage|MissingJavadoc.*)"/>
+  <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]internal[\\/].*" checks="(FilteringWriteTag|JavadocPackage|MissingJavadoc.*)"/>
+  <suppress files="minimessage[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]text[\\/]minimessage[\\/]parser[\\/].*" checks="(FilteringWriteTag|JavadocPackage|MissingJavadoc.*)"/>
 
   <suppress files=".*[\\/]nbt[\\/](List|Compound)BinaryTag.java" checks="MethodName"/>
 </suppressions>

api/src/main/java/net/kyori/adventure/util/Index.java

@@ -174,4 +174,24 @@ private Index(final Map<K, V> keyToValue, final Map<V, K> valueToKey) {
   public @Nullable V value(final @NotNull K key) {
     return this.keyToValue.get(key);
   }
+
+  /**
+   * Get an unmodifiable mapping of index entries from key to value.
+   *
+   * @return a mapping from key to value in the index
+   * @since 4.10.0
+   */
+  public @NotNull Map<K, V> keyToValue() {
+    return Collections.unmodifiableMap(this.keyToValue);
+  }
+
+  /**
+   * Get an unmodifiable mapping of index entries from value to key.
+   *
+   * @return a mapping from value to key in the index
+   * @since 4.10.0
+   */
+  public @NotNull Map<V, K> valueToKey() {
+    return Collections.unmodifiableMap(this.valueToKey);
+  }
 }

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

@@ -26,8 +26,7 @@
 import java.util.concurrent.TimeUnit;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.minimessage.MiniMessage;
-import net.kyori.adventure.text.minimessage.placeholder.Placeholder;
-import net.kyori.adventure.text.minimessage.placeholder.PlaceholderResolver;
+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;
@@ -50,7 +49,7 @@ public Component testSimple() {
     final String input = "<yellow><test><bold>stranger";
     return MiniMessage.miniMessage().deserialize(
       input,
-      PlaceholderResolver.placeholders(Placeholder.component("test", Component.text("test2")))
+      Placeholder.component("test", Component.text("test2"))
     );
   }
 

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

@@ -0,0 +1,90 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2022 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.text.minimessage;
+
+import java.util.List;
+import java.util.function.Supplier;
+import net.kyori.adventure.text.minimessage.tag.Tag;
+import net.kyori.adventure.text.minimessage.tag.resolver.ArgumentQueue;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import static java.util.Objects.requireNonNull;
+
+final class ArgumentQueueImpl<T extends Tag.Argument> implements ArgumentQueue {
+  private final Context context;
+  final List<T> args;
+  private int ptr = 0;
+
+  ArgumentQueueImpl(final Context context, final List<T> args) {
+    this.context = context;
+    this.args = args;
+  }
+
+  @Override
+  public @NotNull T pop() {
+    if (!this.hasNext()) {
+      throw this.context.newException("Missing argument for this tag!", this);
+    }
+    return this.args.get(this.ptr++);
+  }
+
+  @Override
+  public @NotNull T popOr(final @NotNull String errorMessage) {
+    requireNonNull(errorMessage, "errorMessage");
+    if (!this.hasNext()) {
+      throw this.context.newException(errorMessage, this);
+    }
+    return this.args.get(this.ptr++);
+  }
+
+  @Override
+  public @NotNull T popOr(final @NotNull 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++);
+  }
+
+  @Override
+  public @Nullable T peek() {
+    return this.hasNext() ? this.args.get(this.ptr) : null;
+  }
+
+  @Override
+  public boolean hasNext() {
+    return this.ptr < this.args.size();
+  }
+
+  @Override
+  public void reset() {
+    this.ptr = 0;
+  }
+
+  @Override
+  public String toString() {
+    return this.args.toString();
+  }
+}

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

@@ -24,32 +24,63 @@
 package net.kyori.adventure.text.minimessage;
 
 import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.minimessage.tag.resolver.ArgumentQueue;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Parser context for use within transformations.
  *
- * <p>This allows operating recursive parses, for cases where messages may include tokens.</p>
+ * <p>This allows operating recursive parses, for cases where messages may include parse-specific tags.</p>
  *
  * @since 4.10.0
  */
 @ApiStatus.NonExtendable
 public interface Context {
   /**
-   * Returns original message as provided to the parser.
+   * Parses a MiniMessage string using all the settings of this context.
    *
-   * @return ogMessage
+   * @param message the message to parse
+   * @return the parsed message
    * @since 4.10.0
    */
-  @NotNull String originalMessage();
+  @NotNull Component parse(final @NotNull String message);
 
   /**
-   * Parses a MiniMessage using all the settings of this context, including placeholders.
+   * Create a new parsing exception.
    *
-   * @param message the message to parse
-   * @return the parsed message
+   * @param message a detail message describing the error
+   * @param tags the tag parts which caused the error
+   * @return the new parsing exception
    * @since 4.10.0
    */
-  @NotNull Component parse(final @NotNull String message);
+  @NotNull ParsingException newException(
+    final @NotNull String message,
+    final @NotNull ArgumentQueue tags
+  );
+
+  /**
+   * Create a new parsing exception without reference to a specific location.
+   *
+   * @param message a detail message describing the error
+   * @return the new parsing exception
+   * @since 4.10.0
+   */
+  @NotNull ParsingException newException(final @NotNull String message);
+
+  /**
+   * Create a new parsing exception.
+   *
+   * @param message a detail message describing the error
+   * @param cause the cause
+   * @param args arguments that caused the errors
+   * @return the new parsing exception
+   * @since 4.10.0
+   */
+  @NotNull ParsingException newException(
+    final @NotNull String message,
+    final @Nullable Throwable cause,
+    final @NotNull ArgumentQueue args
+  );
 }

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

@@ -23,11 +23,18 @@
  */
 package net.kyori.adventure.text.minimessage;
 
+import java.util.List;
 import java.util.function.Consumer;
 import java.util.function.UnaryOperator;
 import net.kyori.adventure.text.Component;
-import net.kyori.adventure.text.minimessage.placeholder.PlaceholderResolver;
+import net.kyori.adventure.text.minimessage.parser.ParsingExceptionImpl;
+import net.kyori.adventure.text.minimessage.parser.Token;
+import net.kyori.adventure.text.minimessage.parser.node.TagPart;
+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;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import static java.util.Objects.requireNonNull;
 
@@ -38,26 +45,28 @@
  * @since 4.10.0
  */
 class ContextImpl implements Context {
+  private static final Token[] EMPTY_TOKEN_ARRAY = new Token[0];
+
   private final boolean strict;
   private final Consumer<String> debugOutput;
-  private final String originalMessage;
+  private String message;
   private final MiniMessage miniMessage;
-  private final PlaceholderResolver placeholderResolver;
+  private final TagResolver tagResolver;
   private final UnaryOperator<Component> postProcessor;
 
   ContextImpl(
     final boolean strict,
     final Consumer<String> debugOutput,
-    final String originalMessage,
+    final String message,
     final MiniMessage miniMessage,
-    final @NotNull PlaceholderResolver placeholderResolver,
+    final @NotNull TagResolver extraTags,
     final UnaryOperator<Component> postProcessor
   ) {
     this.strict = strict;
     this.debugOutput = debugOutput;
-    this.originalMessage = originalMessage;
+    this.message = message;
     this.miniMessage = miniMessage;
-    this.placeholderResolver = placeholderResolver;
+    this.tagResolver = extraTags;
     this.postProcessor = postProcessor == null ? UnaryOperator.identity() : postProcessor;
   }
 
@@ -66,10 +75,10 @@ static ContextImpl of(
     final Consumer<String> debugOutput,
     final String input,
     final MiniMessageImpl miniMessage,
-    final PlaceholderResolver placeholderResolver,
+    final TagResolver extraTags,
     final UnaryOperator<Component> postProcessor
   ) {
-    return new ContextImpl(strict, debugOutput, input, miniMessage, placeholderResolver, postProcessor);
+    return new ContextImpl(strict, debugOutput, input, miniMessage, extraTags, postProcessor);
   }
 
   public boolean strict() {
@@ -80,13 +89,16 @@ public Consumer<String> debugOutput() {
     return this.debugOutput;
   }
 
-  @Override
-  public @NotNull String originalMessage() {
-    return this.originalMessage;
+  public @NotNull String message() {
+    return this.message;
+  }
+
+  void message(final @NotNull String message) {
+    this.message = message;
   }
 
-  public @NotNull PlaceholderResolver placeholderResolver() {
-    return this.placeholderResolver;
+  public @NotNull TagResolver extraTags() {
+    return this.tagResolver;
   }
 
   public UnaryOperator<Component> postProcessor() {
@@ -95,6 +107,30 @@ public UnaryOperator<Component> postProcessor() {
 
   @Override
   public @NotNull Component parse(final @NotNull String message) {
-    return this.miniMessage.deserialize(requireNonNull(message, "message"), this.placeholderResolver);
+    return this.miniMessage.deserialize(requireNonNull(message, "message"), this.tagResolver);
+  }
+
+  @Override
+  public @NotNull ParsingException newException(@NotNull final String message) {
+    return new ParsingExceptionImpl(message, this.message, null, EMPTY_TOKEN_ARRAY);
+  }
+
+  @Override
+  public ParsingException newException(final String message, final @NotNull ArgumentQueue tags) {
+    return new ParsingExceptionImpl(message, this.message, tagsToTokens(((ArgumentQueueImpl<?>) tags).args));
+  }
+
+  @Override
+  public ParsingException newException(final String message, final @Nullable Throwable cause, final @NotNull ArgumentQueue tags) {
+    return new ParsingExceptionImpl(message, this.message, cause, tagsToTokens(((ArgumentQueueImpl<?>) tags).args));
+  }
+
+  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();
+    }
+    return tokens;
   }
+
 }