Support of KDL 2.0

.github/workflows/build.yml

@@ -1,24 +1,24 @@
-# This workflow will build a Java project with Gradle
-# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-gradle
-
 name: Gradle CI
 
 on:
   push:
-    branches: [ trunk ]
+    branches:
+      - trunk
   pull_request:
-    branches: [ trunk ]
+    branches:
+      - trunk
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
-
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up JDK 1.8
-      uses: actions/setup-java@v1
-      with:
-        java-version: 1.8
-    - name: Build with Gradle
-      run: gradle build
+      - uses: actions/checkout@v4
+      - name: Set up JDK 11
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 11
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+      - name: Build with Gradle
+        run: ./gradlew build

.gitignore

@@ -1,7 +1,4 @@
-/gradlew.bat
-/gradlew
 /.idea/
 /.gradle/
-/gradle/
 /build/
-.DS_Store
+.DS_Store

.mailmap

@@ -0,0 +1 @@
+Hannah Kolbeck <[email protected]> <[email protected]>

LICENSE.md

@@ -1,4 +1,5 @@
 Copyright 2022 Hannah Kolbeck
+Copyright 2024 Romain Delamare
 
 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
@@ -12,4 +13,3 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 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.
-

README.md

@@ -1,67 +1,80 @@
-# KDL4j
+# KDL4j v2
 
