number suffix type annotations

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 `.<digit>`)
+
+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' | '_')*

tests/test_cases/expected_kdl/suffix_type_bare.kdl

@@ -0,0 +1 @@
+node (abc)123

tests/test_cases/expected_kdl/suffix_type_bare_letter_number.kdl

@@ -0,0 +1 @@
+node (u8)123

tests/test_cases/expected_kdl/suffix_type_bare_underscore.kdl

@@ -0,0 +1 @@
+node (abc)123

tests/test_cases/expected_kdl/suffix_type_explicit.kdl

@@ -0,0 +1 @@
+node (abc)123

tests/test_cases/expected_kdl/suffix_type_explicit_exponent.kdl

@@ -0,0 +1 @@
+node (abc)12300000

tests/test_cases/expected_kdl/suffix_type_explicit_non_decimal.kdl

@@ -0,0 +1 @@
+node (abc)5 (def)83 (zzz)291

tests/test_cases/input/exponent_no_digit_fail.kdl

@@ -0,0 +1 @@
+node 1.0e-

tests/test_cases/input/suffix_type_bare.kdl

@@ -0,0 +1 @@
+node 123abc

tests/test_cases/input/suffix_type_bare_binary_fail.kdl

@@ -0,0 +1 @@
+node 0b0101hi

tests/test_cases/input/suffix_type_bare_binaryish_fail.kdl

@@ -0,0 +1 @@
+node 0b

tests/test_cases/input/suffix_type_bare_comma_fail.kdl

@@ -0,0 +1 @@
+node 123,abc

tests/test_cases/input/suffix_type_bare_exponent_exponent_fail.kdl

@@ -0,0 +1 @@
+node 123e5e5

tests/test_cases/input/suffix_type_bare_exponentish_fail.kdl

@@ -0,0 +1 @@
+node 123e5abc

tests/test_cases/input/suffix_type_bare_exponentish_no_digit_fail.kdl

@@ -0,0 +1 @@
+node 1234e+foo

tests/test_cases/input/suffix_type_bare_hex_fail.kdl

@@ -0,0 +1 @@
+node 0x123nope

tests/test_cases/input/suffix_type_bare_hexish_fail.kdl

@@ -0,0 +1 @@
+node 0xohno

tests/test_cases/input/suffix_type_bare_keyword_fail.kdl

@@ -0,0 +1 @@
+node #truefoo #false#bar #nullish #nan#no #inf123 #-inf#123

tests/test_cases/input/suffix_type_bare_letter_number.kdl

@@ -0,0 +1 @@
+node 123u8

tests/test_cases/input/suffix_type_bare_octal_fail.kdl

@@ -0,0 +1 @@
+node 0o123nope

tests/test_cases/input/suffix_type_bare_on_quoted_string_fail.kdl

@@ -0,0 +1 @@
+node "foo"bar

tests/test_cases/input/suffix_type_bare_on_raw_string_fail.kdl

@@ -0,0 +1 @@
+node #"foo"#bar

tests/test_cases/input/suffix_type_bare_period_fail.kdl

@@ -0,0 +1 @@
+node 123.abc

tests/test_cases/input/suffix_type_bare_quoted_string_fail.kdl

@@ -0,0 +1 @@
+node 123"astring"

tests/test_cases/input/suffix_type_bare_raw_string_fail.kdl

@@ -0,0 +1 @@
+node 456#"rawstring"#

tests/test_cases/input/suffix_type_bare_redundant_fail.kdl

@@ -0,0 +1 @@
+node (abc)123def

tests/test_cases/input/suffix_type_bare_underscore.kdl

@@ -0,0 +1 @@
+node 123_abc

tests/test_cases/input/suffix_type_explicit.kdl

@@ -0,0 +1 @@
+node 123#abc

tests/test_cases/input/suffix_type_explicit_exponent.kdl

@@ -0,0 +1 @@
+node 123e5#abc

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

tests/test_cases/input/suffix_type_explicit_non_decimal.kdl

@@ -0,0 +1 @@
+node 0b0101#abc 0o123#def 0x123#zzz

tests/test_cases/input/suffix_type_explicit_number_fail.kdl

@@ -0,0 +1 @@
+node 123#123

tests/test_cases/input/suffix_type_explicit_quoted_string_fail.kdl

@@ -0,0 +1 @@
+node 123#"string"

tests/test_cases/input/suffix_type_explicit_raw_string_fail.kdl

@@ -0,0 +1 @@
+node 456##"rawstring"#

tests/test_cases/input/suffix_type_explicit_redundant_fail.kdl

@@ -0,0 +1 @@
+node (abc)123#def