diff --git a/CHANGELOG.md b/CHANGELOG.md index f890e09..2f8a655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # KDL Changelog -## 2.0.0 (2024-12-16) +## 2.0.0 (2024-12-21) ### Grammar @@ -9,7 +9,7 @@ escape. * Single line comments (`//`) can now be immediately followed by a newline. * All literal whitespace following a `\` in a string is now discarded. -* Vertical tabs (`U+000B`) are now considered to be whitespace. +* Vertical tabs (`U+000B`) are now considered to be newlines. * The grammar syntax itself has been described, and some confusing definitions in the grammar have been fixed accordingly (mostly related to escaped characters). diff --git a/README.md b/README.md index 53e68ff..1bf1005 100644 --- a/README.md +++ b/README.md @@ -50,10 +50,13 @@ 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`. 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. +The current version of the KDL spec is +[KDL 2.0.0](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md). For legacy KDL, +please refer to the [KDL 1.0.0 +spec](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC_v1.md). All users are +encouraged to migrate. [Migration is forward-and-backward-compatible and +safe](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md#compatibility), and can +be automated. 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 @@ -109,7 +112,7 @@ of some examples of KDL in the wild (either v1, v2, or both): | Go | [kdl-go](https://github.com/sblinch/kdl-go) | ✅ | ✖️ | | | Haskell | [Hustle](https://github.com/fuzzypixelz/Hustle) | ✅ | ✖️ | | | Java | [kdl4j](https://github.com/hkolbeck/kdl4j) | ✅ | ✖️ | | -| JavaScript | [@bgotink/kdl](https://github.com/bgotink/kdl) | ✅* | ✅ | Format/comment-preserving parser | +| JavaScript | [@bgotink/kdl](https://github.com/bgotink/kdl) | ✅ | ✅ | Format/comment-preserving parser | | 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) | ✅ | ✖️ | | @@ -120,13 +123,11 @@ of some examples of KDL in the wild (either v1, v2, or both): | 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) | +| Rust | [kdl-rs](https://github.com/kdl-org/kdl-rs) | ✅ | ✅ | Format/comment-preserving parser | +| Rust | [knus](https://crates.io/crates/knus/) | ✅ | ✖️ | 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 There is a [compatibility test suite](tests/README.md) available for KDL @@ -140,9 +141,11 @@ entirety, but in the future, may be required to in order to be included here. * [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) +* [VS Code](https://marketplace.visualstudio.com/items?itemName=kdl-org.kdl&ssr=false#review-details)\* * [vim](https://github.com/imsnif/kdl.vim) +\* Supports KDL 2.0.0 + ## Overview ### Basics @@ -181,7 +184,7 @@ Nodes without children are terminated by a newline, a semicolon, or the end of a file stream: ```kdl -node1; node2; node3; +node1; node2; node3 ``` ### Values @@ -189,13 +192,13 @@ node1; node2; node3; KDL supports 4 data types: * Strings: `unquoted`, `"hello world"`, or `#"hello world"#` -* Numbers: `123.45` +* Numbers: `123.45`, `0xdeadbeef`, `#inf`, `#-inf`, `#nan` * Booleans: `#true` and `#false` * Null: `#null` #### Strings -It supports three different formats for string input: identifiers, quoted, and raw. +It supports three different formats for string input: unquoted, quoted, and raw. ```kdl node1 this-is-a-string @@ -248,10 +251,10 @@ other-raw ##"hello#"world"## #### Numbers -There are 4 ways to represent numbers in KDL. KDL does not prescribe any -representation for these numbers, and it's entirely up to individual -implementations whether to represent all numbers with a single type, or to -have different representations for different forms. +There are 4 ways to represent numbers in KDL, plus 3 float keywords. KDL does +not prescribe any representation for these numbers, and it's entirely up to +individual implementations whether to represent all numbers with a single type, +or to have different representations for different forms. KDL has regular decimal-radix numbers, with optional decimal part, as well as an optional exponent. @@ -269,6 +272,13 @@ my-octal 0o755 my-binary 0b10101101 ``` +If you're intending to represent IEEE 754 floats, there are three special +keywords you can use: + +```kdl +special-floats #inf #-inf #nan +``` + Finally, all numbers can have underscores to help readability: ```kdl diff --git a/SPEC.md b/SPEC.md index 9f7ace0..83e8dfa 100644 --- a/SPEC.md +++ b/SPEC.md @@ -3,7 +3,7 @@ This is the formal specification for KDL, including the intended data model and the grammar. -This document describes KDL version `2.0.0`. It was released on 2024-12-16. It +This document describes KDL version KDL 2.0.0. It was released on 2024-12-21. It is the latest stable version of the language, and will only be edited for minor copyedits or major errata. @@ -16,6 +16,10 @@ This means that it's safe to use a fallback parsing strategy in order to support both v1 and v2 simultaneously. For example, `node "foo"` is a valid node in both versions, and should be represented identically by parsers. +A version marker `/- kdl-version 2` (or `1`) _MAY_ be added to the beginning of +a KDL document, optionally preceded by the BOM, and parsers _MAY_ use that as a +hint as to which version to parse the document as. + ## Introduction KDL is a node-oriented document language. Its niche and purpose overlaps with @@ -828,10 +832,6 @@ They may be represented in Strings (but not Raw Strings) using [Unicode Escapes] * `U+FEFF`, aka Zero-width Non-breaking Space (ZWNBSP)/Byte Order Mark (BOM), except as the first code point in a document. -### Version marker - -A version marker `/- kdl-version 2` (or `1`) _MAY_ be added to the beginning of a KDL document, optionally preceded by the BOM, and parsers _MAY_ use that as a hint as to which version to parse the document as. - ## Full Grammar This is the full official grammar for KDL and should be considered diff --git a/SPEC_v1.md b/SPEC_v1.md index 60d83a3..22258bd 100644 --- a/SPEC_v1.md +++ b/SPEC_v1.md @@ -28,6 +28,10 @@ This means that it's safe to use a fallback parsing strategy in order to support both v1 and v2 simultaneously. For example, `node "foo"` is a valid node in both versions, and should be represented identically by parsers. +A version marker `/- kdl-version 1` (or `2`) _MAY_ be added to the beginning of +a KDL document, optionally preceded by the BOM, and parsers _MAY_ use that as a +hint as to which version to parse the document as. + ## Introduction KDL is a node-oriented document language. Its niche and purpose overlaps with