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

Script updating gh-pages from b5e590c. [ci skip]

This commit is contained in:
ID Bot 2025-04-18 04:07:23 +00:00
parent 9a4556de59
commit 95809be393
2 changed files with 152 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
zkat/suffixes/draft-marchan-kdl2.html
View File

@ -26,7 +26,7 @@ oficial version of the language, see https://kdl.dev/spec.
<meta content="draft-marchan-kdl2-latest" name="ietf.draft"> <meta content="draft-marchan-kdl2-latest" name="ietf.draft">
<!-- Generator version information: <!-- Generator version information:
xml2rfc 3.28.1 xml2rfc 3.28.1
Python 3.12.9 Python 3.12.10
ConfigArgParse 1.7 ConfigArgParse 1.7
google-i18n-address 3.1.1 google-i18n-address 3.1.1
intervaltree 3.1.0 intervaltree 3.1.0
@ -1071,7 +1071,7 @@ svg :is([fill="white"], [fill^="#fff"]) {
<dd class="workgroup">KDL Community</dd> <dd class="workgroup">KDL Community</dd>
<dt class="label-published">Published:</dt> <dt class="label-published">Published:</dt>
<dd class="published"> <dd class="published">
<time datetime="2025-04-17" class="published">17 April 2025</time> <time datetime="2025-04-18" class="published">18 April 2025</time>
</dd> </dd>
<dt class="label-authors">Authors:</dt> <dt class="label-authors">Authors:</dt>
<dd class="authors"> <dd class="authors">
@ -1184,13 +1184,13 @@ https://creativecommons.org/licenses/by-sa/4.0/<a href="#section-note.2-1" class
<p id="section-toc.1-1.3.2.8.2.1.1"><a href="#section-3.8.1" class="auto internal xref">3.8.1</a>.  <a href="#name-suffix-type-annotation" class="internal xref">Suffix Type Annotation</a></p> <p id="section-toc.1-1.3.2.8.2.1.1"><a href="#section-3.8.1" class="auto internal xref">3.8.1</a>.  <a href="#name-suffix-type-annotation" class="internal xref">Suffix Type Annotation</a></p>
</li> </li>
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.2"> <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.2">
<p id="section-toc.1-1.3.2.8.2.2.1"><a href="#section-3.8.2" class="auto internal xref">3.8.2</a>.  <a href="#name-reserved-type-annotations-f" class="internal xref">Reserved Type Annotations for Numbers Without Decimals</a></p> <p id="section-toc.1-1.3.2.8.2.2.1"><a href="#section-3.8.2" class="auto internal xref">3.8.2</a>.  <a href="#name-reserved-type-annotations-f" class="internal xref">Reserved Type Annotations for Numbers Without Decimal Parts</a></p>
</li> </li>
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.3"> <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.3">
<p id="section-toc.1-1.3.2.8.2.3.1"><a href="#section-3.8.3" class="auto internal xref">3.8.3</a>.  <a href="#name-reserved-type-annotations-fo" class="internal xref">Reserved Type Annotations for Numbers With Decimals:</a></p> <p id="section-toc.1-1.3.2.8.2.3.1"><a href="#section-3.8.3" class="auto internal xref">3.8.3</a>.  <a href="#name-reserved-type-annotations-fo" class="internal xref">Reserved Type Annotations for Numbers With Decimal Parts</a></p>
</li> </li>
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.4"> <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.4">
<p id="section-toc.1-1.3.2.8.2.4.1"><a href="#section-3.8.4" class="auto internal xref">3.8.4</a>.  <a href="#name-reserved-type-annotations-for" class="internal xref">Reserved Type Annotations for Strings:</a></p> <p id="section-toc.1-1.3.2.8.2.4.1"><a href="#section-3.8.4" class="auto internal xref">3.8.4</a>.  <a href="#name-reserved-type-annotations-for" class="internal xref">Reserved Type Annotations for Strings</a></p>
</li> </li>
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.5"> <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3.2.8.2.5">
<p id="section-toc.1-1.3.2.8.2.5.1"><a href="#section-3.8.5" class="auto internal xref">3.8.5</a>.  <a href="#name-examples" class="internal xref">Examples</a></p> <p id="section-toc.1-1.3.2.8.2.5.1"><a href="#section-3.8.5" class="auto internal xref">3.8.5</a>.  <a href="#name-examples" class="internal xref">Examples</a></p>
@ -1562,59 +1562,76 @@ about how to interpret a value.<a href="#section-3.8-3" class="pilcrow">¶</a></
<h4 id="name-suffix-type-annotation"> <h4 id="name-suffix-type-annotation">
<a href="#section-3.8.1" class="section-number selfRef">3.8.1. </a><a href="#name-suffix-type-annotation" class="section-name selfRef">Suffix Type Annotation</a> <a href="#section-3.8.1" class="section-number selfRef">3.8.1. </a><a href="#name-suffix-type-annotation" class="section-name selfRef">Suffix Type Annotation</a>
</h4> </h4>
<p id="section-3.8.1-1">When a (<a href="#value" class="auto internal xref">Section 3.7</a>) is a (<a href="#number" class="auto internal xref">Section 3.14</a>), it's possible to attach the type <p id="section-3.8.1-1">When a Value (<a href="#value" class="auto internal xref">Section 3.7</a>) is a Number (<a href="#number" class="auto internal xref">Section 3.14</a>), it's possible to attach the
annotation as a "suffix", instead of prepending it between <code>(</code> and <code>)</code>. This type annotation as a "suffix", instead of prepending it between <code>(</code> and <code>)</code>.
makes it possible to, for example, write <code>10px</code>, <code>10.5%</code>, <code>512GiB</code>, etc., which This makes it possible to, for example, write <code>10px</code>, <code>10.5%</code>, <code>512GiB</code>, etc.,
are equivalent to <code>(px)10</code>, <code>(%)5</code>, and <code>(GiB)512</code>, respectively.<a href="#section-3.8.1-1" class="pilcrow"></a></p> which are equivalent to <code>(px)10</code>, <code>(%)5</code>, and <code>(GiB)512</code>, respectively.<a href="#section-3.8.1-1" class="pilcrow"></a></p>
<p id="section-3.8.1-2">Most suffixes can be appended directly to the number (a <p id="section-3.8.1-2">There are two kinds of Suffix Type Annotations (<a href="#suffix-type-annotation" class="auto internal xref">Section 3.8.1</a>)
(<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)), as shown in the previous paragraph. To avoid available: Bare Suffix Type Annotations (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)s and
parsing ambiguity, there are some restrictions on this; an Explicit Suffix Type Annotations (<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>).<a href="#section-3.8.1-2" class="pilcrow"></a></p>
(<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>) avoids all these restrictions by using an <p id="section-3.8.1-3">Most suffixes can be appended directly to the number (a Bare Suffix Type
additional <code>#</code> to explicitly indicate it. For example, <code>10.0u8</code> is invalid, but Annotation (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)), as shown in the previous
<code>10.0#u8</code> is valid and equivalent to <code>(u8)10.0</code>. See paragraph. To avoid parsing ambiguity, there are some restrictions on this; an
(<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>) for the full list of restrictions.<a href="#section-3.8.1-2" class="pilcrow"></a></p> Explicit Suffix Type Annotation (<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>) avoids all
<p id="section-3.8.1-3">An implementation that finds BOTH a parenthesized and a suffix these restrictions by using an additional <code>#</code> to explicitly indicate it. For
(<a href="#type-annotation" class="auto internal xref">Section 3.8</a>) on the same (<a href="#number" class="auto internal xref">Section 3.14</a>) MUST yield a syntax error.<a href="#section-3.8.1-3" class="pilcrow"></a></p> example, <code>10.0u8</code> is invalid, but <code>10.0#u8</code> is valid and equivalent to
<p id="section-3.8.1-4">Suffixes MUST BE plain (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>)s. No other (<a href="#string" class="auto internal xref">Section 3.9</a>) is <code>(u8)10.0</code>. See Bare Suffix Type Annotation (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)
acceptable.<a href="#section-3.8.1-4" class="pilcrow"></a></p> for the full list of restrictions.<a href="#section-3.8.1-3" class="pilcrow"></a></p>
<p id="section-3.8.1-5">There are two kinds of (<a href="#suffix-type-annotation" class="auto internal xref">Section 3.8.1</a>) available: <p id="section-3.8.1-4">An implementation that finds BOTH a parenthesized (<a href="#type-annotation" class="auto internal xref">Section 3.8</a>) and a
(<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)s and (<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>).<a href="#section-3.8.1-5" class="pilcrow"></a></p> Suffix Type Annotation (<a href="#suffix-type-annotation" class="auto internal xref">Section 3.8.1</a>) on the same Number
(<a href="#number" class="auto internal xref">Section 3.14</a>) MUST yield a syntax error.<a href="#section-3.8.1-4" class="pilcrow"></a></p>
<p id="section-3.8.1-5">Suffixes MUST BE plain Identifier Strings (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>). No other
String (<a href="#string" class="auto internal xref">Section 3.9</a>) syntax is acceptable.<a href="#section-3.8.1-5" class="pilcrow"></a></p>
<div id="bare-suffix-type-annotation"> <div id="bare-suffix-type-annotation">
<section id="section-3.8.1.1"> <section id="section-3.8.1.1">
<h5 id="name-bare-suffix-type-annotation"> <h5 id="name-bare-suffix-type-annotation">
<a href="#section-3.8.1.1" class="section-number selfRef">3.8.1.1. </a><a href="#name-bare-suffix-type-annotation" class="section-name selfRef">Bare Suffix Type Annotation</a> <a href="#section-3.8.1.1" class="section-number selfRef">3.8.1.1. </a><a href="#name-bare-suffix-type-annotation" class="section-name selfRef">Bare Suffix Type Annotation</a>
</h5> </h5>
<p id="section-3.8.1.1-1">When a (<a href="#value" class="auto internal xref">Section 3.7</a>) is a decimal (<a href="#number" class="auto internal xref">Section 3.14</a>) WITHOUT exponential syntax (<code>1e+5</code> <p id="section-3.8.1.1-1">When a Value (<a href="#value" class="auto internal xref">Section 3.7</a>) is a decimal Number (<a href="#number" class="auto internal xref">Section 3.14</a>) WITHOUT exponential
etc) (and ONLY a decimal: that is, numbers which do NOT have a <code>0b</code>/<code>0o</code>/<code>0x</code> syntax (<code>1e+5</code> etc) (and ONLY a decimal. That is, numbers which do NOT have a
prefix), it's possible to attach the type annotation as a suffix directly to the <code>0b</code>/<code>0o</code>/<code>0x</code> prefix with an optional sign), it's possible to append the type
number, without any additional syntax.<a href="#section-3.8.1.1-1" class="pilcrow"></a></p> annotation as a suffix directly to the number, without any additional syntax.<a href="#section-3.8.1.1-1" class="pilcrow"></a></p>
<p id="section-3.8.1.1-2">They also come with some additional rules (like only being available for <p id="section-3.8.1.1-2">To remove further ambiguity, on top of not being available for non-decimal
decimals), in order to prevent potential ambiguity or footguns with the syntax. prefixes, and for decimals with exponent parts, the suffix Identifier String
This is generally acceptable, as type annotations in particular tend to be (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>) itself MUST NOT start with any of <code>.</code>, <code>,</code>, or <code>_</code>, as
application-defined and limited in scope, rather than arbitrary user data. In well as <code>[eE][-+]?[0-9]?</code> as part of the exponential restriction above. Note the
designing this feature, it was determined that the value for various real-world optional digit, which is added to prevent typo ambiguity.<a href="#section-3.8.1.1-2" class="pilcrow"></a></p>
DSLs outweighed the complexity of the following rules.<a href="#section-3.8.1.1-2" class="pilcrow"></a></p> <p id="section-3.8.1.1-3">For example, the following are all illegal:<a href="#section-3.8.1.1-3" class="pilcrow"></a></p>
<p id="section-3.8.1.1-3">As such, to remove ambiguity, the suffix (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>) MUST NOT start
with any of the following patterns, all of which MUST yield syntax errors (if
they can be distinguished from other syntaxes at all):<a href="#section-3.8.1.1-3" class="pilcrow"></a></p>
<ul class="normal"> <ul class="normal">
<li class="normal" id="section-3.8.1.1-4.1"> <li class="normal" id="section-3.8.1.1-4.1">
<p id="section-3.8.1.1-4.1.1"><code>.</code>, <code>,</code>, or <code>_</code><a href="#section-3.8.1.1-4.1.1" class="pilcrow"></a></p> <p id="section-3.8.1.1-4.1.1"><code>10,000</code> (suffix would start with <code>,</code>)<a href="#section-3.8.1.1-4.1.1" class="pilcrow"></a></p>
</li> </li>
<li class="normal" id="section-3.8.1.1-4.2"> <li class="normal" id="section-3.8.1.1-4.2">
<p id="section-3.8.1.1-4.2.1"><code>[eE][+-]?[0-9]</code> (to disambiguate exponentials)<a href="#section-3.8.1.1-4.2.1" class="pilcrow"></a></p> <p id="section-3.8.1.1-4.2.1"><code>10e0n</code> (suffix on an exponential)<a href="#section-3.8.1.1-4.2.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-4.3">
<p id="section-3.8.1.1-4.3.1"><code>0xyz</code> (starts with reserved hexadecimal prefix)<a href="#section-3.8.1.1-4.3.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-4.4">
<p id="section-3.8.1.1-4.4.1"><code>0b</code> (starts with reserved binary prefix)<a href="#section-3.8.1.1-4.4.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-4.5">
<p id="section-3.8.1.1-4.5.1"><code>5e+oops</code> (looks too close to an exponential)<a href="#section-3.8.1.1-4.5.1" class="pilcrow"></a></p>
</li>
</ul>
<p id="section-3.8.1.1-5">Whereas the following are all legal:<a href="#section-3.8.1.1-5" class="pilcrow"></a></p>
<ul class="normal">
<li class="normal" id="section-3.8.1.1-6.1">
<p id="section-3.8.1.1-6.1.1"><code>0u8</code> (aka <code>(u8)0</code>)<a href="#section-3.8.1.1-6.1.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-6.2">
<p id="section-3.8.1.1-6.2.1"><code>5em</code> (aka <code>(em)5</code>. The <code>e</code> is not followed by a digit.)<a href="#section-3.8.1.1-6.2.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-6.3">
<p id="section-3.8.1.1-6.3.1"><code>1xyz</code> (aka <code>(xyz)1</code>. No longer starts with <code>0</code> as above.)<a href="#section-3.8.1.1-6.3.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="section-3.8.1.1-6.4">
<p id="section-3.8.1.1-6.4.1"><code>20b</code> (aka <code>(b)20</code>, "20 bytes". No longer starts with just <code>0</code> as above.)<a href="#section-3.8.1.1-6.4.1" class="pilcrow"></a></p>
</li> </li>
</ul> </ul>
<p id="section-3.8.1.1-5">For example, <code>10,000</code> is illegal. <code>10e0n</code> is illegal, but <code>10e0</code> is a legal
<em>decimal number using exponential syntax</em>, <strong>not</strong> equivalent to <code>(e0)10</code>.
Additionally, note that since bare suffixes are only legal on <em>decimals</em>, <code>0u8</code>
is legal, but <code>0xs</code> is <em>not</em>, since hexadecimals are determined by their
prefixes. Similarly, <code>1xs</code> <em>is</em> legal, and equivalent to <code>(xs)1</code>.<a href="#section-3.8.1.1-5" class="pilcrow"></a></p>
<p id="section-3.8.1.1-6">All other (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>)s can be safely appended to decimal numbers, so
long as the decimal does not include an exponential component.<a href="#section-3.8.1.1-6" class="pilcrow"></a></p>
<p id="section-3.8.1.1-7">If the desired suffix would violate any of the above rules, either regular <p id="section-3.8.1.1-7">If the desired suffix would violate any of the above rules, either regular
parenthetical (<a href="#type-annotation" class="auto internal xref">Section 3.8</a>)s or (<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>)s parenthetical Type Annotations (<a href="#type-annotation" class="auto internal xref">Section 3.8</a>) or Explicit Suffix Type
may be used.<a href="#section-3.8.1.1-7" class="pilcrow"></a></p> Annotations (<a href="#explicit-suffix-type-annotation" class="auto internal xref">Section 3.8.1.2</a>) may be used.<a href="#section-3.8.1.1-7" class="pilcrow"></a></p>
</section> </section>
</div> </div>
<div id="explicit-suffix-type-annotation"> <div id="explicit-suffix-type-annotation">
@ -1622,22 +1639,24 @@ may be used.<a href="#section-3.8.1.1-7" class="pilcrow">¶</a></p>
<h5 id="name-explicit-suffix-type-annota"> <h5 id="name-explicit-suffix-type-annota">
<a href="#section-3.8.1.2" class="section-number selfRef">3.8.1.2. </a><a href="#name-explicit-suffix-type-annota" class="section-name selfRef">Explicit Suffix Type Annotation</a> <a href="#section-3.8.1.2" class="section-number selfRef">3.8.1.2. </a><a href="#name-explicit-suffix-type-annota" class="section-name selfRef">Explicit Suffix Type Annotation</a>
</h5> </h5>
<p id="section-3.8.1.2-1">Any (<a href="#number" class="auto internal xref">Section 3.14</a>) may have a <code>#</code> appended to it, followed by any valid <p id="section-3.8.1.2-1">Any Number (<a href="#number" class="auto internal xref">Section 3.14</a>) may have a <code>#</code> appended to it, followed by any valid
(<a href="#identifier-string" class="auto internal xref">Section 3.10</a>). This is an explicit (<a href="#suffix-type-annotation" class="auto internal xref">Section 3.8.1</a>) syntax Identifier String (<a href="#identifier-string" class="auto internal xref">Section 3.10</a>). This is an Explicit Suffix Type
without any of the relatively complex requirements of Annotation (<a href="#suffix-type-annotation" class="auto internal xref">Section 3.8.1</a>) syntax without any of the added
(<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>), which can be a useful escape hatch. For restrictions of Bare Suffix Type Annotations (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>),
example: <code>0#b1</code> is invalid syntax without the <code>#</code> prefix.<a href="#section-3.8.1.2-1" class="pilcrow"></a></p> which can be a useful escape hatch. For example: <code>0#b</code> is invalid syntax without
<p id="section-3.8.1.2-2">Note again that, unlike (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>)s, Explicit Suffixes the <code>#</code> prefix.<a href="#section-3.8.1.2-1" class="pilcrow"></a></p>
may be used with ALL (<a href="#number" class="auto internal xref">Section 3.14</a>) formats (hexadecimal, decimal, octal, and <p id="section-3.8.1.2-2">Note that, unlike Bare Suffix Type Annotations
binary). For example, <code>0x1234#u32</code> is valid.<a href="#section-3.8.1.2-2" class="pilcrow"></a></p> (<a href="#bare-suffix-type-annotation" class="auto internal xref">Section 3.8.1.1</a>), Explicit Suffixes may be used with ALL Number
(<a href="#number" class="auto internal xref">Section 3.14</a>) formats (hexadecimal, decimal, octal, and binary). For example,
<code>0x1234#u32</code> is valid.<a href="#section-3.8.1.2-2" class="pilcrow"></a></p>
</section> </section>
</div> </div>
</section> </section>
</div> </div>
<div id="reserved-type-annotations-for-numbers-without-decimals"> <div id="reserved-type-annotations-for-numbers-without-decimal-parts">
<section id="section-3.8.2"> <section id="section-3.8.2">
<h4 id="name-reserved-type-annotations-f"> <h4 id="name-reserved-type-annotations-f">
<a href="#section-3.8.2" class="section-number selfRef">3.8.2. </a><a href="#name-reserved-type-annotations-f" class="section-name selfRef">Reserved Type Annotations for Numbers Without Decimals</a> <a href="#section-3.8.2" class="section-number selfRef">3.8.2. </a><a href="#name-reserved-type-annotations-f" class="section-name selfRef">Reserved Type Annotations for Numbers Without Decimal Parts</a>
</h4> </h4>
<p id="section-3.8.2-1">Additionally, the following type annotations MAY be recognized by KDL parsers <p id="section-3.8.2-1">Additionally, the following type annotations MAY be recognized by KDL parsers
and, if used, SHOULD interpret these types as follows.<a href="#section-3.8.2-1" class="pilcrow"></a></p> and, if used, SHOULD interpret these types as follows.<a href="#section-3.8.2-1" class="pilcrow"></a></p>
@ -1688,10 +1707,10 @@ and, if used, SHOULD interpret these types as follows.<a href="#section-3.8.2-1"
</ul> </ul>
</section> </section>
</div> </div>
<div id="reserved-type-annotations-for-numbers-with-decimals"> <div id="reserved-type-annotations-for-numbers-with-decimal-parts">
<section id="section-3.8.3"> <section id="section-3.8.3">
<h4 id="name-reserved-type-annotations-fo"> <h4 id="name-reserved-type-annotations-fo">
<a href="#section-3.8.3" class="section-number selfRef">3.8.3. </a><a href="#name-reserved-type-annotations-fo" class="section-name selfRef">Reserved Type Annotations for Numbers With Decimals:</a> <a href="#section-3.8.3" class="section-number selfRef">3.8.3. </a><a href="#name-reserved-type-annotations-fo" class="section-name selfRef">Reserved Type Annotations for Numbers With Decimal Parts</a>
</h4> </h4>
<p id="section-3.8.3-1">IEEE 754 floating point numbers, both single (32) and double (64) precision:<a href="#section-3.8.3-1" class="pilcrow"></a></p> <p id="section-3.8.3-1">IEEE 754 floating point numbers, both single (32) and double (64) precision:<a href="#section-3.8.3-1" class="pilcrow"></a></p>
<ul class="normal"> <ul class="normal">
@ -1716,7 +1735,7 @@ and, if used, SHOULD interpret these types as follows.<a href="#section-3.8.2-1"
<div id="reserved-type-annotations-for-strings"> <div id="reserved-type-annotations-for-strings">
<section id="section-3.8.4"> <section id="section-3.8.4">
<h4 id="name-reserved-type-annotations-for"> <h4 id="name-reserved-type-annotations-for">
<a href="#section-3.8.4" class="section-number selfRef">3.8.4. </a><a href="#name-reserved-type-annotations-for" class="section-name selfRef">Reserved Type Annotations for Strings:</a> <a href="#section-3.8.4" class="section-number selfRef">3.8.4. </a><a href="#name-reserved-type-annotations-for" class="section-name selfRef">Reserved Type Annotations for Strings</a>
</h4> </h4>
<ul class="normal"> <ul class="normal">
<li class="normal" id="section-3.8.4-1.1"> <li class="normal" id="section-3.8.4-1.1">
@ -1802,8 +1821,8 @@ and, if used, SHOULD interpret these types as follows.<a href="#section-3.8.2-1"
</h4> </h4>
<div class="lang-kdl sourcecode" id="section-3.8.5-1"> <div class="lang-kdl sourcecode" id="section-3.8.5-1">
<pre> <pre>
node (u8)123 node 123u8
node 123#i64 node 0#b 20b 50GiB
node prop=(regex).* node prop=(regex).*
(published)date "1970-01-01" (published)date "1970-01-01"
(contributor)person name="Foo McBar" (contributor)person name="Foo McBar"

133
zkat/suffixes/draft-marchan-kdl2.txt
View File

@ -5,7 +5,7 @@
KDL Community K. Marchán KDL Community K. Marchán
Microsoft Microsoft
KDL Contributors KDL Contributors
17 April 2025 18 April 2025
The KDL Document Language The KDL Document Language
@ -61,9 +61,11 @@ Table of Contents
3.7. Value 3.7. Value
3.8. Type Annotation 3.8. Type Annotation
3.8.1. Suffix Type Annotation 3.8.1. Suffix Type Annotation
3.8.2. Reserved Type Annotations for Numbers Without Decimals 3.8.2. Reserved Type Annotations for Numbers Without Decimal
3.8.3. Reserved Type Annotations for Numbers With Decimals: Parts
3.8.4. Reserved Type Annotations for Strings: 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.5. Examples
3.9. String 3.9. String
3.10. Identifier String 3.10. Identifier String
@ -306,80 +308,89 @@ Table of Contents
3.8.1. Suffix Type Annotation 3.8.1. Suffix Type Annotation
When a (Section 3.7) is a (Section 3.14), it's possible to attach the When a Value (Section 3.7) is a Number (Section 3.14), it's possible
type annotation as a "suffix", instead of prepending it between ( and to attach the type annotation as a "suffix", instead of prepending it
). This makes it possible to, for example, write 10px, 10.5%, between ( and ). This makes it possible to, for example, write 10px,
512GiB, etc., which are equivalent to (px)10, (%)5, and (GiB)512, 10.5%, 512GiB, etc., which are equivalent to (px)10, (%)5, and
respectively. (GiB)512, respectively.
Most suffixes can be appended directly to the number (a There are two kinds of Suffix Type Annotations (Section 3.8.1)
(Section 3.8.1.1)), as shown in the previous paragraph. To avoid available: Bare Suffix Type Annotations (Section 3.8.1.1)s and
parsing ambiguity, there are some restrictions on this; an Explicit Suffix Type Annotations (Section 3.8.1.2).
(Section 3.8.1.2) avoids all these restrictions by using an
additional # to explicitly indicate it. For example, 10.0u8 is Most suffixes can be appended directly to the number (a Bare Suffix
invalid, but 10.0#u8 is valid and equivalent to (u8)10.0. See 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. (Section 3.8.1.1) for the full list of restrictions.
An implementation that finds BOTH a parenthesized and a suffix An implementation that finds BOTH a parenthesized (Section 3.8) and a
(Section 3.8) on the same (Section 3.14) MUST yield a syntax error. Suffix Type Annotation (Section 3.8.1) on the same Number
(Section 3.14) MUST yield a syntax error.
Suffixes MUST BE plain (Section 3.10)s. No other (Section 3.9) is Suffixes MUST BE plain Identifier Strings (Section 3.10). No other
acceptable. String (Section 3.9) syntax is acceptable.
There are two kinds of (Section 3.8.1) available: (Section 3.8.1.1)s
and (Section 3.8.1.2).
3.8.1.1. Bare Suffix Type Annotation 3.8.1.1. Bare Suffix Type Annotation
When a (Section 3.7) is a decimal (Section 3.14) WITHOUT exponential When a Value (Section 3.7) is a decimal Number (Section 3.14) WITHOUT
syntax (1e+5 etc) (and ONLY a decimal: that is, numbers which do NOT exponential syntax (1e+5 etc) (and ONLY a decimal. That is, numbers
have a 0b/0o/0x prefix), it's possible to attach the type annotation which do NOT have a 0b/0o/0x prefix with an optional sign), it's
as a suffix directly to the number, without any additional syntax. possible to append the type annotation as a suffix directly to the
number, without any additional syntax.
They also come with some additional rules (like only being available To remove further ambiguity, on top of not being available for non-
for decimals), in order to prevent potential ambiguity or footguns decimal prefixes, and for decimals with exponent parts, the suffix
with the syntax. This is generally acceptable, as type annotations Identifier String (Section 3.10) itself MUST NOT start with any of .,
in particular tend to be application-defined and limited in scope, ,, or _, as well as [eE][-+]?[0-9]? as part of the exponential
rather than arbitrary user data. In designing this feature, it was restriction above. Note the optional digit, which is added to
determined that the value for various real-world DSLs outweighed the prevent typo ambiguity.
complexity of the following rules.
As such, to remove ambiguity, the suffix (Section 3.10) MUST NOT For example, the following are all illegal:
start with any of the following patterns, all of which MUST yield
syntax errors (if they can be distinguished from other syntaxes at
all):
* ., ,, or _ * 10,000 (suffix would start with ,)
* [eE][+-]?[0-9] (to disambiguate exponentials) * 10e0n (suffix on an exponential)
For example, 10,000 is illegal. 10e0n is illegal, but 10e0 is a legal * 0xyz (starts with reserved hexadecimal prefix)
_decimal number using exponential syntax_, *not* equivalent to
(e0)10. Additionally, note that since bare suffixes are only legal
on _decimals_, 0u8 is legal, but 0xs is _not_, since hexadecimals are
determined by their prefixes. Similarly, 1xs _is_ legal, and
equivalent to (xs)1.
All other (Section 3.10)s can be safely appended to decimal numbers, * 0b (starts with reserved binary prefix)
so long as the decimal does not include an exponential component.
* 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 If the desired suffix would violate any of the above rules, either
regular parenthetical (Section 3.8)s or (Section 3.8.1.2)s may be regular parenthetical Type Annotations (Section 3.8) or Explicit
used. Suffix Type Annotations (Section 3.8.1.2) may be used.
3.8.1.2. Explicit Suffix Type Annotation 3.8.1.2. Explicit Suffix Type Annotation
Any (Section 3.14) may have a # appended to it, followed by any valid Any Number (Section 3.14) may have a # appended to it, followed by
(Section 3.10). This is an explicit (Section 3.8.1) syntax without any valid Identifier String (Section 3.10). This is an Explicit
any of the relatively complex requirements of (Section 3.8.1.1), Suffix Type Annotation (Section 3.8.1) syntax without any of the
which can be a useful escape hatch. For example: 0#b1 is invalid 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. syntax without the # prefix.
Note again that, unlike (Section 3.8.1.1)s, Explicit Suffixes may be Note that, unlike Bare Suffix Type Annotations (Section 3.8.1.1),
used with ALL (Section 3.14) formats (hexadecimal, decimal, octal, Explicit Suffixes may be used with ALL Number (Section 3.14) formats
and binary). For example, 0x1234#u32 is valid. (hexadecimal, decimal, octal, and binary). For example, 0x1234#u32
is valid.
3.8.2. Reserved Type Annotations for Numbers Without Decimals 3.8.2. Reserved Type Annotations for Numbers Without Decimal Parts
Additionally, the following type annotations MAY be recognized by KDL Additionally, the following type annotations MAY be recognized by KDL
parsers and, if used, SHOULD interpret these types as follows. parsers and, if used, SHOULD interpret these types as follows.
@ -414,7 +425,7 @@ Table of Contents
* usize * usize
3.8.3. Reserved Type Annotations for Numbers With Decimals: 3.8.3. Reserved Type Annotations for Numbers With Decimal Parts
IEEE 754 floating point numbers, both single (32) and double (64) IEEE 754 floating point numbers, both single (32) and double (64)
precision: precision:
@ -429,7 +440,7 @@ Table of Contents
* decimal128 * decimal128
3.8.4. Reserved Type Annotations for Strings: 3.8.4. Reserved Type Annotations for Strings
* date-time: ISO8601 date/time format. * date-time: ISO8601 date/time format.
@ -485,8 +496,8 @@ Table of Contents
3.8.5. Examples 3.8.5. Examples
node (u8)123 node 123u8
node 123#i64 node 0#b 20b 50GiB
node prop=(regex).* node prop=(regex).*
(published)date "1970-01-01" (published)date "1970-01-01"
(contributor)person name="Foo McBar" (contributor)person name="Foo McBar"