diff --git a/CHANGELOG.md b/CHANGELOG.md index b6414c9..ce96591 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,52 +1,6 @@ # KDL Changelog -## 2.0.0-draft.8 (2024-12-14) - -* Some details have been clarified around the treatment of whitespace in - multiline strings. -* `raw-string` productions have been updated to be explicitly non-greedy and - "fallible". -* Some tests have been added, others adjusted, some removed, after a cleanup pass. - -## 2.0.0-draft.7 (2024-12-10) - -* `node-space` is now allowed as whitespace after a `slashdash`, meaning line - continuations will work now. -* One or two consecutive double-quotes are now allowed in the bodies of - multi-line quoted strings, without needing to be escaped. -* Grammar has been fixed to disallow raw strings like `#"""#`, which are now - properly treated as invalid multi-line raw strings (instead of the equivalent of - `"\""`). -* Test suite has been updated to include a `_fail` suffix in all test cases - which are expected to fail. -* A slew of additional slashdash and multi-line string compliance tests have - been added. Have fun. :) -* The organization of string types in the spec prose has been updated to a - hopefully more helpful structure. - - -## 2.0.0-draft.6 (2024-12-04) - -* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error. -* Fixed an issue with the `unicode_silly` test case. -* Some rewordings and clarification in the spec prose. -* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`. - - -## 2.0.0-draft.5 (2024-11-28) - -* Equals signs other than `=` are no longer supported in properties. -* 128-bit integer type annotations have been added to the list of "well-known" - type annotations. -* Multiline string escape rules have been tweaked significantly. -* `\s` is now a valid escape within a string, representing a space character. -* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more - clear and intuitive. This includes some changes relating to whitespace, - including comments and newlines, which are breaking changes. -* Various updates to test suite to reflect changes. - - -## 2.0.0 (Unreleased) +## 2.0.0 (2024-12-16) ### Grammar @@ -71,6 +25,7 @@ improvement. * Raw strings no longer require an `r` prefix: they are now specified by using `#""#`. +* Raw string productions are now explicitly non-greedy (and "fallible"). * Line continuations can be followed by an EOF now, instead of requiring a newline (or comment). `node \` is now a legal KDL document. * `#` is no longer a legal identifier character. @@ -91,7 +46,7 @@ should be valid UTF-8 now, as was intended. * The last node in a child block no longer needs to be terminated with `;`, even if the closing `}` is on the same line, so this is now a legal node: - `node {foo;bar;baz}` + `node{foo;bar;baz}` * More places allow whitespace (node-spaces, specifically) now. With great power comes great responsibility: * Inside `(foo)` annotations (so, `( foo )` would be legal (`( f oo )` would @@ -123,6 +78,10 @@ ### KQL +> [!INFO] Note: these are provided for convenience, but as of the 2.0.0 KDL spec release, +> KQL itself is not finalized and should be considered a separate specification, +> alongside the Schema spec and others. + * There's now a _required_ descendant selector (`>>`), instead of using plain spaces for that purpose. * The "any sibling" selector is now `++` instead of `~`, for consistency with @@ -131,3 +90,54 @@ * Multi- and single-line comments are now supported, as well as line continuations with `\`. * Map operators have been removed entirely. + +--- + +## 2.0.0 Draft Changelogs + +### 2.0.0-draft.8 (2024-12-14) + +* Some details have been clarified around the treatment of whitespace in + multiline strings. +* `raw-string` productions have been updated to be explicitly non-greedy and + "fallible". +* Some tests have been added, others adjusted, some removed, after a cleanup pass. + + +### 2.0.0-draft.7 (2024-12-10) + +* `node-space` is now allowed as whitespace after a `slashdash`, meaning line + continuations will work now. +* One or two consecutive double-quotes are now allowed in the bodies of + multi-line quoted strings, without needing to be escaped. +* Grammar has been fixed to disallow raw strings like `#"""#`, which are now + properly treated as invalid multi-line raw strings (instead of the equivalent of + `"\""`). +* Test suite has been updated to include a `_fail` suffix in all test cases + which are expected to fail. +* A slew of additional slashdash and multi-line string compliance tests have + been added. Have fun. :) +* The organization of string types in the spec prose has been updated to a + hopefully more helpful structure. + + +### 2.0.0-draft.6 (2024-12-04) + +* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error. +* Fixed an issue with the `unicode_silly` test case. +* Some rewordings and clarification in the spec prose. +* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`. + + +### 2.0.0-draft.5 (2024-11-28) + +* Equals signs other than `=` are no longer supported in properties. +* 128-bit integer type annotations have been added to the list of "well-known" + type annotations. +* Multiline string escape rules have been tweaked significantly. +* `\s` is now a valid escape within a string, representing a space character. +* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more + clear and intuitive. This includes some changes relating to whitespace, + including comments and newlines, which are breaking changes. +* Various updates to test suite to reflect changes. + diff --git a/README.md b/README.md index 561fa7c..61af959 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,9 @@ # The KDL Document Language -> [!WARNING] -> The main branch of this repository shows the latest v2.0.0 draft, which is a -> work in progress and not considered the "mainline" KDL yet. Most KDL -> implementations in the wild are based on the [v1.0.0 -> spec](https://github.com/kdl-org/kdl/tree/1.0.0) instead, so you may want to -> refer to that if you're using KDL today. - KDL is a small, pleasant document language with XML-like node semantics that looks like you're invoking a bunch of CLI commands! It's meant to be used both -as a serialization format and a configuration language, much like JSON, YAML, -or XML. It looks like this: +as a serialization format and a configuration language, much like JSON, YAML, or +XML. It looks like this: ```kdl package { @@ -51,27 +44,34 @@ package { } ``` +For more details, see the [overview below](#overview). + There's a living [specification](SPEC.md), as well as various [implementations](#implementations). You can also check out the [FAQ](#faq) to answer all your burning questions! -The current version of the KDL spec is `2.0.0-draft.8`. +The current version of the KDL spec is `2.0.0`. For legacy KDL, please refer to +the [KDL 1.0 spec](./SPEC_v1.md). All users are encouraged to migrate. +[Migration is forward-and-backward-compatible and +safe](./SPEC.md#compatibility), and can be automated. -In addition to a spec for KDL itself, there are also standard specs for [a KDL -Query Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema +In addition to a spec for KDL itself, there are specifications for [a KDL Query +Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema Language](SCHEMA-SPEC.md) loosely based on JSON Schema. The language is based on [SDLang](https://sdlang.org), with a [number of modifications and clarifications on its syntax and behavior](#why-not-sdlang). +We are grateful for their work as an inspiration to ours. -[Play with it in your browser!](https://kdl-play.danini.dev/) +[Play with it in your browser (currently v1 only)!](https://kdl-play.danini.dev/) ## Design and Discussion -KDL 2.0 design is still in progress. Discussions and questions about the format -should happen over on the [discussions -page](https://github.com/kdl-org/kdl/discussions). Feel free to jump in and give -us your 2 cents! +KDL 2.0.0 has been finalized, and no further changes are expected. For questions +about KDL and discussions, please see the [discussions +page](https://github.com/kdl-org/kdl/discussions). For minor editorial fixes or +critical spec errata, please feel free to [file an +issue](https://github.com/kdl-org/kdl/issues). ## Used By @@ -92,26 +92,39 @@ of some examples of KDL in the wild (either v1, v2, or both): ## Implementations -* Rust: [kdl-rs](https://github.com/kdl-org/kdl-rs), [knuffel](https://crates.io/crates/knuffel/) (latter includes derive macro), and [kaydle](https://github.com/Lucretiel/kaydle) (serde-based) -* JavaScript: [kdljs](https://github.com/kdl-org/kdljs), [@virtualstate/kdl](https://github.com/virtualstate/kdl) (query only, JSX based) -* Ruby: [kdl-rb](https://github.com/danini-the-panini/kdl-rb) -* Dart: [kdl-dart](https://github.com/danini-the-panini/kdl-dart) -* Java: [kdl4j](https://github.com/hkolbeck/kdl4j) -* PHP: [kdl-php](https://github.com/kdl-org/kdl-php) -* Python: [kdl-py](https://github.com/tabatkins/kdlpy), [cuddle](https://github.com/djmattyg007/python-cuddle), [ckdl](https://github.com/tjol/ckdl) -* Elixir: [kuddle](https://github.com/IceDragon200/kuddle) -* XSLT: [xml2kdl](https://github.com/Devasta/XML2KDL) -* Haskell: [Hustle](https://github.com/fuzzypixelz/Hustle) -* .NET: [Kadlet](https://github.com/oledfish/Kadlet) -* C: [ckdl](https://github.com/tjol/ckdl) -* C++: [kdlpp](https://github.com/tjol/ckdl) (part of ckdl, requires C++20) -* OCaml: [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl) -* Nim: [kdl-nim](https://github.com/Patitotective/kdl-nim) -* Common Lisp: [kdlcl](https://github.com/chee/kdlcl) -* Go: [gokdl](https://github.com/lunjon/gokdl), [kdl-go](https://github.com/sblinch/kdl-go) -* Swift: [kdl-swift](https://github.com/danini-the-panini/kdl-swift) -* Crystal: [kdl-cr](https://github.com/danini-the-panini/kdl-cr) -* Lua: [kdlua](https://github.com/danini-the-panini/kdlua) +> [!INFO] There are two major versions of KDL. Different libraries may support one or the +> other, or even provide a "hybrid" mode where both versions are attempted, since +> there's no data ambiguity between v1 and v2 documents. + +| Language | Implementation | v1 | v2 | Notes | +|---|---|---|---|---| +| C | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | | +| C#/.NET | [Kadlet](https://github.com/oledfish/Kadlet) | ✅ | ✖️ | | +| C++ | [kdlpp](https://github.com/tjol/ckdl) | ✅ | ✅ | part of ckdl, requires C++20 | +| Common Lisp | [kdlcl](https://github.com/chee/kdlcl) | ✅ | ✖️ | | +| Crystal | [kdl-cr](https://github.com/danini-the-panini/kdl-cr) | ✅ | ✖️ | | +| Dart | [kdl-dart](https://github.com/danini-the-panini/kdl-dart) | ✅ | ✖️ | | +| Elixir | [kuddle](https://github.com/IceDragon200/kuddle) | ✅ | ✅ | | +| Go | [gokdl](https://github.com/lunjon/gokdl) | ✅ | ✖️ | | +| Go | [kdl-go](https://github.com/sblinch/kdl-go) | ✅ | ✖️ | | +| Haskell | [Hustle](https://github.com/fuzzypixelz/Hustle) | ✅ | ✖️ | | +| Java | [kdl4j](https://github.com/hkolbeck/kdl4j) | ✅ | ✖️ | | +| JavaScript | [@virtualstate/kdl](https://github.com/virtualstate/kdl) | ✅ | ✖️ | query only, JSX based | +| JavaScript | [kdljs](https://github.com/kdl-org/kdljs) | ✅ | ✖️ | | +| Lua | [kdlua](https://github.com/danini-the-panini/kdlua) | ✅ | ✖️ | | +| Nim | [kdl-nim](https://github.com/Patitotective/kdl-nim) | ✅ | ✖️ | | +| OCaml | [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl) | ✅ | ✖️ | | +| PHP | [kdl-php](https://github.com/kdl-org/kdl-php) | ✅ | ✖️ | | +| Python | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | | +| Python | [cuddle](https://github.com/djmattyg007/python-cuddle) | ✅ | ✖️ | | +| Python | [kdl-py](https://github.com/tabatkins/kdlpy) | ✅ | ✅ | | +| Ruby | [kdl-rb](https://github.com/danini-the-panini/kdl-rb) | ✅ | ✖️ | | +| Rust | [kdl-rs](https://github.com/kdl-org/kdl-rs) | ✅* | ✅ | Format/comment-preserving parser | +| Rust | [knuffel](https://crates.io/crates/knuffel/) | ✅ | ✖️ | Serde-_style_ derive macros (not actual Serde) | +| Swift | [kdl-swift](https://github.com/danini-the-panini/kdl-swift) | ✅ | ✖️ | | +| XSLT | [xml2kdl](https://github.com/Devasta/XML2KDL) | ✅ | ✖️ | | + +\* Supported by earlier library version ## Compatibility Test Suite @@ -123,11 +136,11 @@ entirety, but in the future, may be required to in order to be included here. ## Editor Support -* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details) -* [Sublime Text](https://packagecontrol.io/packages/KDL) -* [vim](https://github.com/imsnif/kdl.vim) -* [neovim](https://github.com/tree-sitter-grammars/tree-sitter-kdl) * [Intellij IDEA](https://plugins.jetbrains.com/plugin/20136-kdl-document-language) +* [Sublime Text](https://packagecontrol.io/packages/KDL) +* [TreeSitter](https://github.com/tree-sitter-grammars/tree-sitter-kdl) (neovim, among others) +* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details) +* [vim](https://github.com/imsnif/kdl.vim) ## Overview diff --git a/SPEC.md b/SPEC.md index ba43cb5..005cfa3 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,14 +1,15 @@ # KDL Spec -This is the semi-formal specification for KDL, including the intended data -model and the grammar. +This is the formal specification for KDL, including the intended data model and +the grammar. -This document describes KDL version `2.0.0-draft.8`. It was released on -2024-12-14. +This document describes KDL version `2.0.0`. It was released on 2024-12-16. It +is the latest stable version of the language, and will only be edited for minor +copyedits or major errata. ## Compatibility -KDL v2 is designed such that for any given KDL document written as [KDL +KDL 2.0 is designed such that for any given KDL document written as [KDL 1.0](./SPEC_v1.md) or KDL 2.0, the parse will either fail completely, or, if the parse succeeds, the data represented by a v1 or v2 parser will be identical. This means that it's safe to use a fallback parsing strategy in order to support