mirror of https://github.com/kdl-org/kdl.git
final tweaks before release
This commit is contained in:
Kat Marchán
parent
da4e7d4dde
commit
8ad94ec40e
|
|
@ -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).
|
||||
|
|
|
|||
44
README.md
44
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
|
||||
|
|
|
|||
10
SPEC.md
10
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue