This commit is contained in:
zkat 2020-12-27 22:35:00 +00:00
parent 032aeea267
commit 6db35c8916
1 changed files with 54 additions and 68 deletions

View File

@ -56,26 +56,21 @@ Github repo. Feel free to jump in and give us your 2 cents!</p>
<h3>Basics</h3> <h3>Basics</h3>
<p>A KDL node is a node name, followed by zero or more &quot;arguments&quot;, and <p>A KDL node is a node name, followed by zero or more &quot;arguments&quot;, and
children.</p> children.</p>
<pre><code class="language-kdl">title &quot;Hello, World&quot; <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">title</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;Hello, World&quot;</span></span></code></pre>
</code></pre>
<p>You can also have multiple values in a single node!</p> <p>You can also have multiple values in a single node!</p>
<pre><code class="language-kdl">bookmarks 12 15 188 1234 <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">bookmarks</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">12</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">15</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">188</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">1234</span></span></code></pre>
</code></pre>
<p>Nodes can have properties.</p> <p>Nodes can have properties.</p>
<pre><code class="language-kdl">author &quot;Alex Monad&quot; email=&quot;alex@example.com&quot; active=true <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">author</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;Alex Monad&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #8FBCBB">email</span><span style="color: #ECEFF4">=</span><span style="color: #A3BE8C">&quot;alex@example.com&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #8FBCBB">active</span><span style="color: #ECEFF4">=</span><span style="color: #81A1C1">true</span></span></code></pre>
</code></pre>
<p>And they can have nested child nodes, too!</p> <p>And they can have nested child nodes, too!</p>
<pre><code class="language-kdl">contents { <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">contents</span><span style="color: #D8DEE9FF"> {</span></span>
section &quot;First section&quot; { <span class="line"><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">section</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;First section&quot;</span><span style="color: #D8DEE9FF"> {</span></span>
paragraph &quot;This is the first paragraph&quot; <span class="line"><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">paragraph</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;This is the first paragraph&quot;</span></span>
paragraph &quot;This is the second paragraph&quot; <span class="line"><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">paragraph</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;This is the second paragraph&quot;</span></span>
} <span class="line"><span style="color: #D8DEE9FF"> }</span></span>
} <span class="line"><span style="color: #D8DEE9FF">}</span></span></code></pre>
</code></pre>
<p>Nodes without children are terminated by a newline, a semicolon, or the end of <p>Nodes without children are terminated by a newline, a semicolon, or the end of
a file stream:</p> a file stream:</p>
<pre><code class="language-kdl">node1; node2; node3; <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">node1</span><span style="color: #D8DEE9FF">; </span><span style="color: #81A1C1">node2</span><span style="color: #D8DEE9FF">; </span><span style="color: #81A1C1">node3</span><span style="color: #D8DEE9FF">;</span></span></code></pre>
</code></pre>
<h3>Values</h3> <h3>Values</h3>
<p>KDL supports 4 data types:</p> <p>KDL supports 4 data types:</p>
<ul> <ul>
@ -86,18 +81,15 @@ a file stream:</p>
</ul> </ul>
<h4>Strings</h4> <h4>Strings</h4>
<p>It supports two different formats for string input: escaped and raw.</p> <p>It supports two different formats for string input: escaped and raw.</p>
<pre><code class="language-kdl">node &quot;this\nhas\tescapes&quot; <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">node</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;this</span><span style="color: #EBCB8B">\n</span><span style="color: #A3BE8C">has</span><span style="color: #EBCB8B">\t</span><span style="color: #A3BE8C">escapes&quot;</span></span>
other r&quot;C:\Users\zkat\&quot; <span class="line"><span style="color: #81A1C1">other</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">r&quot;C:\Users\zkat\&quot;</span></span></code></pre>
</code></pre>
<p>Both types of string can be multiline as-is, without a different syntax:</p> <p>Both types of string can be multiline as-is, without a different syntax:</p>
<pre><code class="language-kdl">string &quot;my <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">string</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;my</span></span>
multiline <span class="line"><span style="color: #A3BE8C">multiline</span></span>
value&quot; <span class="line"><span style="color: #A3BE8C">value&quot;</span></span></code></pre>
</code></pre>
<p>And for raw strings, you can add any number of # after the r and the last &quot; to <p>And for raw strings, you can add any number of # after the r and the last &quot; to
disambiguate literal &quot; characters:</p> disambiguate literal &quot; characters:</p>
<pre><code class="language-kdl">other-raw r#&quot;hello&quot;world&quot;# <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">other-raw</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">r#&quot;hello&quot;world&quot;#</span></span></code></pre>
</code></pre>
<h4>Numbers</h4> <h4>Numbers</h4>
<p>There's 4 ways to represent numbers in KDL. KDL does not prescribe any <p>There's 4 ways to represent numbers in KDL. KDL does not prescribe any
representation for these numbers, and it's entirely up to individual representation for these numbers, and it's entirely up to individual
@ -105,69 +97,63 @@ implementations whether to represent all numbers with a single type, or to
have different representations for different forms.</p> have different representations for different forms.</p>
<p>KDL has regular decimal-radix numbers, with optional decimal part, as well as <p>KDL has regular decimal-radix numbers, with optional decimal part, as well as
an optional exponent.</p> an optional exponent.</p>
<pre><code class="language-kdl">num 1.234e-42 <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">num</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">1.234e-42</span></span></code></pre>
</code></pre>
<p>And using the appropriate prefix, you can also enter hexadecimal, octal, and <p>And using the appropriate prefix, you can also enter hexadecimal, octal, and
binary literals:</p> binary literals:</p>
<pre><code class="language-kdl">my-hex 0xdeadbeef <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">my-hex</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">0xdeadbeef</span></span>
my-octal 0o755 <span class="line"><span style="color: #81A1C1">my-octal</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">0o755</span></span>
my-binary 0b10101101 <span class="line"><span style="color: #81A1C1">my-binary</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">0b10101101</span></span></code></pre>
</code></pre>
<p>Finally, all numbers can have underscores to help readability:</p> <p>Finally, all numbers can have underscores to help readability:</p>
<pre><code class="language-kdl">bignum 1_000_000 <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">bignum</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">1_000_000</span></span></code></pre>
</code></pre>
<h3>Comments</h3> <h3>Comments</h3>
<p>KDL supports C-style comments, both line-based and multiline. Multiline <p>KDL supports C-style comments, both line-based and multiline. Multiline
comments can be nested.</p> comments can be nested.</p>
<pre><code class="language-kdl">// C style <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #616E88">// C style</span></span>
/* <span class="line"><span style="color: #616E88">/*</span></span>
C style multiline <span class="line"><span style="color: #616E88">C style multiline</span></span>
*/ <span class="line"><span style="color: #616E88">*/</span></span>
tag /*foo=true*/ bar=false <span class="line"><span style="color: #81A1C1">tag</span><span style="color: #D8DEE9FF"> </span><span style="color: #616E88">/*foo=true*/</span><span style="color: #D8DEE9FF"> </span><span style="color: #8FBCBB">bar</span><span style="color: #ECEFF4">=</span><span style="color: #81A1C1">false</span></span>
/*/* <span class="line"><span style="color: #616E88">/*/*</span></span>
hello <span class="line"><span style="color: #616E88">hello</span></span>
*/*/ <span class="line"><span style="color: #616E88">*/*/</span></span></code></pre>
</code></pre>
<p>On top of that, KDL supports <code>/-</code> &quot;slashdash&quot; comments, which can be used to <p>On top of that, KDL supports <code>/-</code> &quot;slashdash&quot; comments, which can be used to
comment out individual nodes, arguments, or children:</p> comment out individual nodes, arguments, or children:</p>
<pre><code class="language-kdl">// This entire node and its children are all commented out. <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #616E88">// This entire node and its children are all commented out.</span></span>
/-mynode &quot;foo&quot; key=1 { <span class="line"><span style="color: #616E88">/-mynode &quot;foo&quot; key=1 {</span></span>
a <span class="line"><span style="color: #616E88"> a</span></span>
b <span class="line"><span style="color: #616E88"> b</span></span>
c <span class="line"><span style="color: #616E88"> c</span></span>
} <span class="line"><span style="color: #616E88">}</span></span>
mynode /-&quot;commented&quot; &quot;not commented&quot; /-key=&quot;value&quot; /-{ <span class="line"><span style="color: #81A1C1">mynode</span><span style="color: #D8DEE9FF"> </span><span style="color: #616E88">/-&quot;commented&quot; </span><span style="color: #A3BE8C">&quot;not commented&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #616E88">/-key=&quot;value&quot; /-{</span></span>
a <span class="line"><span style="color: #616E88"> a</span></span>
b <span class="line"><span style="color: #616E88"> b</span></span>
} <span class="line"><span style="color: #616E88">}</span></span></code></pre>
</code></pre>
<h3>More Details</h3> <h3>More Details</h3>
<pre><code class="language-kdl">// Nodes can be separated into multiple lines <pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #616E88">// Nodes can be separated into multiple lines</span></span>
title \ <span class="line"><span style="color: #81A1C1">title</span><span style="color: #D8DEE9FF"> \</span></span>
&quot;Some title&quot; <span class="line"><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;Some title&quot;</span></span>
// Files must be utf8 encoded! <span class="line"><span style="color: #616E88">// Files must be utf8 encoded!</span></span>
smile &quot;😁&quot; <span class="line"><span style="color: #81A1C1">smile</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;😁&quot;</span></span>
// Instead of anonymous nodes, nodes and properties can be wrapped <span class="line"><span style="color: #616E88">// Instead of anonymous nodes, nodes and properties can be wrapped</span></span>
// in &quot;&quot; for arbitrary node names. <span class="line"><span style="color: #616E88">// in &quot;&quot; for arbitrary node names.</span></span>
&quot;!@#$@$%Q#$%~@!40&quot; &quot;1.2.3&quot; &quot;!!!!!&quot;=true <span class="line"><span style="color: #A3BE8C">&quot;!@#$@$%Q#$%~@!40&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;1.2.3&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;!!!!!&quot;</span><span style="color: #D8DEE9FF">=</span><span style="color: #81A1C1">true</span></span>
// The following is a legal bare identifier: <span class="line"><span style="color: #616E88">// The following is a legal bare identifier:</span></span>
foo123~!@#$%^&amp;*.:'|/?+ &quot;weeee&quot; <span class="line"><span style="color: #81A1C1">foo123~!@#$%^&amp;*.</span><span style="color: #D8DEE9FF">:&#39;</span><span style="color: #81A1C1">|/</span><span style="color: #D8DEE9FF">?</span><span style="color: #81A1C1">+</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;weeee&quot;</span></span>
// And you can also use unicode! <span class="line"><span style="color: #616E88">// And you can also use unicode!</span></span>
ノード お名前=&quot;☜(゚ヮ゚☜)&quot; <span class="line"><span style="color: #81A1C1">ノード</span><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">お名前</span><span style="color: #D8DEE9FF"></span><span style="color: #A3BE8C">&quot;☜(゚ヮ゚☜)&quot;</span></span>
// kdl specifically allows properties and values to be <span class="line"><span style="color: #616E88">// kdl specifically allows properties and values to be</span></span>
// interspersed with each other, much like CLI commands. <span class="line"><span style="color: #616E88">// interspersed with each other, much like CLI commands.</span></span>
foo bar=true &quot;baz&quot; quux=false 1 2 3 <span class="line"><span style="color: #81A1C1">foo</span><span style="color: #D8DEE9FF"> </span><span style="color: #8FBCBB">bar</span><span style="color: #ECEFF4">=</span><span style="color: #81A1C1">true</span><span style="color: #D8DEE9FF"> </span><span style="color: #A3BE8C">&quot;baz&quot;</span><span style="color: #D8DEE9FF"> </span><span style="color: #8FBCBB">quux</span><span style="color: #ECEFF4">=</span><span style="color: #81A1C1">false</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">1</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">2</span><span style="color: #D8DEE9FF"> </span><span style="color: #B48EAD">3</span></span></code></pre>
</code></pre>
</section> </section>
</main> </main>
</body> </body>