go go gadget java 25 + jspecify

Author: TropheusJ

.github/workflows/build.yml

@@ -20,7 +20,7 @@ jobs:
           uses: actions/setup-java@v4
           with:
             distribution: temurin
-            java-version: 21
+            java-version: 25
 
       -   name: Setup Gradle
           uses: gradle/actions/setup-gradle@v4

build.gradle.kts

@@ -4,21 +4,21 @@ plugins {
 }
 
 group = "fish.cichlidmc"
-version = "2.0.1"
+version = "3.0.0"
 
 repositories {
     mavenCentral()
 }
 
 dependencies {
-    compileOnlyApi(libs.jetbrains.annotations)
+    compileOnlyApi(libs.jspecify)
     testImplementation(libs.bundles.junit)
 }
 
 java {
     withSourcesJar()
     toolchain {
-        languageVersion = JavaLanguageVersion.of(21)
+        languageVersion = JavaLanguageVersion.of(25)
     }
 }
 

gradle/libs.versions.toml

@@ -1,9 +1,9 @@
 [versions]
-jetbrains-annotations = "24.1.0"
+jspecify = "1.0.0"
 junit = "6.0.1"
 
 [libraries]
-jetbrains-annotations = { module = "org.jetbrains:annotations", version.ref = "jetbrains-annotations" }
+jspecify = { module = "org.jspecify:jspecify", version.ref = "jspecify" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
 junit-launcher = { module = "org.junit.platform:junit-platform-launcher", version.ref = "junit" }
 

src/main/java/fish/cichlidmc/tinyjson/JsonException.java

@@ -2,19 +2,15 @@
 
 import fish.cichlidmc.tinyjson.value.JsonValue;
 
-/**
- * Exception that may be thrown when managing JSON. This may be thrown for a parsing error or
- * for a deserialization error (such as calling {@link JsonValue#asObject()} on a non-object)
- */
+/// Exception that may be thrown when managing JSON. This may be thrown for a parsing error or
+/// for a deserialization error (such as calling [JsonValue#asObject()] on a non-object)
 public final class JsonException extends RuntimeException {
 	public JsonException(String message) {
 		super(message);
 	}
 
-	/**
-	 * Create a new JsonException with the given value as context. The path is added to the message.
-	 * Format: ${path}: ${message}
-	 */
+	/// Create a new JsonException with the given value as context. The path is added to the message.
+	/// Format: ${path}: ${message}
 	public JsonException(JsonValue value, String message) {
 		this(value.getPath() + ": " + message);
 	}

src/main/java/fish/cichlidmc/tinyjson/TinyJson.java

@@ -1,5 +1,9 @@
 package fish.cichlidmc.tinyjson;
 
+import fish.cichlidmc.tinyjson.parser.ValueParser;
+import fish.cichlidmc.tinyjson.parser.util.ParseInput;
+import fish.cichlidmc.tinyjson.value.JsonValue;
+
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
@@ -14,22 +18,14 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
-import fish.cichlidmc.tinyjson.parser.ValueParser;
-import fish.cichlidmc.tinyjson.parser.util.ParseInput;
-import fish.cichlidmc.tinyjson.value.JsonValue;
-
-/**
- * Primary interface for TinyJson. Provides several methods for parsing JSON from various sources:
- * <ul>
- *     <li>Strings</li>
- *     <li>Files</li>
- *     <li>Paths</li>
- *     <li>URIs</li>
- *     <li>URLs</li>
- *     <li>InputStreams</li>
- *     <li>Readers</li>
- * </ul>
- */
+/// Primary interface for TinyJson. Provides several methods for parsing JSON from various sources:
+/// - Strings
+/// - Files
+/// - Paths
+/// - URIs
+/// - URLs
+/// - InputStreams
+/// - Readers
 public final class TinyJson {
 	private TinyJson() {}
 

src/main/java/fish/cichlidmc/tinyjson/parser/util/ParseInput.java

@@ -1,34 +1,33 @@
 package fish.cichlidmc.tinyjson.parser.util;
 
-import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.CARRIAGE_RETURN;
-import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.EOF;
-import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.LINE_BREAK;
+import fish.cichlidmc.tinyjson.JsonException;
+import org.jspecify.annotations.Nullable;
 
 import java.io.IOException;
 import java.io.PushbackReader;
 import java.io.Reader;
 import java.util.Arrays;
 import java.util.function.Function;
 
-import fish.cichlidmc.tinyjson.JsonException;
+import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.CARRIAGE_RETURN;
+import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.EOF;
+import static fish.cichlidmc.tinyjson.parser.util.ParserUtils.LINE_BREAK;
 
 public final class ParseInput {
 	private final PushbackReader reader;
 
 	private int line = 1;
 	private int col = 1;
 
-	// Nullable
+	@Nullable
 	private CommentState commentState;
 
 	public ParseInput(Reader reader) {
 		this.reader = new PushbackReader(reader, 64);
 	}
 
-	/**
-	 * Read the next character, incrementing the parser location. Throws if the end of input is reached.
-	 * Line breaks are unified into \n.
-	 */
+	/// Read the next character, incrementing the parser location. Throws if the end of input is reached.
+	/// Line breaks are unified into \n.
 	public char next() throws IOException {
 		char next = this.read();
 		if (next == CARRIAGE_RETURN && this.peek() == LINE_BREAK) {
@@ -53,9 +52,7 @@ private void nextLine() {
 		this.col = 1;
 	}
 
-	/**
-	 * Skip past all whitespace at the start of the input, including comments.
-	 */
+	/// Skip past all whitespace at the start of the input, including comments.
 	public void skipWhitespace() throws IOException {
 		while (true) {
 			int next = this.peek();
@@ -118,17 +115,13 @@ public void skipWhitespace() throws IOException {
 		}
 	}
 
-	/**
-	 * Read the next non-whitespace character, throwing if EOF is reached.
-	 */
+	/// Read the next non-whitespace character, throwing if EOF is reached.
 	public char peekNonWhitespace() throws IOException {
 		this.skipWhitespace();
 		return this.peekOrThrow();
 	}
 
-	/**
-	 * Read the next N characters into an array, throwing if EOF is reached.
-	 */
+	/// Read the next N characters into an array, throwing if EOF is reached.
 	public char[] next(int n) throws IOException {
 		char[] array = new char[n];
 		for (int i = 0; i < n; i++) {
@@ -137,9 +130,7 @@ public char[] next(int n) throws IOException {
 		return array;
 	}
 
-	/**
-	 * Read the next character without consuming it. May be EOF.
-	 */
+	/// Read the next character without consuming it. May be EOF.
 	public int peek() throws IOException {
 		int next = this.tryRead();
 		if (next != EOF) {
@@ -148,18 +139,14 @@ public int peek() throws IOException {
 		return next;
 	}
 
-	/**
-	 * Read the next character without consuming it, throwing if it's EOF.
-	 */
+	/// Read the next character without consuming it, throwing if it's EOF.
 	public char peekOrThrow() throws IOException {
 		char next = this.read();
 		this.reader.unread(next);
 		return next;
 	}
 
-	/**
-	 * Peek the next N characters into an array. May be shorter than expected due to EOF.
-	 */
+	/// Peek the next N characters into an array. May be shorter than expected due to EOF.
 	public char[] peek(int n) throws IOException {
 		char[] chars = new char[n];
 		for (int i = 0; i < n; i++) {
@@ -178,9 +165,7 @@ public char[] peek(int n) throws IOException {
 		return chars;
 	}
 
-	/**
-	 * Try to read the next character. May be EOF.
-	 */
+	/// Try to read the next character. May be EOF.
 	public int tryRead() throws IOException {
 		return this.reader.read();
 	}
@@ -189,17 +174,13 @@ public Position pos() {
 		return new Position(this.line, this.col);
 	}
 
-	/**
-	 * Return a new JsonException to be thrown. Message may contain
-	 * "${pos}" as a placeholder for the current input position.
-	 */
+	/// Return a new JsonException to be thrown. Message may contain
+	/// "${pos}" as a placeholder for the current input position.
 	public JsonException error(Function<Position, String> messageFactory) {
 		return new JsonException(messageFactory.apply(this.pos()));
 	}
 
-	/**
-	 * Shortcut for error that just adds 'at ${pos}' to the end.
-	 */
+	/// Shortcut for error that just adds 'at ${pos}' to the end.
 	public JsonException errorAt(String message) {
 		return this.error(pos -> message + " at " + pos);
 	}

src/main/java/fish/cichlidmc/tinyjson/value/JsonPrimitive.java

@@ -5,12 +5,8 @@
 import fish.cichlidmc.tinyjson.value.primitive.JsonNumber;
 import fish.cichlidmc.tinyjson.value.primitive.JsonString;
 
-/**
- * A JsonPrimitive is a JsonValue that holds some direct value and not other JsonValues.
- */
+/// A JsonPrimitive is a JsonValue that holds some direct value and not other JsonValues.
 public abstract sealed class JsonPrimitive<T> extends JsonValue permits JsonString, JsonNumber, JsonBool, JsonNull {
-	/**
-	 * Value held by this JSON value. Always non-null UNLESS this is a JsonNull.
-	 */
+	/// Value held by this JSON value. Always non-null UNLESS this is a JsonNull.
 	public abstract T value();
 }

src/main/java/fish/cichlidmc/tinyjson/value/JsonValue.java

@@ -7,25 +7,21 @@
 import fish.cichlidmc.tinyjson.value.primitive.JsonNull;
 import fish.cichlidmc.tinyjson.value.primitive.JsonNumber;
 import fish.cichlidmc.tinyjson.value.primitive.JsonString;
+import org.jspecify.annotations.Nullable;
 
-/**
- * Parent class to all JSON representations.
- * All JsonValues store a path to themselves for identification in errors. This means that one
- * JsonValue cannot be shared between multiple JsonObjects or JsonArrays and a copy must be made.
- */
+/// Parent class to all JSON representations.
+/// All JsonValues store a path to themselves for identification in errors. This means that one
+/// JsonValue cannot be shared between multiple JsonObjects or JsonArrays and a copy must be made.
 public abstract sealed class JsonValue permits JsonPrimitive, JsonArray, JsonObject {
 	public static final String ROOT_PATH = "$";
+	@Nullable
 	private String path;
 
-	/**
-	 * Create a deep copy of this value and all children.
-	 * The path of this value is not preserved, and all children are updated so that the copy is their root.
-	 */
+	/// Create a deep copy of this value and all children.
+	/// The path of this value is not preserved, and all children are updated so that the copy is their root.
 	public abstract JsonValue copy();
 
-	/**
-	 * Create a pretty-printed string representing this JSON value. This string is parseable back into a JsonValue.
-	 */
+	/// Create a pretty-printed string representing this JSON value. This string is parseable back into a JsonValue.
 	@Override
 	public abstract String toString();
 
@@ -48,10 +44,8 @@ private JsonException typeError(String type) {
 		}
 	}
 
-	/**
-	 * internal - do not call this directly. Paths are managed by JsonArray and JsonObject.
-	 */
-	public void setPath(String path) {
+	/// internal - do not call this directly. Paths are managed by JsonArray and JsonObject.
+	public void setPath(@Nullable String path) {
 		if (this.hasPath() && path != null) {
 			throw new IllegalStateException("Cannot override path " + this.path + " with " + path);
 		}

src/main/java/fish/cichlidmc/tinyjson/value/composite/JsonArray.java

@@ -1,16 +1,17 @@
 package fish.cichlidmc.tinyjson.value.composite;
 
-import java.util.ArrayList;
-import java.util.Iterator;
-import java.util.List;
-import java.util.stream.Stream;
-
 import fish.cichlidmc.tinyjson.JsonException;
 import fish.cichlidmc.tinyjson.value.JsonValue;
 import fish.cichlidmc.tinyjson.value.primitive.JsonBool;
 import fish.cichlidmc.tinyjson.value.primitive.JsonNull;
 import fish.cichlidmc.tinyjson.value.primitive.JsonNumber;
 import fish.cichlidmc.tinyjson.value.primitive.JsonString;
+import org.jspecify.annotations.Nullable;
+
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+import java.util.stream.Stream;
 
 public final class JsonArray extends JsonValue implements Iterable<JsonValue> {
 	private final List<JsonValue> values = new ArrayList<>();
@@ -110,7 +111,7 @@ public String toString() {
 	}
 
 	@Override
-	public void setPath(String path) {
+	public void setPath(@Nullable String path) {
 		super.setPath(path);
 		for (int i = 0; i < this.size(); i++) {
 			JsonValue value = this.get(i);
@@ -130,6 +131,7 @@ private String makePath(int i) {
 
 	private static final class JsonArrayIterator implements Iterator<JsonValue> {
 		private final Iterator<JsonValue> wrapped;
+		@Nullable
 		private JsonValue lastReturned;
 
 		private JsonArrayIterator(Iterator<JsonValue> wrapped) {