Z Graph LanguageZGL is a human writable graph description language.Zola2021-03-12T14:01:00+00:00https://zg-lang.org/atom.xmlString Literals2021-03-12T14:01:00+00:002021-03-12T14:01:00+00:00https://zg-lang.org/decisions/string-literals/<h2 id="string-literals">String Literals</h2>
<p><strong>Context</strong>:
ZGL is a data interchange language (also known as a data exchange language).
Although it lacks string processing functions (by design), ZGL aims to make it easy to include strings in various styles, ranging from short strings to large blocks of text.</p>
<p><strong>Decision</strong>:
The ZGL grammar uses a custom string literal syntax.
As you can see on the <a href="/strings">strings documentation page</a>, ZGL provides six options that can be mixed and matched using flags (e.g. <code>-ecltaz</code>). Learning <strong>6</strong> options is easier than 2 ^ 6 = <strong>64</strong>. </p>
<p><strong>Consequences</strong>:
This requires changes to the ANTLR parser, syntax highlighters, and documentation.</p>
<p><strong>Status</strong>:
Accepted on 2021-03-10.
Updated on 2021-03-12.</p>
Backslash for string continuation2021-02-25T23:40:00+00:002021-02-25T23:45:00+00:00https://zg-lang.org/decisions/string-continuation/<h2 id="backslash-for-string-continuation">Backslash <code>\</code> for string continuation</h2>
<p><strong>Context</strong>:
Strings are frequently-used in ZGL.
Being able to break a string across multiple lines while suppressing newlines helps ergonomics.</p>
<p><strong>Decision</strong>:
The ZGL grammar will allow <code>\</code> as a string continuation character for strings.
It works the same way <a href="https://doc.rust-lang.org/reference/tokens.html#string-literals">as it does in Rust</a>:</p>
<blockquote>
<p>when an unescaped U+005C character (\) occurs immediately before the
line-break, then the U+005C character, the line-break, and all
whitespace at the beginning of the next line are ignored.</p>
</blockquote>
<p><strong>Consequences</strong>:
This requires simple changes to the parser and syntax highlighters.</p>
<p><strong>Status</strong>:
Accepted on 2021-02-25.
Updated on 2021-03-08.</p>
Require whitespace to terminate a URL2021-02-25T21:05:00+00:002021-02-25T21:10:00+00:00https://zg-lang.org/decisions/url-whitespace/<h2 id="require-whitespace-to-terminate-a-url">Require whitespace to terminate a URL</h2>
<p><strong>Context</strong>:
What should ZGL do if an URL ends with a <code>,</code> or <code>;</code>? Here are two choices:</p>
<ol>
<li>Include the <code>,</code> or <code>;</code> character as part of the URL.</li>
<li>Treat the <code>,</code> or <code>;</code> as a separate token.</li>
</ol>
<p>As a point of comparison, many text-processing tools (e.g. email clients) do not include a trailing punctuation character in a URL.</p>
<p>However, if (2), how can a user represent a URL that ends in a <code>,</code> or <code>;</code>? This would require additional grammar rules. Since I prefer ZGL's grammar to be simple, I choose (1).</p>
<p><strong>Decision</strong>:
Whitespace is required to terminate a URL. </p>
<p>For example, this would be incorrect:</p>
<pre><code class="language-zgl" data-lang="zgl">/org/PBS homepage https://www.pbs.org;
</code></pre>
<p>Above, a parser would consume the <code>;</code> as part of the URL. However, then it would not find a terminating <code>;</code> and fail. </p>
<p>Here is the correct way to write the graph expression:</p>
<pre><code class="language-zgl" data-lang="zgl">/org/PBS homepage https://www.pbs.org ;
</code></pre>
<p><strong>Consequences</strong>:</p>
<ul>
<li>Simpler grammar.</li>
<li>Simpler to implement.</li>
<li>Slightly less convenient to type.</li>
<li>Assymetry: there are no other places where whitespace is required before a terminating semicolon (<code>;</code>).</li>
</ul>
<p><strong>Status</strong>:
Accepted on 2021-02-25.</p>