Merge pull request #1239 from kermandev/feat/nbt-stringio

kezz · web-flow · commit 00c0e7c9c918 · 2025-06-17T10:11:07.000Z
feat(nbt): TagStringIO Enhancements
diff --git a/nbt/src/main/java/net/kyori/adventure/nbt/CharBuffer.java b/nbt/src/main/java/net/kyori/adventure/nbt/CharBuffer.java
@@ -96,6 +96,18 @@ public CharSequence takeUntil(char until) throws StringTagParseException {
     return result;
   }
 
+  /**
+   * Takes the remaining characters and advances the index to the end of the buffer.
+   *
+   * @return the remaining string from the current index to the length of the sequence.
+   */
+  public CharSequence takeRest() {
+    final int length = this.sequence.length();
+    final CharSequence result = this.sequence.subSequence(this.index, length);
+    this.index = length;
+    return result;
+  }
+
   /**
    * Assert that the next non-whitespace character is the provided parameter.
    *
diff --git a/nbt/src/main/java/net/kyori/adventure/nbt/TagStringIO.java b/nbt/src/main/java/net/kyori/adventure/nbt/TagStringIO.java
@@ -26,6 +26,7 @@
 import java.io.IOException;
 import java.io.Writer;
 import java.util.Arrays;
+import java.util.Objects;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -37,17 +38,29 @@ public final class TagStringIO {
   private static final TagStringIO INSTANCE = new TagStringIO(new Builder());
 
   /**
-   * Get an instance of {@link TagStringIO} that creates reads and writes using standard options.
+   * Get an instance of {@link TagStringIO} that reads and writes using standard options.
    *
    * @return the basic instance
    * @since 4.0.0
+   * @deprecated For removal since 4.22.0, use {@link #tagStringIO()} instead
    */
+  @Deprecated
   public static @NotNull TagStringIO get() {
+    return tagStringIO();
+  }
+
+  /**
+   * Gets an instance of {@link TagStringIO} that reads and writes using standard options.
+   *
+   * @return the basic instance
+   * @since 4.22.0
+   */
+  public static @NotNull TagStringIO tagStringIO() {
     return INSTANCE;
   }
 
   /**
-   * Create an new builder to configure IO.
+   * Create a new builder to configure IO.
    *
    * @return a builder
    * @since 4.0.0
@@ -77,7 +90,8 @@ private TagStringIO(final @NotNull Builder builder) {
    * @throws IOException on any syntax errors
    * @since 4.0.0
    */
-  public CompoundBinaryTag asCompound(final String input) throws IOException {
+  public @NotNull CompoundBinaryTag asCompound(final @NotNull String input) throws IOException {
+    Objects.requireNonNull(input, "input");
     try {
       final CharBuffer buffer = new CharBuffer(input);
       final TagStringReader parser = new TagStringReader(buffer);
@@ -92,6 +106,81 @@ public CompoundBinaryTag asCompound(final String input) throws IOException {
     }
   }
 
+  /**
+   * Read the string into a tag.
+   *
+   * <p>When working with untrusted input (such as from the network), users should be careful
+   * to validate that the {@code input} string is of a reasonable size.</p>
+   *
+   * @param input Input data
+   * @return the parsed tag
+   * @throws IOException on any syntax errors
+   * @since 4.22.0
+   */
+  public @NotNull BinaryTag asTag(final @NotNull String input) throws IOException {
+    Objects.requireNonNull(input, "input");
+    try {
+      final CharBuffer buffer = new CharBuffer(input);
+      final TagStringReader parser = new TagStringReader(buffer);
+      parser.legacy(this.acceptLegacy);
+      final BinaryTag tag = parser.tag();
+      if (buffer.skipWhitespace().hasMore()) {
+        throw new IOException("Document had trailing content after first Tag");
+      }
+      return tag;
+    } catch (final StringTagParseException ex) {
+      throw new IOException(ex);
+    }
+  }
+
+  /**
+   * Read the string into an embedded compound tag, returning the remainder of the input.
+   *
+   * @param input the input string
+   * @param remainder the appendable to write the remainder to
+   * @return the parsed tag with the remainder
+   * @throws IOException on any syntax errors
+   * @since 4.22.0
+   */
+  public @NotNull CompoundBinaryTag asCompound(final @NotNull String input, final @NotNull Appendable remainder) throws IOException {
+    Objects.requireNonNull(input, "input");
+    Objects.requireNonNull(remainder, "remainder");
+    try {
+      final CharBuffer buffer = new CharBuffer(input);
+      final TagStringReader parser = new TagStringReader(buffer);
+      parser.legacy(this.acceptLegacy);
+      final CompoundBinaryTag tag = parser.compound();
+      remainder.append(buffer.takeRest());
+      return tag;
+    } catch (final StringTagParseException ex) {
+      throw new IOException(ex);
+    }
+  }
+
+  /**
+   * Read the string into an embedded tag, returning the remainder of the input.
+   *
+   * @param input the input string
+   * @param remainder the appendable to write the remainder to
+   * @return the parsed tag with the remainder
+   * @throws IOException on any syntax errors
+   * @since 4.22.0
+   */
+  public @NotNull BinaryTag asTag(final @NotNull String input, final @NotNull Appendable remainder) throws IOException {
+    Objects.requireNonNull(input, "input");
+    Objects.requireNonNull(remainder, "remainder");
+    try {
+      final CharBuffer buffer = new CharBuffer(input);
+      final TagStringReader parser = new TagStringReader(buffer);
+      parser.legacy(this.acceptLegacy);
+      final BinaryTag tag = parser.tag();
+      remainder.append(buffer.takeRest());
+      return tag;
+    } catch (final StringTagParseException ex) {
+      throw new IOException(ex);
+    }
+  }
+
   /**
    * Get a string representation of the provided tag.
    *
@@ -100,7 +189,7 @@ public CompoundBinaryTag asCompound(final String input) throws IOException {
    * @throws IOException if any errors occur writing to string
    * @since 4.0.0
    */
-  public String asString(final CompoundBinaryTag input) throws IOException {
+  public @NotNull String asString(final @NotNull CompoundBinaryTag input) throws IOException {
     return this.asString((BinaryTag) input);
   }
 
@@ -112,7 +201,8 @@ public String asString(final CompoundBinaryTag input) throws IOException {
    * @throws IOException if any errors occur writing to string
    * @since 4.20.0
    */
-  public String asString(final BinaryTag input) throws IOException {
+  public @NotNull String asString(final @NotNull BinaryTag input) throws IOException {
+    Objects.requireNonNull(input, "input");
     final StringBuilder sb = new StringBuilder();
     try (final TagStringWriter emit = new TagStringWriter(sb, this.indent)) {
       emit.legacy(this.emitLegacy);
@@ -122,7 +212,7 @@ public String asString(final BinaryTag input) throws IOException {
   }
 
   /**
-   * Writes a tag to in string format.
+   * Writes a compound tag to in string format.
    *
    * <p>The provided {@link Writer} will remain open after reading a tag.</p>
    *
@@ -131,7 +221,23 @@ public String asString(final BinaryTag input) throws IOException {
    * @throws IOException if any IO or syntax errors occur while parsing
    * @since 4.0.0
    */
-  public void toWriter(final CompoundBinaryTag input, final Writer dest) throws IOException {
+  public void toWriter(final @NotNull CompoundBinaryTag input, final @NotNull Writer dest) throws IOException {
+    this.toWriter((BinaryTag) input, dest);
+  }
+
+  /**
+   * Writes a tag to in string format.
+   *
+   * <p>The provided {@link Writer} will remain open after reading a tag.</p>
+   *
+   * @param input Tag to write
+   * @param dest Writer to write to
+   * @throws IOException if any IO or syntax errors occur while parsing
+   * @since 4.22.0
+   */
+  public void toWriter(final @NotNull BinaryTag input, final @NotNull Writer dest) throws IOException {
+    Objects.requireNonNull(input, "input");
+    Objects.requireNonNull(dest, "dest");
     try (final TagStringWriter emit = new TagStringWriter(dest, this.indent)) {
       emit.legacy(this.emitLegacy);
       emit.writeTag(input);
@@ -163,7 +269,7 @@ public static class Builder {
     public @NotNull Builder indent(final int spaces) {
       if (spaces == 0) {
         this.indent = "";
-      } else if ((this.indent.length() > 0 && this.indent.charAt(0) != ' ') || spaces != this.indent.length()) {
+      } else if ((!this.indent.isEmpty() && this.indent.charAt(0) != ' ') || spaces != this.indent.length()) {
         final char[] indent = new char[spaces];
         Arrays.fill(indent, ' ');
         this.indent = String.copyValueOf(indent);
@@ -183,7 +289,7 @@ public static class Builder {
     public @NotNull Builder indentTab(final int tabs) {
       if (tabs == 0) {
         this.indent = "";
-      } else if ((this.indent.length() > 0 && this.indent.charAt(0) != '\t') || tabs != this.indent.length()) {
+      } else if ((!this.indent.isEmpty() && this.indent.charAt(0) != '\t') || tabs != this.indent.length()) {
         final char[] indent = new char[tabs];
         Arrays.fill(indent, '\t');
         this.indent = String.copyValueOf(indent);
diff --git a/nbt/src/test/java/net/kyori/adventure/nbt/StringIOTest.java b/nbt/src/test/java/net/kyori/adventure/nbt/StringIOTest.java
@@ -313,6 +313,31 @@ void testTrailingComma() throws IOException {
     assertEquals(ListBinaryTag.builder().add(StringBinaryTag.stringBinaryTag("hello")).build(), this.stringToTag("[\"hello\",]"));
   }
 
+  @Test
+  void testReadingEmbeddedCompound() throws IOException {
+    final String input = "{test: \"hello\"} extra content";
+    final StringBuilder remainderBuilder = new StringBuilder();
+    final CompoundBinaryTag tag = TagStringIO.get().asCompound(input, remainderBuilder);
+    assertEquals(CompoundBinaryTag.builder().putString("test", "hello").build(), tag);
+    assertEquals(" extra content", remainderBuilder.toString());
+  }
+
+  @Test
+  void testReadingEmbedded() throws IOException {
+    final String input = "[1, 1, 1] extra content";
+    final StringBuilder remainderBuilder = new StringBuilder();
+    final BinaryTag tag = TagStringIO.get().asTag(input, remainderBuilder);
+    assertEquals(ListBinaryTag.builder().add(IntBinaryTag.intBinaryTag(1)).add(IntBinaryTag.intBinaryTag(1)).add(IntBinaryTag.intBinaryTag(1)).build(), tag);
+    assertEquals(" extra content", remainderBuilder.toString());
+  }
+
+  @Test
+  void testReadingInvalidEmbeddedTag() throws IOException {
+    final String input = "{test: \"hello\" extra content";
+    final StringBuilder remainderBuilder = new StringBuilder();
+    assertThrows(IOException.class, () -> TagStringIO.get().asTag(input, remainderBuilder));
+  }
+
   private String tagToString(final BinaryTag tag) throws IOException {
     final StringWriter writer = new StringWriter();
     try (final TagStringWriter emitter = new TagStringWriter(writer, "")) {
