diff --git a/draft-marchan-kdl2.md b/draft-marchan-kdl2.md index 865d13a9..eb7ca726 100644 --- a/draft-marchan-kdl2.md +++ b/draft-marchan-kdl2.md @@ -117,10 +117,11 @@ Being a node-oriented language means that the real core component of any KDL document is the "node". Every node must have a name, which must be a String ({{string}}). -The name may be preceded by a Type Annotation ({{type-annotation}}) to further -clarify its type, particularly in relation to its parent node. (For example, -clarifying that a particular `date` child node is for the _publication_ date, -rather than the last-modified date, with `(published)date`.) +The name may be preceded by a Prefix Type Annotation +({{prefix-type-annotation}}) to further clarify its type, particularly in +relation to its parent node. (For example, clarifying that a particular `date` +child node is for the _publication_ date, rather than the last-modified date, +with `(published)date`.) Following the name are zero or more Arguments ({{argument}}) or Properties ({{property}}), separated by either whitespace ({{whitespace}}) or a @@ -247,28 +248,124 @@ Values _MUST_ be either Arguments ({{argument}}) or values of Properties ({{property}}). Only String ({{string}}) values may be used as Node ({{node}}) names or Property ({{property}}) keys. -Values (both as arguments and in properties) _MAY_ be prefixed by a single -Type Annotation ({{type-annotation}}). +Values (both as arguments and in properties) _MAY_ include a single Type +Annotation ({{type-annotation}}). ## Type Annotation -A type annotation is a prefix to any Node Name ({{node}}) or Value ({{value}}) that -includes a _suggestion_ of what type the value is _intended_ to be treated as, -or as a _context-specific elaboration_ of the more generic type the node name -indicates. - -Type annotations are written as a set of `(` and `)` with a single -String ({{string}}) in it. It may contain Whitespace after the `(` and before -the `)`, and may be separated from its target by Whitespace. +A type annotation is a String ({{string}}) value attached to any Node Name +({{node}}) or Value ({{value}}) that includes a _suggestion_ of what type the +value is _intended_ to be treated as, or as a _context-specific elaboration_ of +the more generic type the node name indicates. KDL does not specify any restrictions on what implementations might do with these annotations. They are free to ignore them, or use them to make decisions -about how to interpret a value. +about how to interpret a value. That said, KDL does reserve certain well-known +strings for what would be their intended purpose, for the sake of +interoperability ({{reserved-type-annotations}}). -Additionally, the following type annotations MAY be recognized by KDL parsers -and, if used, SHOULD interpret these types as follows: +There are two kinds of Type Annotation syntaxes in KDL: Prefix Type Annotations +({{prefix-type-annotation}}) and Suffix Type Annotations +({{suffix-type-annotation}}). + +### Examples + +~~~kdl +node 123u8 +node 0#b 20b 50GiB +node prop=(regex).* +(published)date "1970-01-01" +(contributor)person name="Foo McBar" +~~~ + +### Prefix Type Annotation + +Prefix Type Annotations are written as a set of `(` and `)` with a single String +({{string}}) in it. It may contain Whitespace after the `(` and before the `)`, +and may be separated from its target by Whitespace. Unlike the other annotation +types, any String type may be used. + +### Suffix Type Annotation + +When a Value ({{value}}) is a Number ({{number}}), it's possible to attach the +type annotation as a "suffix", instead of prepending it between `(` and `)`. +This makes it possible to, for example, write `10px`, `10.5%`, `512GiB`, etc., +which are equivalent to `(px)10`, `(%)5`, and `(GiB)512`, respectively. + +Most suffixes can be appended directly to the number (a Bare Suffix Type +Annotation ({{bare-suffix-type-annotation}})), as shown in the previous +paragraph. To avoid parsing ambiguity, there are some restrictions on this; an +Explicit Suffix Type Annotation ({{explicit-suffix-type-annotation}}) avoids all +these restrictions by using an additional `#` to explicitly indicate it. For +example, `0bytes` is invalid, but `0#bytes` is valid and equivalent to +`(bytes)0`. See Bare Suffix Type Annotation ({{bare-suffix-type-annotation}}) +for the full list of restrictions. + +An implementation that finds BOTH a parenthesized Prefix Type Annotation +({{prefix-type-annotation}}) and a Suffix Type Annotation +({{suffix-type-annotation}}) on the same Number ({{number}}) MUST yield a syntax +error. + +Suffixes MUST BE plain Identifier Strings ({{identifier-string}}). No other +String ({{string}}) syntax is acceptable. + +#### Bare Suffix Type Annotation + +When a Value ({{value}}) is a Number ({{number}}) that meets certain criteria, +it's possible to append an Identifier String ({{identifier-string}}), and ONLY +an Identifier String, as a suffix directly to the Number, as its Type Annotation +({{type-annotation}}). The criteria are as follows: + +* The Number MUST be a Decimal (that is, it MUST NOT start with `0b`, `0o`, or + `0x`). Additionally, the tokens `0b`, `0o`, and `0x` MUST be treated as syntax + errors (incomplete non-decimal numbers). +* It MUST NOT have an exponent part (e.g. `5.2e+3`). +* The Identifier String used for the type itself MUST NOT start with either `.` or `,`. +* As part of the exponential restriction, the suffix MUST NOT match + `[eE]([-+]|[0-9])` (e.g. `5.2e+` SHOULD be considered a "bad exponential", and + MUST NOT parse as `(e+)5.2`). -### Reserved Type Annotations for Numbers Without Decimals: +For example, the following are all illegal: + +* `10,000` (suffix would start with `,`) +* `10e0n` (suffix on an exponential) +* `0xyz` (starts with reserved hexadecimal prefix) +* `0b` (starts with reserved binary prefix) +* `5e+oops` (looks too close to an exponential) +* `1.2.3-abc` (suffix would start with `.` AND Identifier Strings can't start + with `.`) + +Whereas the following are all legal: + +* `0u8` = `(u8)0` +* `5em` = `(em)5`, the `e` is not followed by a digit. +* `1xyz` = `(xyz)1`, no longer starts with `0` as above. +* `20b` = `(b)20`, "20 bytes", no longer starts with just `0` as above. + +If the desired suffix would violate any of the above rules, either Prefix Type +Annotations ({{prefix-type-annotation}}) or Explicit Suffix Type Annotations +({{explicit-suffix-type-annotation}}) may be used. + +#### Explicit Suffix Type Annotation + +Any Number ({{number}}) may have a `#` appended to it, followed by any valid +Identifier String ({{identifier-string}}). This is an Explicit Suffix Type +Annotation ({{suffix-type-annotation}}) syntax without any of the added +restrictions of Bare Suffix Type Annotations ({{bare-suffix-type-annotation}}), +which can be a useful escape hatch. For example: `0#b` is invalid syntax without +the `#` prefix. + +Note that, unlike Bare Suffix Type Annotations +({{bare-suffix-type-annotation}}), Explicit Suffixes may be used with ALL Number +({{number}}) formats (hexadecimal, decimal, octal, and binary). For example, +`0x1234#u32` is valid. + +### Reserved Type Annotations + +#### For Numbers Without Decimal Parts + +Additionally, the following type annotations MAY be recognized by KDL parsers +and, if used, SHOULD interpret these types as follows. Signed integers of various sizes (the number is the bit size): @@ -291,7 +388,7 @@ Platform-dependent integer types, both signed and unsigned: - `isize` - `usize` -### Reserved Type Annotations for Numbers With Decimals: +#### For Numbers With Decimal Parts IEEE 754 floating point numbers, both single (32) and double (64) precision: @@ -303,7 +400,7 @@ IEEE 754-2008 decimal floating point numbers - `decimal64` - `decimal128` -### Reserved Type Annotations for Strings: +#### For Strings - `date-time`: ISO8601 date/time format. - `time`: "Time" section of ISO8601. @@ -331,15 +428,6 @@ IEEE 754-2008 decimal floating point numbers - `base64`: A Base64-encoded string, denoting arbitrary binary data. - `base85`: An [Ascii85](https://en.wikipedia.org/wiki/Ascii85)-encoded string, denoting arbitrary binary data. -### Examples - -~~~kdl -node (u8)123 -node prop=(regex).* -(published)date "1970-01-01" -(contributor)person name="Foo McBar" -~~~ - ## String Strings in KDL represent textual UTF-8 Values ({{value}}). A String is either an @@ -951,8 +1039,9 @@ node-children := '{' nodes final-node? '}' node-terminator := single-line-comment | newline | ';' | eof prop := string node-space* '=' node-space* value -value := type? node-space* (string | number | keyword) +value := normal-value | suffixed-decimal type := '(' node-space* string node-space* ')' +normal-value := type? node-space* (string | number | keyword) // Strings string := identifier-string | quoted-string | raw-string ΒΆ @@ -1013,12 +1102,26 @@ multi-line-raw-string-body := // Numbers number := keyword-number | hex | octal | binary | decimal -decimal := sign? integer ('.' integer)? exponent? +decimal := significand exponent? +suffixed-decimal := significand ( + bare-type-suffix + | (exponent? explicit-type-suffix) +) +significand := sign? significand-initial integer? ('.' integer)? exponent := ('e' | 'E') sign? integer integer := digit (digit | '_')* +significand-initial = digit + - '0b' + - '0o' + - '0x' digit := [0-9] sign := '+' | '-' +bare-type-suffix := unambiguous-bare-type-suffix | e-bare-type-suffix +unambiguous-bare-type-suffix := (identifier-char - ('.' | ',' | 'e' | 'E')) identifier-char* +e-bare-type-suffix := 'e' | 'E' | ( ((identifier-char - ('.' | ',')) identifier-char) - (('e' | 'E') (sign | digit)) ) identifier-char* +explicit-type-suffix := '#' identifier-string + hex := sign? '0x' hex-digit (hex-digit | '_')* octal := sign? '0o' [0-7] [0-7_]* binary := sign? '0b' ('0' | '1') ('0' | '1' | '_')* diff --git a/tests/test_cases/expected_kdl/suffix_type_bare.kdl b/tests/test_cases/expected_kdl/suffix_type_bare.kdl new file mode 100644 index 00000000..885fe200 --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_bare.kdl @@ -0,0 +1 @@ +node (abc)123 diff --git a/tests/test_cases/expected_kdl/suffix_type_bare_letter_number.kdl b/tests/test_cases/expected_kdl/suffix_type_bare_letter_number.kdl new file mode 100644 index 00000000..f8433a74 --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_bare_letter_number.kdl @@ -0,0 +1 @@ +node (u8)123 diff --git a/tests/test_cases/expected_kdl/suffix_type_bare_underscore.kdl b/tests/test_cases/expected_kdl/suffix_type_bare_underscore.kdl new file mode 100644 index 00000000..885fe200 --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_bare_underscore.kdl @@ -0,0 +1 @@ +node (abc)123 diff --git a/tests/test_cases/expected_kdl/suffix_type_explicit.kdl b/tests/test_cases/expected_kdl/suffix_type_explicit.kdl new file mode 100644 index 00000000..885fe200 --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_explicit.kdl @@ -0,0 +1 @@ +node (abc)123 diff --git a/tests/test_cases/expected_kdl/suffix_type_explicit_exponent.kdl b/tests/test_cases/expected_kdl/suffix_type_explicit_exponent.kdl new file mode 100644 index 00000000..c3f9ce0e --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_explicit_exponent.kdl @@ -0,0 +1 @@ +node (abc)12300000 diff --git a/tests/test_cases/expected_kdl/suffix_type_explicit_non_decimal.kdl b/tests/test_cases/expected_kdl/suffix_type_explicit_non_decimal.kdl new file mode 100644 index 00000000..81b59ff5 --- /dev/null +++ b/tests/test_cases/expected_kdl/suffix_type_explicit_non_decimal.kdl @@ -0,0 +1 @@ +node (abc)5 (def)83 (zzz)291 diff --git a/tests/test_cases/input/bare_ident_numeric_fail.kdl b/tests/test_cases/input/bare_ident_numeric_fail.kdl deleted file mode 100644 index 053af211..00000000 --- a/tests/test_cases/input/bare_ident_numeric_fail.kdl +++ /dev/null @@ -1 +0,0 @@ -node 0n \ No newline at end of file diff --git a/tests/test_cases/input/bare_ident_numeric_sign_fail.kdl b/tests/test_cases/input/bare_ident_numeric_sign_fail.kdl deleted file mode 100644 index 6cadc35e..00000000 --- a/tests/test_cases/input/bare_ident_numeric_sign_fail.kdl +++ /dev/null @@ -1 +0,0 @@ -node +0n \ No newline at end of file diff --git a/tests/test_cases/input/exponent_no_digit_fail.kdl b/tests/test_cases/input/exponent_no_digit_fail.kdl new file mode 100644 index 00000000..cca7adb1 --- /dev/null +++ b/tests/test_cases/input/exponent_no_digit_fail.kdl @@ -0,0 +1 @@ +node 1.0e- diff --git a/tests/test_cases/input/suffix_type_bare.kdl b/tests/test_cases/input/suffix_type_bare.kdl new file mode 100644 index 00000000..a032d6a2 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare.kdl @@ -0,0 +1 @@ +node 123abc diff --git a/tests/test_cases/input/suffix_type_bare_binary_fail.kdl b/tests/test_cases/input/suffix_type_bare_binary_fail.kdl new file mode 100644 index 00000000..e14dd7f5 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_binary_fail.kdl @@ -0,0 +1 @@ +node 0b0101hi diff --git a/tests/test_cases/input/suffix_type_bare_binaryish_fail.kdl b/tests/test_cases/input/suffix_type_bare_binaryish_fail.kdl new file mode 100644 index 00000000..bfc36dc4 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_binaryish_fail.kdl @@ -0,0 +1 @@ +node 0b diff --git a/tests/test_cases/input/suffix_type_bare_comma_fail.kdl b/tests/test_cases/input/suffix_type_bare_comma_fail.kdl new file mode 100644 index 00000000..1ff24807 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_comma_fail.kdl @@ -0,0 +1 @@ +node 123,abc diff --git a/tests/test_cases/input/suffix_type_bare_exponent_exponent_fail.kdl b/tests/test_cases/input/suffix_type_bare_exponent_exponent_fail.kdl new file mode 100644 index 00000000..235474e2 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_exponent_exponent_fail.kdl @@ -0,0 +1 @@ +node 123e5e5 diff --git a/tests/test_cases/input/suffix_type_bare_exponentish_fail.kdl b/tests/test_cases/input/suffix_type_bare_exponentish_fail.kdl new file mode 100644 index 00000000..678175a8 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_exponentish_fail.kdl @@ -0,0 +1 @@ +node 123e5abc diff --git a/tests/test_cases/input/suffix_type_bare_exponentish_no_digit_fail.kdl b/tests/test_cases/input/suffix_type_bare_exponentish_no_digit_fail.kdl new file mode 100644 index 00000000..d61a1ae3 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_exponentish_no_digit_fail.kdl @@ -0,0 +1 @@ +node 1234e+foo diff --git a/tests/test_cases/input/suffix_type_bare_hex_fail.kdl b/tests/test_cases/input/suffix_type_bare_hex_fail.kdl new file mode 100644 index 00000000..dc0efe44 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_hex_fail.kdl @@ -0,0 +1 @@ +node 0x123nope diff --git a/tests/test_cases/input/suffix_type_bare_hexish_fail.kdl b/tests/test_cases/input/suffix_type_bare_hexish_fail.kdl new file mode 100644 index 00000000..37977c93 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_hexish_fail.kdl @@ -0,0 +1 @@ +node 0xohno diff --git a/tests/test_cases/input/suffix_type_bare_keyword_fail.kdl b/tests/test_cases/input/suffix_type_bare_keyword_fail.kdl new file mode 100644 index 00000000..ffdaff40 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_keyword_fail.kdl @@ -0,0 +1 @@ +node #truefoo #false#bar #nullish #nan#no #inf123 #-inf#123 diff --git a/tests/test_cases/input/suffix_type_bare_letter_number.kdl b/tests/test_cases/input/suffix_type_bare_letter_number.kdl new file mode 100644 index 00000000..3310ecad --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_letter_number.kdl @@ -0,0 +1 @@ +node 123u8 diff --git a/tests/test_cases/input/suffix_type_bare_octal_fail.kdl b/tests/test_cases/input/suffix_type_bare_octal_fail.kdl new file mode 100644 index 00000000..8adf6a21 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_octal_fail.kdl @@ -0,0 +1 @@ +node 0o123nope diff --git a/tests/test_cases/input/suffix_type_bare_on_quoted_string_fail.kdl b/tests/test_cases/input/suffix_type_bare_on_quoted_string_fail.kdl new file mode 100644 index 00000000..f8ace5fc --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_on_quoted_string_fail.kdl @@ -0,0 +1 @@ +node "foo"bar diff --git a/tests/test_cases/input/suffix_type_bare_on_raw_string_fail.kdl b/tests/test_cases/input/suffix_type_bare_on_raw_string_fail.kdl new file mode 100644 index 00000000..9e72af0c --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_on_raw_string_fail.kdl @@ -0,0 +1 @@ +node #"foo"#bar diff --git a/tests/test_cases/input/suffix_type_bare_period_fail.kdl b/tests/test_cases/input/suffix_type_bare_period_fail.kdl new file mode 100644 index 00000000..8f0aad52 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_period_fail.kdl @@ -0,0 +1 @@ +node 123.abc diff --git a/tests/test_cases/input/suffix_type_bare_quoted_string_fail.kdl b/tests/test_cases/input/suffix_type_bare_quoted_string_fail.kdl new file mode 100644 index 00000000..335a1a25 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_quoted_string_fail.kdl @@ -0,0 +1 @@ +node 123"astring" diff --git a/tests/test_cases/input/suffix_type_bare_raw_string_fail.kdl b/tests/test_cases/input/suffix_type_bare_raw_string_fail.kdl new file mode 100644 index 00000000..3453eebb --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_raw_string_fail.kdl @@ -0,0 +1 @@ +node 456#"rawstring"# diff --git a/tests/test_cases/input/suffix_type_bare_redundant_fail.kdl b/tests/test_cases/input/suffix_type_bare_redundant_fail.kdl new file mode 100644 index 00000000..8fc91279 --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_redundant_fail.kdl @@ -0,0 +1 @@ +node (abc)123def diff --git a/tests/test_cases/input/suffix_type_bare_underscore.kdl b/tests/test_cases/input/suffix_type_bare_underscore.kdl new file mode 100644 index 00000000..e7ee020a --- /dev/null +++ b/tests/test_cases/input/suffix_type_bare_underscore.kdl @@ -0,0 +1 @@ +node 123_abc diff --git a/tests/test_cases/input/suffix_type_explicit.kdl b/tests/test_cases/input/suffix_type_explicit.kdl new file mode 100644 index 00000000..47e027e5 --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit.kdl @@ -0,0 +1 @@ +node 123#abc diff --git a/tests/test_cases/input/suffix_type_explicit_exponent.kdl b/tests/test_cases/input/suffix_type_explicit_exponent.kdl new file mode 100644 index 00000000..87deb179 --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_exponent.kdl @@ -0,0 +1 @@ +node 123e5#abc diff --git a/tests/test_cases/input/suffix_type_explicit_keyword_fail.kdl b/tests/test_cases/input/suffix_type_explicit_keyword_fail.kdl new file mode 100644 index 00000000..cd233adf --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_keyword_fail.kdl @@ -0,0 +1 @@ +node 123#true 456#false 789#null 012#nan 345#inf 678#-inf diff --git a/tests/test_cases/input/suffix_type_explicit_non_decimal.kdl b/tests/test_cases/input/suffix_type_explicit_non_decimal.kdl new file mode 100644 index 00000000..2eb552a7 --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_non_decimal.kdl @@ -0,0 +1 @@ +node 0b0101#abc 0o123#def 0x123#zzz diff --git a/tests/test_cases/input/suffix_type_explicit_number_fail.kdl b/tests/test_cases/input/suffix_type_explicit_number_fail.kdl new file mode 100644 index 00000000..ef43d25f --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_number_fail.kdl @@ -0,0 +1 @@ +node 123#123 diff --git a/tests/test_cases/input/suffix_type_explicit_quoted_string_fail.kdl b/tests/test_cases/input/suffix_type_explicit_quoted_string_fail.kdl new file mode 100644 index 00000000..5ffa2ccf --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_quoted_string_fail.kdl @@ -0,0 +1 @@ +node 123#"string" diff --git a/tests/test_cases/input/suffix_type_explicit_raw_string_fail.kdl b/tests/test_cases/input/suffix_type_explicit_raw_string_fail.kdl new file mode 100644 index 00000000..7203cd63 --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_raw_string_fail.kdl @@ -0,0 +1 @@ +node 456##"rawstring"# diff --git a/tests/test_cases/input/suffix_type_explicit_redundant_fail.kdl b/tests/test_cases/input/suffix_type_explicit_redundant_fail.kdl new file mode 100644 index 00000000..7bd2fe9e --- /dev/null +++ b/tests/test_cases/input/suffix_type_explicit_redundant_fail.kdl @@ -0,0 +1 @@ +node (abc)123#def