berkus
/
kdl
mirror of https://github.com/kdl-org/kdl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Release KDL 2.0.0

This commit is contained in:
Kat Marchán 2024-12-14 17:26:18 -08:00
parent 0e58f61b18
commit 5d6f755832
No known key found for this signature in database
GPG Key ID: AEB529C08A3C7E9E
3 changed files with 118 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
CHANGELOG.md
View File

@ -1,52 +1,6 @@
# KDL Changelog # KDL Changelog
## 2.0.0-draft.8 (2024-12-14) ## 2.0.0 (2024-12-16)
* 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)
### Grammar ### Grammar
@ -71,6 +25,7 @@
improvement. improvement.
* Raw strings no longer require an `r` prefix: they are now specified by using * 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 * Line continuations can be followed by an EOF now, instead of requiring a
newline (or comment). `node \<EOF>` is now a legal KDL document. newline (or comment). `node \<EOF>` is now a legal KDL document.
* `#` is no longer a legal identifier character. * `#` is no longer a legal identifier character.
@ -91,7 +46,7 @@
should be valid UTF-8 now, as was intended. should be valid UTF-8 now, as was intended.
* The last node in a child block no longer needs to be terminated with `;`, * 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: 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 * More places allow whitespace (node-spaces, specifically) now. With great
power comes great responsibility: power comes great responsibility:
* Inside `(foo)` annotations (so, `( foo )` would be legal (`( f oo )` would * Inside `(foo)` annotations (so, `( foo )` would be legal (`( f oo )` would
@ -123,6 +78,10 @@
### KQL ### 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 * There's now a _required_ descendant selector (`>>`), instead of using plain
spaces for that purpose. spaces for that purpose.
* The "any sibling" selector is now `++` instead of `~`, for consistency with * 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 * Multi- and single-line comments are now supported, as well as line
continuations with `\`. continuations with `\`.
* Map operators have been removed entirely. * 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.

95
README.md
View File

@ -1,16 +1,9 @@
# The KDL Document Language # 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 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 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, as a serialization format and a configuration language, much like JSON, YAML, or
or XML. It looks like this: XML. It looks like this:
```kdl ```kdl
package { 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 There's a living [specification](SPEC.md), as well as various
[implementations](#implementations). You can also check out the [FAQ](#faq) to [implementations](#implementations). You can also check out the [FAQ](#faq) to
answer all your burning questions! 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 In addition to a spec for KDL itself, there are specifications for [a KDL Query
Query Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema
Language](SCHEMA-SPEC.md) loosely based on JSON Schema. Language](SCHEMA-SPEC.md) loosely based on JSON Schema.
The language is based on [SDLang](https://sdlang.org), with a [number of The language is based on [SDLang](https://sdlang.org), with a [number of
modifications and clarifications on its syntax and behavior](#why-not-sdlang). 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 ## Design and Discussion
KDL 2.0 design is still in progress. Discussions and questions about the format KDL 2.0.0 has been finalized, and no further changes are expected. For questions
should happen over on the [discussions about KDL and discussions, please see the [discussions
page](https://github.com/kdl-org/kdl/discussions). Feel free to jump in and give page](https://github.com/kdl-org/kdl/discussions). For minor editorial fixes or
us your 2 cents! critical spec errata, please feel free to [file an
issue](https://github.com/kdl-org/kdl/issues).
## Used By ## Used By
@ -92,26 +92,39 @@ of some examples of KDL in the wild (either v1, v2, or both):
## Implementations ## 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) > [!INFO] There are two major versions of KDL. Different libraries may support one or the
* JavaScript: [kdljs](https://github.com/kdl-org/kdljs), [@virtualstate/kdl](https://github.com/virtualstate/kdl) (query only, JSX based) > other, or even provide a "hybrid" mode where both versions are attempted, since
* Ruby: [kdl-rb](https://github.com/danini-the-panini/kdl-rb) > there's no data ambiguity between v1 and v2 documents.
* Dart: [kdl-dart](https://github.com/danini-the-panini/kdl-dart)
* Java: [kdl4j](https://github.com/hkolbeck/kdl4j) | Language | Implementation | v1 | v2 | Notes |
* 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) | C | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | |
* Elixir: [kuddle](https://github.com/IceDragon200/kuddle) | C#/.NET | [Kadlet](https://github.com/oledfish/Kadlet) | ✅ | ✖️ | |
* XSLT: [xml2kdl](https://github.com/Devasta/XML2KDL) | C++ | [kdlpp](https://github.com/tjol/ckdl) | ✅ | ✅ | part of ckdl, requires C++20 |
* Haskell: [Hustle](https://github.com/fuzzypixelz/Hustle) | Common Lisp | [kdlcl](https://github.com/chee/kdlcl) | ✅ | ✖️ | |
* .NET: [Kadlet](https://github.com/oledfish/Kadlet) | Crystal | [kdl-cr](https://github.com/danini-the-panini/kdl-cr) | ✅ | ✖️ | |
* C: [ckdl](https://github.com/tjol/ckdl) | Dart | [kdl-dart](https://github.com/danini-the-panini/kdl-dart) | ✅ | ✖️ | |
* C++: [kdlpp](https://github.com/tjol/ckdl) (part of ckdl, requires C++20) | Elixir | [kuddle](https://github.com/IceDragon200/kuddle) | ✅ | ✅ | |
* OCaml: [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl) | Go | [gokdl](https://github.com/lunjon/gokdl) | ✅ | ✖️ | |
* Nim: [kdl-nim](https://github.com/Patitotective/kdl-nim) | Go | [kdl-go](https://github.com/sblinch/kdl-go) | ✅ | ✖️ | |
* Common Lisp: [kdlcl](https://github.com/chee/kdlcl) | Haskell | [Hustle](https://github.com/fuzzypixelz/Hustle) | ✅ | ✖️ | |
* Go: [gokdl](https://github.com/lunjon/gokdl), [kdl-go](https://github.com/sblinch/kdl-go) | Java | [kdl4j](https://github.com/hkolbeck/kdl4j) | ✅ | ✖️ | |
* Swift: [kdl-swift](https://github.com/danini-the-panini/kdl-swift) | JavaScript | [@virtualstate/kdl](https://github.com/virtualstate/kdl) | ✅ | ✖️ | query only, JSX based |
* Crystal: [kdl-cr](https://github.com/danini-the-panini/kdl-cr) | JavaScript | [kdljs](https://github.com/kdl-org/kdljs) | ✅ | ✖️ | |
* Lua: [kdlua](https://github.com/danini-the-panini/kdlua) | 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 ## Compatibility Test Suite
@ -123,11 +136,11 @@ entirety, but in the future, may be required to in order to be included here.
## Editor Support ## 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) * [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 ## Overview

11
SPEC.md
View File

@ -1,14 +1,15 @@
# KDL Spec # KDL Spec
This is the semi-formal specification for KDL, including the intended data This is the formal specification for KDL, including the intended data model and
model and the grammar. the grammar.
This document describes KDL version `2.0.0-draft.8`. It was released on This document describes KDL version `2.0.0`. It was released on 2024-12-16. It
2024-12-14. is the latest stable version of the language, and will only be edited for minor
copyedits or major errata.
## Compatibility ## 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 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. 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 This means that it's safe to use a fallback parsing strategy in order to support