Skip to content

Commit 6ceecd8

Browse files
zkateilveliabgotinktjoleugenesvk
authored
Release KDL 2.0.0 (#434)
* Release KDL 2.0.0 * fix grammar for multiline quoted strings to allow escaped whitespace on closing line * Add unicode-space to raw string * Remove nonexistent equals-sign from the grammar (#435) * fix multiline string tests * grammar: fix disallowed-keyword-identifiers and string-character (#436) * Back out "fix multiline string tests" This backs out commit 0c5604b. * add extra javascript implementation (#437) * reword interaction multiline + whitespace escape (#439) * More tests for backslash behaviour (#438) * More tests for baskslash behaviour * Incorrect example of escaped final newline * Test with non-literal indent * Make line-space a superset of node-space (#440) * Allow escline everywhere * escline tests * Always escape \ inside single quotes in the grammar text (#441) to match the other uses of it and the metalanguage description below * Add tests for mandatory whitespace between arguments or properties (#442) * Add an optional version marker (#444) * Add version marker to the grammer * Add version marker to the Changelog * Update SPEC.md Co-authored-by: eilvelia <[email protected]> * add a mandatory newline after the version marker * add mandatory space between version number --------- Co-authored-by: eilvelia <[email protected]> * Fix a changelog line erroneously truncated in #444 (#445) * fix: move vertical tab to the line-breaking whitespace to match Unicode (#446) * add vertical tab change test * final tweaks before release --------- Co-authored-by: eilvelia <[email protected]> Co-authored-by: Bram Gotink <[email protected]> Co-authored-by: Thomas Jollans <[email protected]> Co-authored-by: Evgeny <[email protected]>
1 parent 0e58f61 commit 6ceecd8

39 files changed

+265
-132
lines changed

‎CHANGELOG.md

+60-49
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,6 @@
11
# KDL Changelog
22

3-
## 2.0.0-draft.8 (2024-12-14)
4-
5-
* Some details have been clarified around the treatment of whitespace in
6-
multiline strings.
7-
* `raw-string` productions have been updated to be explicitly non-greedy and
8-
"fallible".
9-
* Some tests have been added, others adjusted, some removed, after a cleanup pass.
10-
11-
## 2.0.0-draft.7 (2024-12-10)
12-
13-
* `node-space` is now allowed as whitespace after a `slashdash`, meaning line
14-
continuations will work now.
15-
* One or two consecutive double-quotes are now allowed in the bodies of
16-
multi-line quoted strings, without needing to be escaped.
17-
* Grammar has been fixed to disallow raw strings like `#"""#`, which are now
18-
properly treated as invalid multi-line raw strings (instead of the equivalent of
19-
`"\""`).
20-
* Test suite has been updated to include a `_fail` suffix in all test cases
21-
which are expected to fail.
22-
* A slew of additional slashdash and multi-line string compliance tests have
23-
been added. Have fun. :)
24-
* The organization of string types in the spec prose has been updated to a
25-
hopefully more helpful structure.
26-
27-
28-
## 2.0.0-draft.6 (2024-12-04)
29-
30-
* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error.
31-
* Fixed an issue with the `unicode_silly` test case.
32-
* Some rewordings and clarification in the spec prose.
33-
* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`.
34-
35-
36-
## 2.0.0-draft.5 (2024-11-28)
37-
38-
* Equals signs other than `=` are no longer supported in properties.
39-
* 128-bit integer type annotations have been added to the list of "well-known"
40-
type annotations.
41-
* Multiline string escape rules have been tweaked significantly.
42-
* `\s` is now a valid escape within a string, representing a space character.
43-
* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more
44-
clear and intuitive. This includes some changes relating to whitespace,
45-
including comments and newlines, which are breaking changes.
46-
* Various updates to test suite to reflect changes.
47-
48-
49-
## 2.0.0 (Unreleased)
3+
## 2.0.0 (2024-12-21)
504

515
### Grammar
526

@@ -55,7 +9,7 @@
559
escape.
5610
* Single line comments (`//`) can now be immediately followed by a newline.
5711
* All literal whitespace following a `\` in a string is now discarded.
58-
* Vertical tabs (`U+000B`) are now considered to be whitespace.
12+
* Vertical tabs (`U+000B`) are now considered to be newlines.
5913
* The grammar syntax itself has been described, and some confusing definitions
6014
in the grammar have been fixed accordingly (mostly related to escaped
6115
characters).
@@ -71,6 +25,7 @@
7125
improvement.
7226
* Raw strings no longer require an `r` prefix: they are now specified by using
7327
`#""#`.
28+
* Raw string productions are now explicitly non-greedy (and "fallible").
7429
* Line continuations can be followed by an EOF now, instead of requiring a
7530
newline (or comment). `node \<EOF>` is now a legal KDL document.
7631
* `#` is no longer a legal identifier character.
@@ -91,7 +46,7 @@
9146
should be valid UTF-8 now, as was intended.
9247
* The last node in a child block no longer needs to be terminated with `;`,
9348
even if the closing `}` is on the same line, so this is now a legal node:
94-
`node {foo;bar;baz}`
49+
`node{foo;bar;baz}`
9550
* More places allow whitespace (node-spaces, specifically) now. With great
9651
power comes great responsibility:
9752
* Inside `(foo)` annotations (so, `( foo )` would be legal (`( f oo )` would
@@ -120,9 +75,14 @@
12075
* Furthermore, The ordering of slashdashed elements has been restricted such
12176
that a slashdashed child block cannot go before an entry (including slashdashed
12277
entries).
78+
* Optional version marker `/- kdl-version 2` (or `1`) as the first line in a document, optionally preceded by the BOM.
12379

12480
### KQL
12581

82+
> [!INFO] Note: these are provided for convenience, but as of the 2.0.0 KDL spec release,
83+
> KQL itself is not finalized and should be considered a separate specification,
84+
> alongside the Schema spec and others.
85+
12686
* There's now a _required_ descendant selector (`>>`), instead of using plain
12787
spaces for that purpose.
12888
* The "any sibling" selector is now `++` instead of `~`, for consistency with
@@ -131,3 +91,54 @@
13191
* Multi- and single-line comments are now supported, as well as line
13292
continuations with `\`.
13393
* Map operators have been removed entirely.
94+
95+
---
96+
97+
## 2.0.0 Draft Changelogs
98+
99+
### 2.0.0-draft.8 (2024-12-14)
100+
101+
* Some details have been clarified around the treatment of whitespace in
102+
multiline strings.
103+
* `raw-string` productions have been updated to be explicitly non-greedy and
104+
"fallible".
105+
* Some tests have been added, others adjusted, some removed, after a cleanup pass.
106+
107+
108+
### 2.0.0-draft.7 (2024-12-10)
109+
110+
* `node-space` is now allowed as whitespace after a `slashdash`, meaning line
111+
continuations will work now.
112+
* One or two consecutive double-quotes are now allowed in the bodies of
113+
multi-line quoted strings, without needing to be escaped.
114+
* Grammar has been fixed to disallow raw strings like `#"""#`, which are now
115+
properly treated as invalid multi-line raw strings (instead of the equivalent of
116+
`"\""`).
117+
* Test suite has been updated to include a `_fail` suffix in all test cases
118+
which are expected to fail.
119+
* A slew of additional slashdash and multi-line string compliance tests have
120+
been added. Have fun. :)
121+
* The organization of string types in the spec prose has been updated to a
122+
hopefully more helpful structure.
123+
124+
125+
### 2.0.0-draft.6 (2024-12-04)
126+
127+
* Multiline strings, both Raw and Quoted, must now use `"""` instead of a single `"`. Using `"""` for a single-line string is a syntax error.
128+
* Fixed an issue with the `unicode_silly` test case.
129+
* Some rewordings and clarification in the spec prose.
130+
* Slight grammar tweak where the pre-terminator `node-space*` for `node` and `final-node` have been moved into `base-node`.
131+
132+
133+
### 2.0.0-draft.5 (2024-11-28)
134+
135+
* Equals signs other than `=` are no longer supported in properties.
136+
* 128-bit integer type annotations have been added to the list of "well-known"
137+
type annotations.
138+
* Multiline string escape rules have been tweaked significantly.
139+
* `\s` is now a valid escape within a string, representing a space character.
140+
* Slashdash (`/-`)-compatible locations and related grammar adjusted to be more
141+
clear and intuitive. This includes some changes relating to whitespace,
142+
including comments and newlines, which are breaking changes.
143+
* Various updates to test suite to reflect changes.
144+

‎README.md

+71-47
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,9 @@
11
# The KDL Document Language
22

3-
> [!WARNING]
4-
> The main branch of this repository shows the latest v2.0.0 draft, which is a
5-
> work in progress and not considered the "mainline" KDL yet. Most KDL
6-
> implementations in the wild are based on the [v1.0.0
7-
> spec](https://github.com/kdl-org/kdl/tree/1.0.0) instead, so you may want to
8-
> refer to that if you're using KDL today.
9-
103
KDL is a small, pleasant document language with XML-like node semantics that
114
looks like you're invoking a bunch of CLI commands! It's meant to be used both
12-
as a serialization format and a configuration language, much like JSON, YAML,
13-
or XML. It looks like this:
5+
as a serialization format and a configuration language, much like JSON, YAML, or
6+
XML. It looks like this:
147

158
```kdl
169
package {
@@ -51,27 +44,37 @@ package {
5144
}
5245
```
5346

47+
For more details, see the [overview below](#overview).
48+
5449
There's a living [specification](SPEC.md), as well as various
5550
[implementations](#implementations). You can also check out the [FAQ](#faq) to
5651
answer all your burning questions!
5752

58-
The current version of the KDL spec is `2.0.0-draft.8`.
53+
The current version of the KDL spec is
54+
[KDL 2.0.0](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md). For legacy KDL,
55+
please refer to the [KDL 1.0.0
56+
spec](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC_v1.md). All users are
57+
encouraged to migrate. [Migration is forward-and-backward-compatible and
58+
safe](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md#compatibility), and can
59+
be automated.
5960

60-
In addition to a spec for KDL itself, there are also standard specs for [a KDL
61-
Query Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema
61+
In addition to a spec for KDL itself, there are specifications for [a KDL Query
62+
Language](QUERY-SPEC.md) based on CSS selectors, and [a KDL Schema
6263
Language](SCHEMA-SPEC.md) loosely based on JSON Schema.
6364

6465
The language is based on [SDLang](https://sdlang.org), with a [number of
6566
modifications and clarifications on its syntax and behavior](#why-not-sdlang).
67+
We are grateful for their work as an inspiration to ours.
6668

67-
[Play with it in your browser!](https://kdl-play.danini.dev/)
69+
[Play with it in your browser (currently v1 only)!](https://kdl-play.danini.dev/)
6870

6971
## Design and Discussion
7072

71-
KDL 2.0 design is still in progress. Discussions and questions about the format
72-
should happen over on the [discussions
73-
page](https://github.com/kdl-org/kdl/discussions). Feel free to jump in and give
74-
us your 2 cents!
73+
KDL 2.0.0 has been finalized, and no further changes are expected. For questions
74+
about KDL and discussions, please see the [discussions
75+
page](https://github.com/kdl-org/kdl/discussions). For minor editorial fixes or
76+
critical spec errata, please feel free to [file an
77+
issue](https://github.com/kdl-org/kdl/issues).
7578

7679
## Used By
7780

@@ -92,26 +95,38 @@ of some examples of KDL in the wild (either v1, v2, or both):
9295

9396
## Implementations
9497

95-
* 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)
96-
* JavaScript: [kdljs](https://github.com/kdl-org/kdljs), [@virtualstate/kdl](https://github.com/virtualstate/kdl) (query only, JSX based)
97-
* Ruby: [kdl-rb](https://github.com/danini-the-panini/kdl-rb)
98-
* Dart: [kdl-dart](https://github.com/danini-the-panini/kdl-dart)
99-
* Java: [kdl4j](https://github.com/hkolbeck/kdl4j)
100-
* PHP: [kdl-php](https://github.com/kdl-org/kdl-php)
101-
* Python: [kdl-py](https://github.com/tabatkins/kdlpy), [cuddle](https://github.com/djmattyg007/python-cuddle), [ckdl](https://github.com/tjol/ckdl)
102-
* Elixir: [kuddle](https://github.com/IceDragon200/kuddle)
103-
* XSLT: [xml2kdl](https://github.com/Devasta/XML2KDL)
104-
* Haskell: [Hustle](https://github.com/fuzzypixelz/Hustle)
105-
* .NET: [Kadlet](https://github.com/oledfish/Kadlet)
106-
* C: [ckdl](https://github.com/tjol/ckdl)
107-
* C++: [kdlpp](https://github.com/tjol/ckdl) (part of ckdl, requires C++20)
108-
* OCaml: [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl)
109-
* Nim: [kdl-nim](https://github.com/Patitotective/kdl-nim)
110-
* Common Lisp: [kdlcl](https://github.com/chee/kdlcl)
111-
* Go: [gokdl](https://github.com/lunjon/gokdl), [kdl-go](https://github.com/sblinch/kdl-go)
112-
* Swift: [kdl-swift](https://github.com/danini-the-panini/kdl-swift)
113-
* Crystal: [kdl-cr](https://github.com/danini-the-panini/kdl-cr)
114-
* Lua: [kdlua](https://github.com/danini-the-panini/kdlua)
98+
> [!INFO] There are two major versions of KDL. Different libraries may support one or the
99+
> other, or even provide a "hybrid" mode where both versions are attempted, since
100+
> there's no data ambiguity between v1 and v2 documents.
101+
102+
| Language | Implementation | v1 | v2 | Notes |
103+
|---|---|---|---|---|
104+
| C | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | |
105+
| C#/.NET | [Kadlet](https://github.com/oledfish/Kadlet) | ✅ | ✖️ | |
106+
| C++ | [kdlpp](https://github.com/tjol/ckdl) | ✅ | ✅ | part of ckdl, requires C++20 |
107+
| Common Lisp | [kdlcl](https://github.com/chee/kdlcl) | ✅ | ✖️ | |
108+
| Crystal | [kdl-cr](https://github.com/danini-the-panini/kdl-cr) | ✅ | ✖️ | |
109+
| Dart | [kdl-dart](https://github.com/danini-the-panini/kdl-dart) | ✅ | ✖️ | |
110+
| Elixir | [kuddle](https://github.com/IceDragon200/kuddle) | ✅ | ✅ | |
111+
| Go | [gokdl](https://github.com/lunjon/gokdl) | ✅ | ✖️ | |
112+
| Go | [kdl-go](https://github.com/sblinch/kdl-go) | ✅ | ✖️ | |
113+
| Haskell | [Hustle](https://github.com/fuzzypixelz/Hustle) | ✅ | ✖️ | |
114+
| Java | [kdl4j](https://github.com/hkolbeck/kdl4j) | ✅ | ✖️ | |
115+
| JavaScript | [@bgotink/kdl](https://github.com/bgotink/kdl) | ✅ | ✅ | Format/comment-preserving parser |
116+
| JavaScript | [@virtualstate/kdl](https://github.com/virtualstate/kdl) | ✅ | ✖️ | query only, JSX based |
117+
| JavaScript | [kdljs](https://github.com/kdl-org/kdljs) | ✅ | ✖️ | |
118+
| Lua | [kdlua](https://github.com/danini-the-panini/kdlua) | ✅ | ✖️ | |
119+
| Nim | [kdl-nim](https://github.com/Patitotective/kdl-nim) | ✅ | ✖️ | |
120+
| OCaml | [ocaml-kdl](https://github.com/Bannerets/ocaml-kdl) | ✅ | ✖️ | |
121+
| PHP | [kdl-php](https://github.com/kdl-org/kdl-php) | ✅ | ✖️ | |
122+
| Python | [ckdl](https://github.com/tjol/ckdl) | ✅ | ✅ | |
123+
| Python | [cuddle](https://github.com/djmattyg007/python-cuddle) | ✅ | ✖️ | |
124+
| Python | [kdl-py](https://github.com/tabatkins/kdlpy) | ✅ | ✅ | |
125+
| Ruby | [kdl-rb](https://github.com/danini-the-panini/kdl-rb) | ✅ | ✖️ | |
126+
| Rust | [kdl-rs](https://github.com/kdl-org/kdl-rs) | ✅ | ✅ | Format/comment-preserving parser |
127+
| Rust | [knus](https://crates.io/crates/knus/) | ✅ | ✖️ | Serde-_style_ derive macros (not actual Serde) |
128+
| Swift | [kdl-swift](https://github.com/danini-the-panini/kdl-swift) | ✅ | ✖️ | |
129+
| XSLT | [xml2kdl](https://github.com/Devasta/XML2KDL) | ✅ | ✖️ | |
115130

116131
## Compatibility Test Suite
117132

@@ -123,11 +138,13 @@ entirety, but in the future, may be required to in order to be included here.
123138

124139
## Editor Support
125140

126-
* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details)
141+
* [Intellij IDEA](https://plugins.jetbrains.com/plugin/20136-kdl-document-language)
127142
* [Sublime Text](https://packagecontrol.io/packages/KDL)
143+
* [TreeSitter](https://github.com/tree-sitter-grammars/tree-sitter-kdl) (neovim, among others)
144+
* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details)\*
128145
* [vim](https://github.com/imsnif/kdl.vim)
129-
* [neovim](https://github.com/tree-sitter-grammars/tree-sitter-kdl)
130-
* [Intellij IDEA](https://plugins.jetbrains.com/plugin/20136-kdl-document-language)
146+
147+
\* Supports KDL 2.0.0
131148

132149
## Overview
133150

@@ -167,21 +184,21 @@ Nodes without children are terminated by a newline, a semicolon, or the end of
167184
a file stream:
168185

169186
```kdl
170-
node1; node2; node3;
187+
node1; node2; node3
171188
```
172189

173190
### Values
174191

175192
KDL supports 4 data types:
176193

177194
* Strings: `unquoted`, `"hello world"`, or `#"hello world"#`
178-
* Numbers: `123.45`
195+
* Numbers: `123.45`, `0xdeadbeef`, `#inf`, `#-inf`, `#nan`
179196
* Booleans: `#true` and `#false`
180197
* Null: `#null`
181198

182199
#### Strings
183200

184-
It supports three different formats for string input: identifiers, quoted, and raw.
201+
It supports three different formats for string input: unquoted, quoted, and raw.
185202

186203
```kdl
187204
node1 this-is-a-string
@@ -234,10 +251,10 @@ other-raw ##"hello#"world"##
234251

235252
#### Numbers
236253

237-
There are 4 ways to represent numbers in KDL. KDL does not prescribe any
238-
representation for these numbers, and it's entirely up to individual
239-
implementations whether to represent all numbers with a single type, or to
240-
have different representations for different forms.
254+
There are 4 ways to represent numbers in KDL, plus 3 float keywords. KDL does
255+
not prescribe any representation for these numbers, and it's entirely up to
256+
individual implementations whether to represent all numbers with a single type,
257+
or to have different representations for different forms.
241258

242259
KDL has regular decimal-radix numbers, with optional decimal part, as well as
243260
an optional exponent.
@@ -255,6 +272,13 @@ my-octal 0o755
255272
my-binary 0b10101101
256273
```
257274

275+
If you're intending to represent IEEE 754 floats, there are three special
276+
keywords you can use:
277+
278+
```kdl
279+
special-floats #inf #-inf #nan
280+
```
281+
258282
Finally, all numbers can have underscores to help readability:
259283

260284
```kdl

0 commit comments

Comments
 (0)