feat: first version of the KDL 2.0 parser

Author: alightgoesout

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = tab
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml}]
+tab_width = 2

.github/workflows/build.yaml

@@ -0,0 +1,24 @@
+name: Gradle CI
+
+on:
+  push:
+    branches:
+      - trunk
+  pull_request:
+    branches:
+      - trunk
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+      - name: Build with Gradle
+        run: ./gradlew build

.github/workflows/build.yml

@@ -0,0 +1 @@
+temurin-17

.github/workflows/release.yaml

@@ -4,49 +4,73 @@
 
 If you see behavior that makes you feel unsafe or unwelcome or otherwise uncomfortable, follow these steps:
 
-1. Let the person know that what they did is not appropriate and ask them to stop and/or edit their message(s) or commits.
+1. Let the person know that what they did is not appropriate and ask them to stop and/or edit their message(s) or
+   commits.
 2. That person should immediately stop the behavior and correct the issue.
 3. If this doesn’t happen, or if you're uncomfortable speaking up, [contact the maintainers](#contacting-maintainers).
-4. As soon as available, a maintainer will look into the issue, and take [further action (see below)](#further-enforcement), starting with a warning, then temporary block, then long-term repo or organization ban.
+4. As soon as available, a maintainer will look into the issue, and
+   take [further action (see below)](#further-enforcement), starting with a warning, then temporary block, then
+   long-term repo or organization ban.
 
-**The maintainer team will prioritize the well-being and comfort of those affected over the comfort of the offending party.** See [some examples below](#enforcement-examples).
+**The maintainer team will prioritize the well-being and comfort of those affected over the comfort of the offending
+party.** See [some examples below](#enforcement-examples).
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers of this project pledge to making participation in our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, technical preferences, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers of this project
+pledge to making participation in our community a harassment-free experience for everyone, regardless of age, body size,
+disability, ethnicity, gender identity and expression, level of experience, technical preferences, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
 
-This commitment means that inappropriate behavior can lead to intervention. This includes our intention to address issues with [missing stairs](https://en.wikipedia.org/wiki/Missing_stair) who may not have explicitly violated any written-down rules but might still be disrupting the community.
+This commitment means that inappropriate behavior can lead to intervention. This includes our intention to address
+issues with [missing stairs](https://en.wikipedia.org/wiki/Missing_stair) who may not have explicitly violated any
+written-down rules but might still be disrupting the community.
 
 ## Scope
 
-This Code of Conduct applies both within spaces involving this project and in other spaces involving community members. This includes the repository, its Pull Requests and Issue tracker, its Twitter community, private email communications in the context of the project, and any events where members of the project are participating, as well as adjacent communities and venues affecting the project's members.
+This Code of Conduct applies both within spaces involving this project and in other spaces involving community members.
+This includes the repository, its Pull Requests and Issue tracker, its Twitter community, private email communications
+in the context of the project, and any events where members of the project are participating, as well as adjacent
+communities and venues affecting the project's members.
 
-Depending on the violation, the maintainers may decide that violations of this code of conduct that have happened outside of the scope of the community may deem an individual unwelcome, and take appropriate action to maintain the comfort and safety of its members.
+Depending on the violation, the maintainers may decide that violations of this code of conduct that have happened
+outside of the scope of the community may deem an individual unwelcome, and take appropriate action to maintain the
+comfort and safety of its members.
 
 ## Contacting Maintainers
 
 - [Hannah Kolbeck <[email protected]>](mailto:[email protected])
+- [Romain Delamare <[email protected]>](mailto:[email protected])
 
 ## Further Enforcement
 
-If you've already followed the [initial enforcement steps](#enforcement), these are the steps maintainers will take for further enforcement, as needed:
+If you've already followed the [initial enforcement steps](#enforcement), these are the steps maintainers will take for
+further enforcement, as needed:
 
 1. Repeat the request to stop.
-2. If the person doubles down, they will have offending messages removed or edited by a maintainers given an official warning. The PR or Issue may be locked.
+2. If the person doubles down, they will have offending messages removed or edited by a maintainers given an official
+   warning. The PR or Issue may be locked.
 3. If the behavior continues or is repeated later, the person will be blocked from participating for 24 hours.
 4. If the behavior continues or is repeated after the temporary block, a long-term (6-12mo) ban will be used.
 
 On top of this, maintainers may remove any offending messages, images, contributions, etc, as they deem necessary.
 
-Maintainers reserve full rights to skip any of these steps, at their discretion, if the violation is considered to be a serious and/or immediate threat to the health and well-being of members of the community. These include any threats, serious physical or verbal attacks, and other such behavior that would be completely unacceptable in any social setting that puts our members at risk.
+Maintainers reserve full rights to skip any of these steps, at their discretion, if the violation is considered to be a
+serious and/or immediate threat to the health and well-being of members of the community. These include any threats,
+serious physical or verbal attacks, and other such behavior that would be completely unacceptable in any social setting
+that puts our members at risk.
 
 Members expelled from events or venues with any sort of paid attendance will not be refunded.
 
 ## Who Watches the Watchers?
 
-Maintainers and other leaders who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. These may include anything from removal from the maintainer team to a permanent ban from the community.
+Maintainers and other leaders who do not follow or enforce the Code of Conduct in good faith may face temporary or
+permanent repercussions as determined by other members of the project's leadership. These may include anything from
+removal from the maintainer team to a permanent ban from the community.
 
-Additionally, as a project hosted on both GitHub, [their Community Guidielines may be applied to maintainers of this project](https://help.github.com/articles/github-community-guidelines/), externally of this project's procedures.
+Additionally, as a project hosted on both
+GitHub, [their Community Guidielines may be applied to maintainers of this project](https://help.github.com/articles/github-community-guidelines/),
+externally of this project's procedures.
 
 ## Enforcement Examples
 
@@ -62,25 +86,31 @@ The vast majority of situations work out like this. This interaction is common,
 
 ### The Maintainer Case
 
-Sometimes, though, you need to get maintainers involved. Maintainers will do their best to resolve conflicts, but people who were harmed by something **will take priority**.
+Sometimes, though, you need to get maintainers involved. Maintainers will do their best to resolve conflicts, but people
+who were harmed by something **will take priority**.
 
 > Patt: "Honestly, sometimes I just really hate using $library and anyone who uses it probably sucks at their job."
 
 > Alex: "Whoa there, could you dial it back a bit? There's a CoC thing about attacking folks' tech use like that."
 
 > Patt: "I'm not attacking anyone, what's your problem?"
 
-> Alex: "@maintainers hey uh. Can someone look at this issue? Patt is getting a bit aggro. I tried to nudge them about it, but nope."
+> Alex: "@maintainers hey uh. Can someone look at this issue? Patt is getting a bit aggro. I tried to nudge them about
+> it, but nope."
 
-> KeeperOfCommitBits: (on issue) "Hey Patt, maintainer here. Could you tone it down? This sort of attack is really not okay in this space."
+> KeeperOfCommitBits: (on issue) "Hey Patt, maintainer here. Could you tone it down? This sort of attack is really not
+> okay in this space."
 
 > Patt: "Leave me alone I haven't said anything bad wtf is wrong with you."
 
-> KeeperOfCommitBits: (deletes user's comment), "@patt I mean it. Please refer to the CoC over at (URL to this CoC) if you have questions, but you can consider this an actual warning. I'd appreciate it if you reworded your messages in this thread, since they made folks there uncomfortable. Let's try and be kind, yeah?"
+> KeeperOfCommitBits: (deletes user's comment), "@patt I mean it. Please refer to the CoC over at (URL to this CoC) if
+> you have questions, but you can consider this an actual warning. I'd appreciate it if you reworded your messages in this
+> thread, since they made folks there uncomfortable. Let's try and be kind, yeah?"
 
-> Patt: "@keeperofbits Okay sorry. I'm just frustrated and I'm kinda burnt out and I guess I got carried away. I'll DM Alex a note apologizing and edit my messages. Sorry for the trouble."
+> Patt: "@keeperofbits Okay sorry. I'm just frustrated and I'm kinda burnt out and I guess I got carried away. I'll DM
+> Alex a note apologizing and edit my messages. Sorry for the trouble."
 
-> KeeperOfCommitBits: "@patt Thanks for that. I hear you on the stress. Burnout sucks :/.  Have a good one!"
+> KeeperOfCommitBits: "@patt Thanks for that. I hear you on the stress. Burnout sucks :/. Have a good one!"
 
 ### The Nope Case
 
@@ -96,7 +126,8 @@ Sometimes, though, you need to get maintainers involved. Maintainers will do the
 
 ## Attribution
 
-This Code of Conduct was generated using [WeAllJS Code of Conduct Generator](https://npm.im/weallbehave), which is based on the [WeAllJS Code of
+This Code of Conduct was generated using [WeAllJS Code of Conduct Generator](https://npm.im/weallbehave), which is based
+on the [WeAllJS Code of
 Conduct](https://wealljs.org/code-of-conduct), which is itself based on
 [Contributor Covenant](http://contributor-covenant.org), version 1.4, available
 at

.java-version

@@ -1,4 +1,5 @@
 Copyright 2022 Hannah Kolbeck
+Copyright 2025 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.
-

CODE_OF_CONDUCT.md

@@ -1,67 +1,82 @@
-# 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`.
 
-## 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>dev.kdl</groupId>
+		<artifactId>kdl4j</artifactId>
+		<version>1.0.0-SNAPSHOT</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 'dev.kdl:kdl4j:1.0.0-SNAPSHOT'
+}
+```
 
-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 parse.dev.kdl.KDLParser;
+
+// Create a KDL 2 parser
+var parser = KdlParser.v2();
+// Parse from a String
+var documentFromString = parser.parse("filename", "node_name \"arg\"");
+// Parse from an InputStream
+var documentFromReader = parser.parse("filename", new ByteArrayInputStream(/* … */));
+// Parse from a file
+var documentFromReader = parser.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.