-A Java implementation of a parser for the [KDL Document Language](https://github.com/kdl-org/kdl).
+A Java implementation of a parser for the [KDL Document Language](https://github.com/kdl-org/kdl). Supports KDL
+version `2.0.0-draft.4`.
 
-## Status
+This library targets Java 11 as a minimum version.
 
-![Gradle CI](https://github.com/hkolbeck/kdl4j/workflows/Gradle%20CI/badge.svg)
+## Status
 
-This project is beta-quality. It's been extensively tested, but the spec it implements is still in flux.
+![Gradle CI](https://github.com/kdl-org/kdl4j/workflows/Gradle%20CI/badge.svg)
 
 ## Usage
 
-### Parsing
+### Dependency
 
-```java
-final KDLParser parser = new KDLParser();
+Releases are published on [GitHub Packages](https://docs.github.com/en/packages). You need to authenticate with GitHub
+using a token with `read:packages` permission. See the official documentation for more information on how to
+authenticate on GitHub Packages for
+[Maven](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
+or for
+[Gradle](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry).
 
-final KDLDocument documentFromString = parser.parse("node_name \"arg\"")
-// OR
-final KDLDocument documentFromReader = parser.parse(new FileReader("some/file.kdl"))
-```
+Then you can add the KDL4j dependency. Maven:
 
-`KDLDocument` objects, and all descendants of `KDLObject`, are immutable and threadsafe, though that is not true of their 
-`Builder` objects. If you need to make changes to a `KDLDocument`, use the `filter()` and `mutate()` functions explained below.
+```xml
 
-### Searching and Mutating Documents
+<dependencies>
+    <dependency>
+        <groupId>kdl</groupId>
+        <artifactId>kdl4j</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+</dependencies>
+```
 
-Several utilities are provided for finding nodes in documents. Each presents the same interface, but the way they search
-the document differs. There are three search types:
+Gradle:
 
-* RootSearch - Searches entirely at the root, primarily used for mutations to the root as discussed below
-* GeneralSearch - Searches for nodes anywhere in the tree matching a single, possibly compound, node predicate
-* PathedSearch - Searches for nodes down a specified path. At each level a different node predicate can be specified
+```groovy
+dependencies {
+    implementation 'kdl:kdl4j:2.0.0'
+}
+```
 
-Each provides four methods for searching or mutating documents:
+Alternatively, you can use the packages [hosted by JitPack](https://jitpack.io/#kdl-org/kdl4j). In this case, make sure
+you use the `com.github.kdl-org` groupId.
 
-* `anyMatch(document)` - Returns true if any node matches the search, false otherwise
-* `filter(document, trim)` - Removes all nodes from the tree not on a branch that matches the predicates of the search. if
-  `trim` is set, removes all their non-matching children
-* `list(document, trim)` - Produces a new document with all matching nodes at the root. If `trim` is set, removes all
-  their non-matching children
-* `mutate(document, mutation)` - Applies a provided `Mutation` to every matching node in the tree, depth first.
+### Parsing
 
-There are 3 types of `Mutations` provided, and users may provide custom mutations. Provided are `AddMutation`, 
-`SubtractMutation`, and `SetMutation`. Each performs functions hinted at by the name. See individual javadocs for details.
+```java
+import kdl.parse.KDLParser;
+
+// Parse from a String
+var documentFromString = KDLParser.parse("node_name \"arg\"");
+// Parse from an InputStream
+var documentFromReader = KDLParser.parse(new ByteArrayInputStream(/* … */));
+// Parse from a file
+var documentFromReader = KDLParser.parse(Paths.get("path", "to", "file"));
+```
 
 ### Printing
 
-By default, calling `document.toKDL()` or `document.writeKDL(writer)` will print the structure with:
- 
-* 4 space indents
-* No semicolons
-* Printable ASCII characters which can be escaped, escaped
-* Empty children printed
-* `null` arguments and properties with `null` values printed
-* `\n` (unicode `\u{0a}`) for newlines
+The `KDLPrinter` class allows printing a KDL document to a `String`, a `Writer`, an `OutputStream` or to a file. By
+default, it:
+
+- prints one character tabulation for each indentation level
+- does not print node separators (`;`)
+- does not print braces for nodes without children
+- prints arguments and properties with null value
+- uses `E` as the exponent character in decimal values
 
-Any of these can be changed by creating a new PrintConfig object and passing it into the print method. See the javadocs
-on PrintConfig for more information.
+Any of these can be changed by creating a `PrintConfiguration` and passing it to the `KDLPrinter` constructor.
 
 ## Contributing
 
 Please read the Code of Conduct before opening any issues or pull requests.
 
-Besides code fixes, the easiest way to contribute is by generating test cases. Check out 
-[the test cases directory](https://github.com/hkolbeck/kdl4j/tree/trunk/src/test/resources/test_cases) to see the existing ones.
+Besides code fixes, the easiest way to contribute is by generating test cases. Check out
+[the test cases directory](src/test/resources/test_cases) to see the
+existing ones.
 See the README there for more details.

build.gradle.kts

@@ -1,27 +1,26 @@
 plugins {
-    java
+    `java-library`
     jacoco
     `maven-publish`
 }
 
-group = "dev.hbeck.kdl"
-version = "0.2.0"
+group = "kdl"
 
 repositories {
     mavenCentral()
 }
 
 publishing {
     publications {
-        create<MavenPublication>("default") {
+        create<MavenPublication>("maven") {
             from(components["java"])
         }
     }
 
     repositories {
         maven {
             name = "GitHubPackages"
-            url = uri("https://maven.pkg.github.com/hkolbeck/kdl4j")
+            url = uri("https://maven.pkg.github.com/kdl-org/kdl4j")
             credentials {
                 username = System.getenv("GITHUB_ACTOR")
                 password = System.getenv("GITHUB_TOKEN")
@@ -30,15 +29,41 @@ publishing {
     }
 }
 
+java {
+    withSourcesJar()
+
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(11)
+    }
+}
+
+tasks.compileJava {
+    options.javaModuleVersion = provider { version as String }
+}
+
+tasks.test {
+    useJUnitPlatform()
+    finalizedBy(tasks.jacocoTestReport)
+}
+
 tasks.jacocoTestReport {
+    dependsOn(tasks.test)
+
     reports {
-        xml.isEnabled = false
-        csv.isEnabled = false
-        html.destination = file("${buildDir}/jacoco/coverage")
+        xml.required = false
+        csv.required = false
+        html.outputLocation = layout.buildDirectory.dir("jacoco/coverage")
     }
 }
 
+val mockitoVersion = "5.10.0"
+
 dependencies {
-    testImplementation("junit", "junit", "4.12")
-    testImplementation("org.mockito", "mockito-core", "3.7.7")
+    implementation("jakarta.annotation:jakarta.annotation-api:2.1.1")
+
+    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+    testImplementation("org.assertj:assertj-core:3.25.3")
+    testImplementation("org.mockito:mockito-core:$mockitoVersion")
+    testImplementation("org.mockito:mockito-junit-jupiter:$mockitoVersion")
 }

gradle.properties

@@ -1,2 +1 @@
-group=dev.hbeck.kdl
-version=0.2.0
+version=2.0.0.beta-1

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists