Merge pull request #3 from rhysdh540/master

reflection

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: ZSON
-          path: "build/libs/zson-*.jar"
+          path: "build/libs/*.jar"
       - name: Upload test results
         uses: actions/upload-artifact@v3
         with:

README.md

@@ -6,9 +6,89 @@ under the license to "make a reasonable effort under the circumstances to obtain
 the terms of this License".
 
 # ZSON
-
 A tiny JSON5 parsing library for Java 8, with a focus on simplicity and minimizing size.
 
+## Usage
+First, include the library in your project. You can do this by adding the following to your build.gradle(.kts):
+<details>
+<summary>Kotlin</summary>
+
+```kotlin
+repositories {
+    maven("https://maven.blamejared.com")
+}
+
+dependencies {
+    implementation("dev.nolij:zson:version")
+}
+```
+</details>
+<details>
+<summary>Groovy</summary>
+
+```groovy
+repositories {
+    maven { url 'https://maven.blamejared.com' }
+}
+
+dependencies {
+    implementation 'dev.nolij:zson:version'
+}
+```
+</details>
+
+Then, you can use the library like so:
+```java
+import dev.nolij.zson.Zson; // contains static methods for parsing and writing JSON
+import dev.nolij.zson.ZsonWriter; // contains methods for writing JSON
+import dev.nolij.zson.ZsonParser; // contains static methods for parsing JSON
+import dev.nolij.zson.ZsonValue; // represents a JSON value with a comment
+import java.util.Map;
+
+import static dev.nolij.zson.Zson.*;
+
+public class ZsonExample {
+    public static void main(String[] args) {
+        // Parse a JSON string
+        String json = "{\"key\": \"value\"}";
+        Map<String, ZsonValue> zson = ZsonParser.parseString(json);
+        System.out.println(zson.get("key")); // value
+
+        // Write a JSON string
+        ZsonWriter writer = new ZsonWriter().withIndent("  ").withExpandArrays(false);
+		Map<String, ZsonValue> map = object( // Zson.object()
+                entry("key", "comment", 4),
+                entry("arr", "look, arrays work too!", array(1, 2, 3)),
+                entry("obj", "and objects!", object(
+                        entry("key", "value")
+                )),
+                entry("null", "comments can also\nbe miltiple lines", null)
+        );
+		System.out.println(jsonString);
+	}
+}
+
+```
+
+This prints out:
+```json5
+{
+  // comment
+  "key": 4,
+  // look, arrays work too!
+  "arr": [ 1, 2, 3, ],
+  // and objects!
+  "obj": {
+    "key": "value", 
+  },
+  // comments can also
+  // be multiple lines
+  "null": null,
+}
+```
+
+<!--- TODO: make a tutorial for serializing objects and the annotations that help in doing so --->
+
 ## License
 
 This project is licensed under OSL-3.0. For more information, see [LICENSE](LICENSE).

build.gradle.kts

@@ -1,3 +1,4 @@
+import xyz.wagyourtail.jvmdg.gradle.task.DowngradeJar
 import java.time.ZonedDateTime
 
 plugins {
@@ -6,13 +7,15 @@ plugins {
     id("maven-publish")
     id("org.ajoberstar.grgit")
     id("com.github.breadmoirai.github-release")
+    id("xyz.wagyourtail.jvmdowngrader")
 }
 
 operator fun String.invoke(): String = rootProject.properties[this] as? String ?: error("Property $this not found")
 
 group = "maven_group"()
 base.archivesName = "project_name"()
 
+//region Git
 enum class ReleaseChannel(val suffix: String? = null) {
     DEV_BUILD("dev"),
     RELEASE,
@@ -81,6 +84,8 @@ if (releaseChannel.suffix != null) {
 val versionString = "${minorVersion}.${patchAndSuffix}"
 val versionTagName = "${releaseTagPrefix}${versionString}"
 
+//endregion
+
 version = versionString
 println("ZSON Version: $versionString")
 
@@ -90,33 +95,40 @@ repositories {
 
 dependencies {
     compileOnly("org.jetbrains:annotations:${"jetbrains_annotations_version"()}")
-    compileOnly("com.pkware.jabel:jabel-javac-plugin:${"jabel_version"()}", ::annotationProcessor)
 
     testImplementation("org.junit.jupiter:junit-jupiter:5.11.0-M1")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
 }
 
+tasks.downgradeJar {
+    dependsOn(tasks.jar)
+    downgradeTo = JavaVersion.VERSION_1_8
+    archiveClassifier = "downgraded-8"
+}
+
+val downgradeJar17 = tasks.register<DowngradeJar>("downgradeJar17") {
+    dependsOn(tasks.jar)
+    downgradeTo = JavaVersion.VERSION_17
+    inputFile = tasks.jar.get().archiveFile
+    archiveClassifier = "downgraded-17"
+}
+
 tasks.jar {
     isPreserveFileTimestamps = false
     isReproducibleFileOrder = true
 
     from(rootProject.file("LICENSE")) {
         rename { "${it}_${rootProject.name}" }
     }
-}
 
-val sourcesJar = tasks.register<Jar>("sourcesJar") {
-    group = "build"
-
-    archiveClassifier = "sources"
-    isPreserveFileTimestamps = false
-    isReproducibleFileOrder = true
+    finalizedBy(tasks.downgradeJar, downgradeJar17)
+}
 
+java.withSourcesJar()
+val sourcesJar: Jar = tasks.withType<Jar>()["sourcesJar"].apply {
     from(rootProject.file("LICENSE")) {
         rename { "${it}_${rootProject.name}" }
     }
-
-    from(sourceSets.main.get().allSource) { duplicatesStrategy = DuplicatesStrategy.EXCLUDE }
 }
 
 tasks.assemble {
@@ -133,10 +145,9 @@ tasks.withType<GenerateModuleMetadata> {
 
 tasks.withType<JavaCompile> {
     options.encoding = "UTF-8"
-    sourceCompatibility = "17"
-    options.release = 8
+    sourceCompatibility = "21"
     javaCompiler = javaToolchains.compilerFor {
-        languageVersion = JavaLanguageVersion.of(17)
+        languageVersion = JavaLanguageVersion.of(21)
     }
 }
 
@@ -145,7 +156,7 @@ githubRelease {
     setTagName(versionTagName)
     setTargetCommitish("master")
     setReleaseName(versionString)
-    setReleaseAssets(tasks.jar.get().archiveFile, sourcesJar.get().archiveFile)
+    setReleaseAssets(tasks.jar.get().archiveFile, sourcesJar.archiveFile)
 }
 
 tasks.githubRelease {
@@ -160,8 +171,10 @@ publishing {
 
     publications {
         create<MavenPublication>("project_name"()) {
-            artifact(tasks.jar)
-            artifact(sourcesJar)
+            artifact(tasks.jar) // java 21
+            artifact(downgradeJar17) // java 17
+            artifact(tasks.downgradeJar) // java 8
+            artifact(sourcesJar) // java 21 sources
         }
     }
 }

gradle.properties

@@ -6,7 +6,7 @@ org.gradle.caching = true
 org.gradle.configuration-cache = false
 
 maven_group = dev.nolij
-project_version = 0.1
+project_version = 0.2
 project_name = zson
 
 # Dependencies

settings.gradle.kts

@@ -5,13 +5,22 @@ pluginManagement {
                 excludeGroup("org.apache.logging.log4j")
             }
         }
+        maven("https://maven.wagyourtail.xyz/releases")
+        maven("https://maven.wagyourtail.xyz/snapshots")
+    }
+}
+
+buildscript {
+    dependencies {
+        classpath("org.apache.commons:commons-io:1.3.2")
     }
 }
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version("0.7.0")
     id("org.ajoberstar.grgit") version("5.2.2") apply(false)
     id("com.github.breadmoirai.github-release") version("2.4.1") apply(false)
+    id("xyz.wagyourtail.jvmdowngrader") version("0.3.0") apply(false)
 }
 
 rootProject.name = "zson"

src/main/java/dev/nolij/zson/Comment.java

@@ -0,0 +1,15 @@
+package dev.nolij.zson;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A comment to be associated with a field.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Comment {
+	String value();
+}

src/main/java/dev/nolij/zson/Exclude.java

@@ -0,0 +1,14 @@
+package dev.nolij.zson;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Exclude a field from being serialized or deserialized.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Exclude {
+}

src/main/java/dev/nolij/zson/Include.java

@@ -0,0 +1,15 @@
+package dev.nolij.zson;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Force a field to be included in serialization, even if it is private or static.
+ * If static, it will not be included for deserialization.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Include {
+}