index.html

@@ -110,7 +110,6 @@ of some examples of KDL in the wild (either v1, v2, or both):</p>
 <li><a href="https://github.com/camping/camping">Camping</a> - Ruby web microframework</li>
 <li><a href="https://ironvault.quest">Iron Vault</a> - VTT (Virtual Tabletop) plugin for Obsidian for the Ironsworn family of games</li>
 <li><a href="https://github.com/microsoft/TypeScript-DOM-lib-generator">Microsoft TypeScript DOM Generator</a> - Tool for generating DOM-related TypeScript and JavaScript library files</li>
-<li><a href="https://ferron.sh/">Ferron</a> - A fast, memory-safe web server written in Rust</li>
 <li>You?</li>
 </ul>
 </section>
@@ -118,12 +117,7 @@ of some examples of KDL in the wild (either v1, v2, or both):</p>
 <h2>Implementations</h2>
 <ul>
 <li>C - <a href="https://github.com/tjol/ckdl">ckdl</a>*</li>
-<li>C#/.NET -
+<li>C#/.NET - <a href="https://github.com/oledfish/Kadlet">Kadlet</a></li>
-<ul>
-<li><a href="https://github.com/oledfish/Kadlet">Kadlet</a> (v1)</li>
-<li><a href="https://github.com/AndreyAkinshin/KdlSharp">KdlSharp</a> (v2)</li>
-</ul>
-</li>
 <li>C++ - <a href="https://github.com/tjol/ckdl">kdlpp</a>* (part of ckdl, requires C++20)</li>
 <li>Common Lisp - <a href="https://github.com/chee/kdlcl">kdlcl</a></li>
 <li>Crystal - <a href="https://github.com/danini-the-panini/kdl-cr">kdl-cr</a></li>
@@ -169,7 +163,6 @@ of some examples of KDL in the wild (either v1, v2, or both):</p>
 </li>
 <li>Swift - <a href="https://github.com/danini-the-panini/kdl-swift">kdl-swift</a></li>
 <li>XSLT - <a href="https://github.com/Devasta/XML2KDL">xml2kdl</a></li>
-<li>Zig - <a href="https://codeberg.org/desttinghim/zig-kdl">zig-kdl</a></li>
 </ul>
 <p>* Supports both KDL v1 and v2</p>
 </section>

spec.txt

@@ -5,7 +5,7 @@
 KDL Community                                                 K. Marchán
                                                                Microsoft
                                                         KDL Contributors
-                                                         26 January 2026
+                                                         19 January 2025
 
 
                        The KDL Document Language
@@ -45,53 +45,74 @@ License
 
 Table of Contents
 
-   1.  Compatibility
+   1.  Compatibility . . . . . . . . . . . . . . . . . . . . . . . .   3
-   2.  Introduction
+   2.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
-   3.  Components
+   3.  Components  . . . . . . . . . . . . . . . . . . . . . . . . .   3
-     3.1.  Document
+     3.1.  Document  . . . . . . . . . . . . . . . . . . . . . . . .   3
-       3.1.1.  Example
+
-     3.2.  Node
+
-       3.2.1.  Example
+
-     3.3.  Line Continuation
+
-       3.3.1.  Example
+Marchán & KDL Contributors    Experimental                      [Page 1]
-     3.4.  Property
+
-     3.5.  Argument
+                                   KDL                      January 2025
-       3.5.1.  Example
+
-     3.6.  Children Block
+
-       3.6.1.  Example
+       3.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   4
-     3.7.  Value
+     3.2.  Node  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
-     3.8.  Type Annotation
+       3.2.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   5
-       3.8.1.  Reserved Type Annotations for Numbers Without Decimals:
+     3.3.  Line Continuation . . . . . . . . . . . . . . . . . . . .   5
-       3.8.2.  Reserved Type Annotations for Numbers With Decimals:
+       3.3.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   5
-       3.8.3.  Reserved Type Annotations for Strings:
+     3.4.  Property  . . . . . . . . . . . . . . . . . . . . . . . .   5
-       3.8.4.  Examples
+     3.5.  Argument  . . . . . . . . . . . . . . . . . . . . . . . .   6
-     3.9.  String
+       3.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   6
-     3.10. Identifier String
+     3.6.  Children Block  . . . . . . . . . . . . . . . . . . . . .   6
-       3.10.1.  Non-initial characters
+       3.6.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   6
-       3.10.2.  Non-identifier characters
+     3.7.  Value . . . . . . . . . . . . . . . . . . . . . . . . . .   6
-     3.11. Quoted String
+     3.8.  Type Annotation . . . . . . . . . . . . . . . . . . . . .   7
-       3.11.1.  Escapes
+       3.8.1.  Reserved Type Annotations for Numbers Without
-     3.12. Multi-line String
+               Decimals: . . . . . . . . . . . . . . . . . . . . . .   7
-       3.12.1.  Newline Normalization
+       3.8.2.  Reserved Type Annotations for Numbers With
-       3.12.2.  Examples
+               Decimals: . . . . . . . . . . . . . . . . . . . . . .   8
-       3.12.3.  Interaction with Whitespace Escapes
+       3.8.3.  Reserved Type Annotations for Strings:  . . . . . . .   8
-     3.13. Raw String
+       3.8.4.  Examples  . . . . . . . . . . . . . . . . . . . . . .   9
-       3.13.1.  Example
+     3.9.  String  . . . . . . . . . . . . . . . . . . . . . . . . .   9
-     3.14. Number
+     3.10. Identifier String . . . . . . . . . . . . . . . . . . . .  10
-       3.14.1.  Keyword Numbers
+       3.10.1.  Non-initial characters . . . . . . . . . . . . . . .  10
-     3.15. Boolean
+       3.10.2.  Non-identifier characters  . . . . . . . . . . . . .  11
-       3.15.1.  Example
+     3.11. Quoted String . . . . . . . . . . . . . . . . . . . . . .  11
-     3.16. Null
+       3.11.1.  Escapes  . . . . . . . . . . . . . . . . . . . . . .  11
-       3.16.1.  Example
+     3.12. Multi-line String . . . . . . . . . . . . . . . . . . . .  13
-     3.17. Whitespace
+       3.12.1.  Newline Normalization  . . . . . . . . . . . . . . .  14
-       3.17.1.  Single-line comments
+       3.12.2.  Examples . . . . . . . . . . . . . . . . . . . . . .  14
-       3.17.2.  Multi-line comments
+       3.12.3.  Interaction with Whitespace Escapes  . . . . . . . .  16
-       3.17.3.  Slashdash comments
+     3.13. Raw String  . . . . . . . . . . . . . . . . . . . . . . .  17
-     3.18. Newline
+       3.13.1.  Example  . . . . . . . . . . . . . . . . . . . . . .  17
-     3.19. Disallowed Literal Code Points
+     3.14. Number  . . . . . . . . . . . . . . . . . . . . . . . . .  18
-   4.  Full Grammar
+       3.14.1.  Keyword Numbers  . . . . . . . . . . . . . . . . . .  19
-     4.1.  Grammar language
+     3.15. Boolean . . . . . . . . . . . . . . . . . . . . . . . . .  19
-   Authors' Addresses
+       3.15.1.  Example  . . . . . . . . . . . . . . . . . . . . . .  19
+     3.16. Null  . . . . . . . . . . . . . . . . . . . . . . . . . .  20
+       3.16.1.  Example  . . . . . . . . . . . . . . . . . . . . . .  20
+     3.17. Whitespace  . . . . . . . . . . . . . . . . . . . . . . .  20
+       3.17.1.  Single-line comments . . . . . . . . . . . . . . . .  21
+       3.17.2.  Multi-line comments  . . . . . . . . . . . . . . . .  22
+       3.17.3.  Slashdash comments . . . . . . . . . . . . . . . . .  22
+     3.18. Newline . . . . . . . . . . . . . . . . . . . . . . . . .  22
+     3.19. Disallowed Literal Code Points  . . . . . . . . . . . . .  23
+   4.  Full Grammar  . . . . . . . . . . . . . . . . . . . . . . . .  24
+     4.1.  Grammar language  . . . . . . . . . . . . . . . . . . . .  26
+   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  27
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                      [Page 2]
+
+                                   KDL                      January 2025
+
 
 1.  Compatibility
 
@@ -134,12 +155,21 @@ Table of Contents
 3.1.  Document
 
    The toplevel concept of KDL is a Document.  A Document is composed of
-   zero or more Nodes (Section 3.2), separated by newlines, semicolons,
+   zero or more Nodes (Section 3.2), separated by newlines and
-   and whitespace, and eventually terminated by an EOF.
+   whitespace, and eventually terminated by an EOF.
 
-   All KDL documents MUST be encoded in UTF-8 and conform to the
+   All KDL documents should be UTF-8 encoded and conform to the
    specifications in this document.
 
+
+
+
+
+Marchán & KDL Contributors    Experimental                      [Page 3]
+
+                                   KDL                      January 2025
+
+
 3.1.1.  Example
 
    The following is a document composed of two toplevel nodes:
@@ -187,9 +217,18 @@ Table of Contents
    children, and make it act as plain whitespace, even if it spreads
    across multiple lines.
 
+
+
+
+
+Marchán & KDL Contributors    Experimental                      [Page 4]
+
+                                   KDL                      January 2025
+
+
    Finally, a node is terminated by either a Newline (Section 3.18), a
-   semicolon (;), the end of its parent's child block (}) or the end of
+   semicolon (;), the end of a child block (}) or the end of the file/
-   the file/stream (an EOF).
+   stream (an EOF).
 
 3.2.1.  Example
 
@@ -236,6 +275,13 @@ Table of Contents
    Deserialized representations may iterate over properties in any order
    and still be spec-compliant.
 
+
+
+Marchán & KDL Contributors    Experimental                      [Page 5]
+
+                                   KDL                      January 2025
+
+
    Properties _MAY_ be prefixed with /- to "comment out" the entire
    token and make it act as plain whitespace, even if it spreads across
    multiple lines.
@@ -275,13 +321,23 @@ Table of Contents
        child2
    }
 
-   parent { child1; child2 }
+   parent { child1; child2; }
 
 3.7.  Value
 
    A value is either: a String (Section 3.9), a Number (Section 3.14), a
    Boolean (Section 3.15), or Null (Section 3.16).
 
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                      [Page 6]
+
+                                   KDL                      January 2025
+
+
    Values _MUST_ be either Arguments (Section 3.5) or values of
    Properties (Section 3.4).  Only String (Section 3.9) values may be
    used as Node (Section 3.2) names or Property (Section 3.4) keys.
@@ -331,6 +387,13 @@ Table of Contents
 
    *  u64
 
+
+
+Marchán & KDL Contributors    Experimental                      [Page 7]
+
+                                   KDL                      January 2025
+
+
    *  u128
 
    Platform-dependent integer types, both signed and unsigned:
@@ -380,6 +443,13 @@ Table of Contents
 
    *  hostname: RFC1123 internet hostname (only ASCII segments)
 
+
+
+Marchán & KDL Contributors    Experimental                      [Page 8]
+
+                                   KDL                      January 2025
+
+
    *  idn-hostname: RFC5890 internationalized internet hostname (only xn
       ---prefixed ASCII "punycode" segments, or non-ASCII segments)
 
@@ -405,9 +475,6 @@ Table of Contents
 
    *  base64: A Base64-encoded string, denoting arbitrary binary data.
 
-   *  base85: An Ascii85 (https://en.wikipedia.org/wiki/Ascii85)-encoded
-      string, denoting arbitrary binary data.
-
 3.8.4.  Examples
 
    node (u8)123
@@ -432,6 +499,13 @@ Table of Contents
    *  Multi-Line Strings let you write strings across multiple lines and
       with indentation that's not part of the string value.
 
+
+
+Marchán & KDL Contributors    Experimental                      [Page 9]
+
+                                   KDL                      January 2025
+
+
    *  Raw Strings don't allow any escapes, allowing you to not worry
       about the string's content containing anything that might look
       like an escape.
@@ -478,6 +552,16 @@ Table of Contents
    Additionally, the following initial characters impose limitations on
    subsequent characters:
 
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 10]
+
+                                   KDL                      January 2025
+
+
    *  the + and - characters can only be used as an initial character if
       the second character is _not_ a digit.  If the second character is
       ., then the third character must _not_ be a digit.
@@ -526,6 +610,14 @@ Table of Contents
    by another character, and are interpreted as described in the
    following table:
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 11]
+
+                                   KDL                      January 2025
+
+
    +==============+=========+=========================================+
    | Name         | Escape  | Code Pt                                 |
    +==============+=========+=========================================+
@@ -574,6 +666,14 @@ Table of Contents
 
    and
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 12]
+
+                                   KDL                      January 2025
+
+
    "Hello \    World"
 
    are semantically identical.  See whitespace (Section 3.17) and
