diff --git a/zkat/suffixes/draft-marchan-kdl2.html b/zkat/suffixes/draft-marchan-kdl2.html index 9dc5863..5a73934 100644 --- a/zkat/suffixes/draft-marchan-kdl2.html +++ b/zkat/suffixes/draft-marchan-kdl2.html @@ -1181,19 +1181,16 @@ https://creativecommons.org/licenses/by-sa/4.0/3.8.  Type Annotation

@@ -1547,286 +1544,308 @@ Type Annotation (Section 3

3.8. Type Annotation

-

A type annotation is a prefix to any Node Name (Section 3.2) or Value (Section 3.7) 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 (Section 3.9) in it. It may contain Whitespace after the ( and before -the ), and may be separated from its target by Whitespace.

-

KDL does not specify any restrictions on what implementations might do with +

A type annotation is a String (Section 3.9) value attached to any Node Name +(Section 3.2) or Value (Section 3.7) 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.

-
-
-

-3.8.1. Suffix Type Annotation -

-

When a Value (Section 3.7) is a Number (Section 3.14), 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.

-

There are two kinds of Suffix Type Annotations (Section 3.8.1) -available: Bare Suffix Type Annotations (Section 3.8.1.1)s and -Explicit Suffix Type Annotations (Section 3.8.1.2).

-

Most suffixes can be appended directly to the number (a Bare Suffix Type -Annotation (Section 3.8.1.1)), as shown in the previous -paragraph. To avoid parsing ambiguity, there are some restrictions on this; an -Explicit Suffix Type Annotation (Section 3.8.1.2) avoids all -these restrictions by using an additional # to explicitly indicate it. For -example, 10.0u8 is invalid, but 10.0#u8 is valid and equivalent to -(u8)10.0. See Bare Suffix Type Annotation (Section 3.8.1.1) -for the full list of restrictions.

-

An implementation that finds BOTH a parenthesized (Section 3.8) and a -Suffix Type Annotation (Section 3.8.1) on the same Number -(Section 3.14) MUST yield a syntax error.

-

Suffixes MUST BE plain Identifier Strings (Section 3.10). No other -String (Section 3.9) syntax is acceptable.

-
-
-
-3.8.1.1. Bare Suffix Type Annotation -
-

When a Value (Section 3.7) is a decimal Number (Section 3.14) 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 -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 -(Section 3.10) 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.

-

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)

    -
    • -
-

Whereas the following are all legal:

-
    -
  • -

    0u8 (aka (u8)0)

    -
    • -
  • -

    5em (aka (em)5. The e is not followed by a digit.)

    -
    • -
  • -

    1xyz (aka (xyz)1. No longer starts with 0 as above.)

    -
    • -
  • -

    20b (aka (b)20, "20 bytes". No longer starts with just 0 as above.)

    -
    • -
-

If the desired suffix would violate any of the above rules, either regular -parenthetical Type Annotations (Section 3.8) or Explicit Suffix Type -Annotations (Section 3.8.1.2) may be used.

-
-
-
-
-
-3.8.1.2. Explicit Suffix Type Annotation -
-

Any Number (Section 3.14) may have a # appended to it, followed by any valid -Identifier String (Section 3.10). This is an Explicit Suffix Type -Annotation (Section 3.8.1) syntax without any of the added -restrictions of Bare Suffix Type Annotations (Section 3.8.1.1), -which can be a useful escape hatch. For example: 0#b is invalid syntax without -the # prefix.

-

Note that, unlike Bare Suffix Type Annotations -(Section 3.8.1.1), Explicit Suffixes may be used with ALL Number -(Section 3.14) formats (hexadecimal, decimal, octal, and binary). For example, -0x1234#u32 is valid.

-
-
-
-
-
-
-

-3.8.2. 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):

- -

Unsigned integers of various sizes (the number is the bit size):

- -

Platform-dependent integer types, both signed and unsigned:

- -
-
-
-
-

-3.8.3. Reserved Type Annotations for Numbers With Decimal Parts -

-

IEEE 754 floating point numbers, both single (32) and double (64) precision:

- -

IEEE 754-2008 decimal floating point numbers

- -
-
-
-
-

-3.8.4. Reserved Type Annotations for Strings -

- -
-
+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 (Section 3.8.4).

+

There are two kinds of Type Annotation syntaxes in KDL: Prefix Type Annotations +(Section 3.8.2) and Suffix Type Annotations +(Section 3.8.3).

-
+

-3.8.5. Examples +3.8.1. Examples

-
+
 node 123u8
 node 0#b 20b 50GiB
 node prop=(regex).*
 (published)date "1970-01-01"
 (contributor)person name="Foo McBar"
-
+ +
+
+
+
+
+

+3.8.2. Prefix Type Annotation +

+

Prefix Type Annotations are written as a set of ( and ) with a single String +(Section 3.9) 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.

+
+
+
+
+

+3.8.3. Suffix Type Annotation +

+

When a Value (Section 3.7) is a Number (Section 3.14), 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.

+

There are two kinds of Suffix Type Annotations (Section 3.8.3) +available: Bare Suffix Type Annotations (Section 3.8.3.1)s and +Explicit Suffix Type Annotations (Section 3.8.3.2).

+

Most suffixes can be appended directly to the number (a Bare Suffix Type +Annotation (Section 3.8.3.1)), as shown in the previous +paragraph. To avoid parsing ambiguity, there are some restrictions on this; an +Explicit Suffix Type Annotation (Section 3.8.3.2) avoids all +these restrictions by using an additional # to explicitly indicate it. For +example, 10.0u8 is invalid, but 10.0#u8 is valid and equivalent to +(u8)10.0. See Bare Suffix Type Annotation (Section 3.8.3.1) +for the full list of restrictions.

+

An implementation that finds BOTH a parenthesized (Section 3.8) and a +Suffix Type Annotation (Section 3.8.3) on the same Number +(Section 3.14) MUST yield a syntax error.

+

Suffixes MUST BE plain Identifier Strings (Section 3.10). No other +String (Section 3.9) syntax is acceptable.

+
+
+
+3.8.3.1. Bare Suffix Type Annotation +
+

When a Value (Section 3.7) is a decimal Number (Section 3.14) 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 +(Section 3.10) 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 (Section 3.14) prefix MUST yield a syntax error +(e.g. 0b is an incorrect binary number, not (b)0).

+

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)

    +
    • +
+

Whereas the following are all legal:

+
    +
  • +

    0u8 (aka (u8)0)

    +
    • +
  • +

    5em (aka (em)5. The e is not followed by a digit.)

    +
    • +
  • +

    1xyz (aka (xyz)1. No longer starts with 0 as above.)

    +
    • +
  • +

    20b (aka (b)20, "20 bytes". No longer starts with just 0 as above.)

    +
    • +
+

If the desired suffix would violate any of the above rules, either regular +parenthetical Type Annotations (Section 3.8) or Explicit Suffix Type +Annotations (Section 3.8.3.2) may be used.

+
+
+
+
+
+3.8.3.2. Explicit Suffix Type Annotation +
+

Any Number (Section 3.14) may have a # appended to it, followed by any valid +Identifier String (Section 3.10). This is an Explicit Suffix Type +Annotation (Section 3.8.3) syntax without any of the added +restrictions of Bare Suffix Type Annotations (Section 3.8.3.1), +which can be a useful escape hatch. For example: 0#b is invalid syntax without +the # prefix.

+

Note that, unlike Bare Suffix Type Annotations +(Section 3.8.3.1), Explicit Suffixes may be used with ALL Number +(Section 3.14) formats (hexadecimal, decimal, octal, and binary). For example, +0x1234#u32 is valid.

+
+
+
+
+
+
+

+3.8.4. Reserved Type Annotations +

+
+
+
+3.8.4.1. 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):

+
    +
  • +

    i8

    +
    • +
  • +

    i16

    +
    • +
  • +

    i32

    +
    • +
  • +

    i64

    +
    • +
  • +

    i128

    +
    • +
+

Unsigned integers of various sizes (the number is the bit size):

+
    +
  • +

    u8

    +
    • +
  • +

    u16

    +
    • +
  • +

    u32

    +
    • +
  • +

    u64

    +
    • +
  • +

    u128

    +
    • +
+

Platform-dependent integer types, both signed and unsigned:

+
    +
  • +

    isize

    +
    • +
  • +

    usize

    +
    • +
+
+
+
+
+
+3.8.4.2. For Numbers With Decimal Parts +
+

IEEE 754 floating point numbers, both single (32) and double (64) precision:

+
    +
  • +

    f32

    +
    • +
  • +

    f64

    +
    • +
+

IEEE 754-2008 decimal floating point numbers

+
    +
  • +

    decimal64

    +
    • +
  • +

    decimal128

    +
    • +
+
+
+
+
+
+3.8.4.3. For Strings +
+
    +
  • +

    date-time: ISO8601 date/time format.

    +
    • +
  • +

    time: "Time" section of ISO8601.

    +
    • +
  • +

    date: "Date" section of ISO8601.

    +
    • +
  • +

    duration: ISO8601 duration format.

    +
    • +
  • +

    decimal: IEEE 754-2008 decimal string format.

    +
    • +
  • +

    currency: ISO 4217 currency code.

    +
    • +
  • +

    country-2: ISO 3166-1 alpha-2 country code.

    +
    • +
  • +

    country-3: ISO 3166-1 alpha-3 country code.

    +
    • +
  • +

    country-subdivision: ISO 3166-2 country subdivision code.

    +
    • +
  • +

    email: RFC5322 email address.

    +
    • +
  • +

    idn-email: RFC6531 internationalized email address.

    +
    • +
  • +

    hostname: RFC1123 internet hostname (only ASCII segments)

    +
    • +
  • +

    idn-hostname: RFC5890 internationalized internet hostname +(only xn---prefixed ASCII "punycode" segments, or non-ASCII segments)

    +
    • +
  • +

    ipv4: RFC2673 dotted-quad IPv4 address.

    +
    • +
  • +

    ipv6: RFC2373 IPv6 address.

    +
    • +
  • +

    url: RFC3986 URI.

    +
    • +
  • +

    url-reference: RFC3986 URI Reference.

    +
    • +
  • +

    irl: RFC3987 Internationalized Resource Identifier.

    +
    • +
  • +

    irl-reference: RFC3987 Internationalized Resource Identifier Reference.

    +
    • +
  • +

    url-template: RFC6570 URI Template.

    +
    • +
  • +

    uuid: RFC4122 UUID.

    +
    • +
  • +

    regex: Regular expression. Specific patterns may be implementation-dependent.

    +
    • +
  • +

    base64: A Base64-encoded string, denoting arbitrary binary data.

    +
    • +
  • +

    base85: An Ascii85-encoded string, denoting arbitrary binary data.

    +
    • +
+
@@ -2955,8 +2974,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 | '_')* diff --git a/zkat/suffixes/draft-marchan-kdl2.txt b/zkat/suffixes/draft-marchan-kdl2.txt index fb3f8ae..c778796 100644 --- a/zkat/suffixes/draft-marchan-kdl2.txt +++ b/zkat/suffixes/draft-marchan-kdl2.txt @@ -60,13 +60,10 @@ Table of Contents 3.6.1. Example 3.7. Value 3.8. Type Annotation - 3.8.1. Suffix Type Annotation - 3.8.2. Reserved Type Annotations for Numbers Without Decimal - Parts - 3.8.3. Reserved Type Annotations for Numbers With Decimal - Parts - 3.8.4. Reserved Type Annotations for Strings - 3.8.5. Examples + 3.8.1. Examples + 3.8.2. Prefix Type Annotation + 3.8.3. Suffix Type Annotation + 3.8.4. Reserved Type Annotations 3.9. String 3.10. Identifier String 3.10.1. Non-initial characters @@ -293,20 +290,38 @@ Table of Contents 3.8. Type Annotation - A type annotation is a prefix to any Node Name (Section 3.2) or Value - (Section 3.7) 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 - (Section 3.9) 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 (Section 3.9) value attached to any + Node Name (Section 3.2) or Value (Section 3.7) 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. + to make decisions 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 (Section 3.8.4). -3.8.1. Suffix Type Annotation + There are two kinds of Type Annotation syntaxes in KDL: Prefix Type + Annotations (Section 3.8.2) and Suffix Type Annotations + (Section 3.8.3). + +3.8.1. Examples + + node 123u8 + node 0#b 20b 50GiB + node prop=(regex).* + (published)date "1970-01-01" + (contributor)person name="Foo McBar" + +3.8.2. Prefix Type Annotation + + Prefix Type Annotations are written as a set of ( and ) with a single + String (Section 3.9) 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. + +3.8.3. Suffix Type Annotation When a Value (Section 3.7) is a Number (Section 3.14), it's possible to attach the type annotation as a "suffix", instead of prepending it @@ -314,40 +329,42 @@ Table of Contents 10.5%, 512GiB, etc., which are equivalent to (px)10, (%)5, and (GiB)512, respectively. - There are two kinds of Suffix Type Annotations (Section 3.8.1) - available: Bare Suffix Type Annotations (Section 3.8.1.1)s and - Explicit Suffix Type Annotations (Section 3.8.1.2). + There are two kinds of Suffix Type Annotations (Section 3.8.3) + available: Bare Suffix Type Annotations (Section 3.8.3.1)s and + Explicit Suffix Type Annotations (Section 3.8.3.2). Most suffixes can be appended directly to the number (a Bare Suffix - Type Annotation (Section 3.8.1.1)), as shown in the previous + Type Annotation (Section 3.8.3.1)), as shown in the previous paragraph. To avoid parsing ambiguity, there are some restrictions - on this; an Explicit Suffix Type Annotation (Section 3.8.1.2) avoids + on this; an Explicit Suffix Type Annotation (Section 3.8.3.2) avoids all these restrictions by using an additional # to explicitly indicate it. For example, 10.0u8 is invalid, but 10.0#u8 is valid and equivalent to (u8)10.0. See Bare Suffix Type Annotation - (Section 3.8.1.1) for the full list of restrictions. + (Section 3.8.3.1) for the full list of restrictions. An implementation that finds BOTH a parenthesized (Section 3.8) and a - Suffix Type Annotation (Section 3.8.1) on the same Number + Suffix Type Annotation (Section 3.8.3) on the same Number (Section 3.14) MUST yield a syntax error. Suffixes MUST BE plain Identifier Strings (Section 3.10). No other String (Section 3.9) syntax is acceptable. -3.8.1.1. Bare Suffix Type Annotation +3.8.3.1. Bare Suffix Type Annotation When a Value (Section 3.7) is a decimal Number (Section 3.14) 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 + 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 (Section 3.10) 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 (Section 3.10) 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 (Section 3.14) prefix MUST yield a syntax error (e.g. 0b is an + incorrect binary number, not (b)0). For example, the following are all illegal: @@ -374,23 +391,25 @@ Table of Contents If the desired suffix would violate any of the above rules, either regular parenthetical Type Annotations (Section 3.8) or Explicit - Suffix Type Annotations (Section 3.8.1.2) may be used. + Suffix Type Annotations (Section 3.8.3.2) may be used. -3.8.1.2. Explicit Suffix Type Annotation +3.8.3.2. Explicit Suffix Type Annotation Any Number (Section 3.14) may have a # appended to it, followed by any valid Identifier String (Section 3.10). This is an Explicit - Suffix Type Annotation (Section 3.8.1) syntax without any of the - added restrictions of Bare Suffix Type Annotations (Section 3.8.1.1), + Suffix Type Annotation (Section 3.8.3) syntax without any of the + added restrictions of Bare Suffix Type Annotations (Section 3.8.3.1), which can be a useful escape hatch. For example: 0#b is invalid syntax without the # prefix. - Note that, unlike Bare Suffix Type Annotations (Section 3.8.1.1), + Note that, unlike Bare Suffix Type Annotations (Section 3.8.3.1), Explicit Suffixes may be used with ALL Number (Section 3.14) formats (hexadecimal, decimal, octal, and binary). For example, 0x1234#u32 is valid. -3.8.2. Reserved Type Annotations for Numbers Without Decimal Parts +3.8.4. Reserved Type Annotations + +3.8.4.1. 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. @@ -425,7 +444,7 @@ Table of Contents * usize -3.8.3. Reserved Type Annotations for Numbers With Decimal Parts +3.8.4.2. For Numbers With Decimal Parts IEEE 754 floating point numbers, both single (32) and double (64) precision: @@ -440,7 +459,7 @@ Table of Contents * decimal128 -3.8.4. Reserved Type Annotations for Strings +3.8.4.3. For Strings * date-time: ISO8601 date/time format. @@ -494,14 +513,6 @@ Table of Contents * base85: An Ascii85 (https://en.wikipedia.org/wiki/Ascii85)-encoded string, denoting arbitrary binary data. -3.8.5. Examples - - node 123u8 - node 0#b 20b 50GiB - node prop=(regex).* - (published)date "1970-01-01" - (contributor)person name="Foo McBar" - 3.9. String Strings in KDL represent textual UTF-8 Values (Section 3.7). A @@ -1247,8 +1258,8 @@ Table of Contents 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 | '_')*