more refinement

Author: zkat

draft-marchan-kdl2.md

@@ -252,18 +252,37 @@ 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}}).
+
+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
 
@@ -294,16 +313,18 @@ String ({{string}}) syntax is acceptable.
 
 #### Bare Suffix Type Annotation
 
-When a Value ({{value}}) is a decimal Number ({{number}}) WITHOUT exponential
-syntax (`1e+5` etc) (and ONLY a decimal. That is, numbers which do NOT have a
-`0b`/`0o`/`0x` prefix with an optional sign), it's possible to append the type
+When a Value ({{value}}) is a decimal Number ({{number}}) WITHOUT an exponential
+part--that is, numbers which do NOT have a `0b`/`0o`/`0x` prefix with an
+optional sign, or which look like `5.2e+3`--it's possible to append the type
 annotation as a suffix directly to the number, without any additional syntax.
 
 To remove further ambiguity, on top of not being available for non-decimal
 prefixes, and for decimals with exponent parts, the suffix Identifier String
-({{identifier-string}}) itself MUST NOT start with any of `.`, `,`, or `_`, as
-well as `[eE][-+]?[0-9]?` as part of the exponential restriction above. Note the
-optional digit, which is added to prevent typo ambiguity.
+({{identifier-string}}) itself MUST NOT start with either `.` or `,`, as well as
+`[eE][-+]?[0-9]?` (as part of the exponential restriction above). Note the
+optional digit, which is added to prevent typo ambiguity. Additionally, a
+standalone non-decimal Number ({{number}}) prefix MUST yield a syntax error
+(e.g. `0b` is an incorrect binary number, not `(b)0`).
 
 For example, the following are all illegal:
 
@@ -338,7 +359,9 @@ Note that, unlike Bare Suffix Type Annotations
 ({{number}}) formats (hexadecimal, decimal, octal, and binary). For example,
 `0x1234#u32` is valid.
 
-### Reserved Type Annotations for Numbers Without Decimal Parts
+### 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.
@@ -364,7 +387,7 @@ Platform-dependent integer types, both signed and unsigned:
 - `isize`
 - `usize`
 
-### Reserved Type Annotations for Numbers With Decimal Parts
+#### For Numbers With Decimal Parts
 
 IEEE 754 floating point numbers, both single (32) and double (64) precision:
 
@@ -376,7 +399,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.
@@ -404,16 +427,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 123u8
-node 0#b 20b 50GiB
-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
@@ -1105,8 +1118,8 @@ sign := '+' | '-'
 
 bare-type-suffix := bare-type-suffix-initial identifier-char*
 bare-type-suffix-initial := identifier-char
-    - '.' - ',' - '_'
-    - (('e' | 'E') sign? digit)
+    - '.' - ','
+    - (('e' | 'E') (sign | digit))
 explicit-type-suffix := '#' identifier-string
 
 hex := sign? '0x' hex-digit (hex-digit | '_')*

tests/test_cases/expected_kdl/suffix_type_bare_underscore.kdl

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