berkus
/
kdl-org.github.io
mirror of https://github.com/kdl-org/kdl-org.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Regenerate website spec

This commit is contained in:
Brandon Chinn 2026-01-26 18:02:17 -08:00 committed by GitHub
parent 56c54e7d6e
commit 26d3c43361
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 820 additions and 1218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1611
src/spec.html
View File

File diff suppressed because it is too large Load Diff

427
src/spec.txt
View File

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