@@ -623,18 +723,18 @@ Table of Contents
    on all intermediate lines.  The first and last Newline can be the
    same character (that is, empty multi-line strings are legal).
 
+
+
+Marchán & KDL Contributors    Experimental                     [Page 13]
+
+                                   KDL                      January 2025
+
+
    In other words, the final line specifies the whitespace prefix that
    will be removed from all other lines.
 
-   Whitespace-only lines (that is, lines containing only literal
-   whitespace characters, not including whitespace escapes like \t)
-   always represent empty lines in the string value, regardless of what
-   whitespace they contain (if any).  They do not have to start with the
-   same whitespace prefix that other lines do; all characters on the
-   line are ignored.
-
    Multi-line Strings that do not immediately start with a Newline and
-   whose final """ is not preceded by optional whitespace and a Newline
+   whose final """ is not preceeded by optional whitespace and a Newline
    are illegal.  This also means that """ may not be used for a single-
    line String (e.g. """foo""").
 
@@ -678,6 +778,14 @@ Table of Contents
 
    which is equivalent to
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 14]
+
+                                   KDL                      January 2025
+
+
    "    foo\nThis is the base indentation\n        bar"
 
    when written as a single-line string.
@@ -724,6 +832,16 @@ Table of Contents
 
    "Indented a bit.\n\nA second indented paragraph."
 
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 15]
+
+                                   KDL                      January 2025
+
+
 3.12.2.4.  Syntax errors
 
    The following yield *syntax errors*:
@@ -770,6 +888,16 @@ Table of Contents
 
    while the following example is allowed
 
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 16]
+
+                                   KDL                      January 2025
+
+
      """
      foo \
    bar
@@ -814,6 +942,18 @@ Table of Contents
 
    The string contains the literal characters hello\n\r\asd"#world
 
+
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 17]
+
+                                   KDL                      January 2025
+
+
    raw-multi-line #"""
        Here's a """
            multiline string
@@ -862,6 +1002,14 @@ Table of Contents
 
       -  They have no radix prefix.
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 18]
+
+                                   KDL                      January 2025
+
+
       -  They use digits 0 through 9, which may be separated by _.
 
       -  They may optionally include a decimal separator ., followed by
@@ -870,14 +1018,6 @@ Table of Contents
       -  They may optionally be followed by E or e, an optional - or +,
          and more digits, to represent an exponent value.
 
-   In all cases where the above says that digits "may be separated by
-   _", this means that between any two digits, or after the digits, any
-   number of consecutive _ characters can appear.  Underscores are not
-   allowed _before_ the digits.  That is, 1___2 and 12____ are valid
-   (and both equivalent to just 12), but _12 is _not_ a valid number (it
-   will instead parse as an identifier string), nor is 0x_1a (it will
-   simply be invalid).
-
    Note that, similar to JSON and some other languages, numbers without
    an integer digit (such as .1) are illegal.  They must be written with
    at least one integer digit, like 0.1.  (These patterns are also
@@ -887,7 +1027,7 @@ Table of Contents
 3.14.1.  Keyword Numbers
 
    There are three special "keyword" numbers included in KDL to
-   accommodate the widespread use of IEEE 754
+   accomodate the widespread use of IEEE 754
    (https://en.wikipedia.org/wiki/IEEE_754) floats:
 
    *  #inf - floating point positive infinity.
@@ -915,6 +1055,17 @@ Table of Contents
 
    my-node #true value=#false
 
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 19]
+
+                                   KDL                      January 2025
+
+
 3.16.  Null
 
    The symbol #null represents a null Value (Section 3.7).  It's up to
@@ -931,6 +1082,46 @@ Table of Contents
    (Section 3.18) white space
    (https://www.unicode.org/Public/UCD/latest/ucd/PropList.txt):
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 20]
+
+                                   KDL                      January 2025
+
+
                   +===========================+=========+
                   | Name                      | Code Pt |
                   +===========================+=========+
@@ -978,6 +1169,15 @@ Table of Contents
    Any text after //, until the next literal Newline (Section 3.18) is
    "commented out", and is considered to be Whitespace (Section 3.17).
 
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 21]
+
+                                   KDL                      January 2025
+
+
 3.17.2.  Multi-line comments
 
    In addition to single-line comments using //, comments can also be
@@ -1020,6 +1220,20 @@ Table of Contents
    (https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-
    5/#G41643):
 
+
+
+
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 22]
+
+                                   KDL                      January 2025
+
+
        +=========+===============================+=================+
        | Acronym | Name                          | Code Pt         |
        +=========+===============================+=================+
@@ -1068,6 +1282,14 @@ Table of Contents
    *  U+FEFF, aka Zero-width Non-breaking Space (ZWNBSP)/Byte Order Mark
       (BOM), except as the first code point in a document.
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 23]
+
+                                   KDL                      January 2025
+
+
 4.  Full Grammar
 
    This is the full official grammar for KDL and should be considered
@@ -1080,11 +1302,11 @@ Table of Contents
    nodes := (line-space* node)* line-space*
 
    base-node := slashdash? type? node-space* string
-       (node-space* (node-space | slashdash) node-prop-or-arg)*
+       (node-space+ slashdash? node-prop-or-arg)*
        // slashdashed node-children must always be after props and args.
-       (node-space* slashdash node-children)*
+       (node-space+ slashdash node-children)*
-       (node-space* node-children)?
+       (node-space+ node-children)?
-       (node-space* slashdash node-children)*
+       (node-space+ slashdash node-children)*
        node-space*
    node := base-node node-terminator
    final-node := base-node node-terminator?
@@ -1101,11 +1323,10 @@ Table of Contents
    // Strings
    string := identifier-string | quoted-string | raw-string ¶
 
-   identifier-string :=
+   identifier-string := unambiguous-ident | signed-ident | dotted-ident
-       (unambiguous-ident | signed-ident | dotted-ident)
-       - disallowed-keyword-identifiers
    unambiguous-ident :=
-       (identifier-char - digit - sign - '.') identifier-char*
+       ((identifier-char - digit - sign - '.') identifier-char*)
+       - disallowed-keyword-strings
    signed-ident :=
        sign ((identifier-char - digit - '.') identifier-char*)?
    dotted-ident :=
@@ -1117,6 +1338,14 @@ Table of Contents
        'true' | 'false' | 'null' | 'inf' | '-inf' | 'nan'
 
    quoted-string :=
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 24]
+
+                                   KDL                      January 2025
+
+
        '"' single-line-string-body '"' |
        '"""' newline
        (multi-line-string-body newline)?
@@ -1130,13 +1359,10 @@ Table of Contents
        [^\\"] - disallowed-literal-code-points
    ws-escape := '\\' (unicode-space | newline)+
    hex-digit := [0-9a-fA-F]
-   hex-unicode := hex-digit{1, 6} - surrogate - above-max-scalar
+   hex-unicode := hex-digit{1, 6} - surrogates
-   surrogate := [0]{0, 2} [dD] [8-9a-fA-F] hex-digit{2}
+   surrogates := [dD][8-9a-fA-F]hex-digit{2}
-   //  U+D800-DFFF:         D   8          00
+   // U+D800-DFFF: D  8         00
-   //                       D   F          FF
+   //              D  F         FF
-   above-max-scalar = [2-9a-fA-F] hex-digit{5} |
-       [1] [1-9a-fA-F] hex-digit{4}
-
 
    raw-string := '#' raw-string-quotes '#' | '#' raw-string '#'
    raw-string-quotes :=
@@ -1168,6 +1394,14 @@ Table of Contents
    octal := sign? '0o' [0-7] [0-7_]*
    binary := sign? '0b' ('0' | '1') ('0' | '1' | '_')*
 
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 25]
+
+                                   KDL                      January 2025
+
+
    // Keywords and booleans.
    keyword := boolean | '#null'
    keyword-number := '#inf' | '#-inf' | '#nan'
@@ -1213,6 +1447,17 @@ Table of Contents
       initiating unicode characters using hex values (\u{FEFF}), and for
       escaping \ itself (\\).
 
+
+
+
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 26]
+
+                                   KDL                      January 2025
+
+
    *  * is used for "zero or more", + is used for "one or more", and ?
       is used for "zero or one".  Per standard regex semantics, * and +
       are _greedy_; they match as many instances as possible without
@@ -1261,3 +1506,7 @@ Authors' Addresses
 
 
    The KDL Contributors
+
+
+
+Marchán & KDL Contributors    Experimental                     [Page 27]