Skip to content

2.0.0

Latest
Latest
Compare
Choose a tag to compare
@zkat zkat released this 22 Dec 02:59
· 7 commits to main since this release
2.0.0
This tag was signed with the committer’s verified signature.
zkat Kat Marchán
GPG key ID: AEB529C08A3C7E9E
Learn about vigilant mode.
6ceecd8
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

It's finally here! KDL 2.0.0 is a major overhaul of the language. It keeps to the spirit of 1.0.0 but addresses a lot of tiny sharp corners, and adds a few exciting new features to make the language overall more ergonomic, easier to manage, and more pleasant on the eyes. It is the culmination of over 3 years of work by scores of contributors, implementers, and community members. It draws from years of experience with KDL 1.0.0 in the wild.

KDL 2.0.0 documents are unambiguous with KDL 1.0.0 documents: if a document happens to parse with either parser, the data is guaranteed to be the exact same.

For up-to-date information on what parsers support which versions of the language, please refer to the implementations table in the README.

Grammar

  • Solidus/Forward slash (/) is no longer an escaped character.
  • Space (U+0020) can now be written into quoted strings with the \s
    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 newlines.
  • The grammar syntax itself has been described, and some confusing definitions
    in the grammar have been fixed accordingly (mostly related to escaped
    characters).
  • ,, <, and > are now legal identifier characters. They were previously
    reserved for KQL but this is no longer necessary.
  • Code points under 0x20 (except newline and whitespace code points), code
    points above 0x10FFFF, Delete control character (0x7F), and the unicode
    "direction control"
    characters
    are now completely banned from appearing literally in KDL documents. They
    can now only be represented in regular strings, and there's no facilities to
    represent them in raw strings. This should be considered a security
    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 \<EOF> is now a legal KDL document.
  • # is no longer a legal identifier character.
  • null, true, and false are now #null, #true, and #false. Using
    the unprefixed versions of these values is a syntax error.
  • The spec prose has more explicitly stated that whitespace and newlines are
    not valid identifier characters, even though the grammar already expressed
    this.
  • Bare identifiers can now be used as values in Arguments and Properties, and are interpreted as string values.
  • The spec prose now more explicitly states that strings and raw strings can
    be used as type annotations.
  • Removed a statement in the spec prose that said "It is reasonable for an
    implementation to ignore null values altogether when deserializing". This is
    no longer encouraged or desired.
  • Code points have been constrained to Unicode Scalar
    Values     only, including
    values used in string escapes (\u{}). All KDL documents and string values
    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}
  • 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
      not be, since it has two identifiers))
    • Between annotations and the thing they're annotating ((blah) node (thing) 1 y= (who) 2)
    • Around = for props (x = 1)
  • The BOM is now only allowed as the first character in a document. It was
    previously treated as generic whitespace.
  • Multi-line strings must now use """ as delimeters. The opening delimiter must be immediately followed by a newline, and the closing delimiter must be on its own line, prefixed by optional whitespace.
  • Multi-line strings are now automatically dedented, according to the common
    whitespace matching the whitespace prefix of the closing line.
  • .1, +.1 etc are no longer valid identifiers, to prevent confusion and
    conflicts with numbers.
  • Multi-line strings' literal Newline sequences are now normalized to single
    LFs.
  • #inf, #-inf, and #nan have been added in order to properly support
    IEEE floats for implementations that choose to represent their decimals that
    way.
  • Correspondingly, the identifiers inf, -inf, and nan are now syntax
    errors.
  • u128 and i128 have been added as well-known number type annotations.
  • Slashdash (/-) -compatible locations adjusted to be more clear and
    intuitive. They can now be used in exactly three different places: before nodes,
    before entire entries, or before entire child blocks.
  • Furthermore, The ordering of slashdashed elements has been restricted such
    that a slashdashed child block cannot go before an entry (including slashdashed
    entries).
  • Optional version marker /- kdl-version 2 (or 1) as the first line in a document, optionally preceded by the BOM.

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
    the new descendant selector.
  • Some parsing logic around the grammar has changed.
  • Multi- and single-line comments are now supported, as well as line
    continuations with \.
  • Map operators have been removed entirely.

New Contributors

Full Changelog: 1.0.0...2.0.0

Contributors

danderson, swift2plunder, and 30 other contributors
Assets 2
Loading
0 Join discussion