Start expression syntax document

author: Marshall Lochbaum <mwlochbaum@gmail.com> 2021-08-06 22:10:51 -0400
committer: Marshall Lochbaum <mwlochbaum@gmail.com> 2021-08-06 22:10:51 -0400
commit: d9c8e65f8bf6219c169eddbfb9320a045f70d636 (patch)
tree: 523fcedbf14fa6565659399a67a82c33da65be43 /docs
parent: 8058cc31eb23393f7c78617d0136e9d21e28d869 (diff)
2 files changed, 173 insertions, 0 deletions
diff --git a/docs/doc/expression.html b/docs/doc/expression.html
new file mode 100644
index 00000000..7597fe4c
--- /dev/null
+++ b/docs/doc/expression.html
@@ -0,0 +1,172 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Expression syntax</title>
+</head>
+<div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">doc</a></div>
+<h1 id="expression-syntax">Expression syntax</h1>
+<p>BQN expressions are the part of <a href="syntax.html">syntax</a> that describes computations to perform. Programs are mainly made up of expressions with a little organizing material like <a href="block.html">blocks</a> and <a href="namespace.html">namespaces</a> around them. This page explains how functions, modifiers, and assignment combine with their inputs. It doesn't describe <a href="syntax.html#constant">constant</a> and <a href="arrayrepr.html#list-literals">array</a> literals, which each form a single subject for grammatical purposes.</p>
+<p>The <a href="../tutorial/expression.html">first tutorial</a> also covers how to build and read BQN expressions.</p>
+<h2 id="overview">Overview</h2>
+<p>BQN expressions consist of subjects, functions, and modifiers arranged in sequence, with parentheses to group parts into subexpressions. Assignment arrows <code><span class='Gets'>←</span></code> and <code><span class='Gets'>↩</span></code> can also be present and mostly behave similar to functions. Functions can be applied to subjects or grouped into trains, while modifiers can be applied to subjects or functions. The most important kinds of application are:</p>
+<table>
+<thead>
+<tr>
+<th>left</th>
+<th>main</th>
+<th>right</th>
+<th>output</th>
+<th>name</th>
+<th>binding</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code><span class='Value'>w?</span></code></td>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Value'>x</span></code></td>
+<td>Subject</td>
+<td>Function</td>
+<td>RtL, looser</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span><span class='Value'>?</span></code></td>
+<td><code><span class='Function'>G</span></code></td>
+<td><code><span class='Function'>H</span></code></td>
+<td>Function</td>
+<td>Train</td>
+<td></td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Modifier'>_m</span></code></td>
+<td></td>
+<td>Function</td>
+<td>1-Modifier</td>
+<td>LtR, tighter</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Modifier2'>_c_</span></code></td>
+<td><code><span class='Function'>G</span></code></td>
+<td>Function</td>
+<td>2-Modifier</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p>The four roles (subject, function, two kinds of modifier) describe expressions, not values. When an expression is evaluated, the value's <a href="types.html">type</a> doesn't have to correspond to its role, and can even change from one evaluation to another. An expression's role is determined entirely by its source code, so it's fixed.</p>
+<p>If you're comfortable reading <a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a> and want to understand things in more detail than described below, you might check the <a href="../spec/grammar.html">grammar specification</a> as well.</p>
+<h2 id="syntactic-role">Syntactic role</h2>
+<p><em>This issue is approached from a different angle in <a href="context.html">Context free grammar</a>.</em></p>
+<p>In APL, the way one part of an expression interacts with others is determined by its value. That means that to parse an expression, in general you would have to evaluate that part, get a value, check its type, and then figure out how it fits in with the rest of the expression. This is a lot of work. BQN changes things so that you can determine how to parse an expression just by looking at its source code. But because it still needs to support expressions that can evaluate to more than one possible <a href="types.html">type</a>, BQN has to introduce a new and independent concept, called <strong>syntactic role</strong>, in order to support APL-like expressions.</p>
+<p>Syntactic role is a property of an expression, not its value. To describe it in terms of English grammar, you might say &quot;I like BQN&quot;, using &quot;BQN&quot; as an object, or &quot;BQN scares me&quot;, using it as a subject. BQN itself isn't a subject or object, it's a programming language. Similarly you might write <code><span class='Function'>F</span> <span class='Value'>g</span></code>, placing <code><span class='Value'>f</span></code> in a function role to apply it to <code><span class='Value'>g</span></code>, or <code><span class='Function'>G</span> <span class='Value'>f</span></code> to use <code><span class='Value'>f</span></code> as an argument. Maybe even in the same program, although it's unlikely.</p>
+<h3 id="role-spellings">Role spellings</h3>
+<p>The four roles are <strong>subject</strong>, <strong>function</strong>, <strong>1-modifier</strong>, and <strong>2-modifier</strong>, as shown in the table below. Each type has an associated role (with non-operation types all corresponding to subjects), and the value of an expression will often have a matching type, but it doesn't have to.</p>
+<table>
+<thead>
+<tr>
+<th>BQN</th>
+<th>Names</th>
+<th>Primitives</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Subject</td>
+<td><code><span class='Value'>lowerCase</span></code></td>
+<td>Literals</td>
+</tr>
+<tr>
+<td>Function</td>
+<td><code><span class='Function'>UpperCase</span></code></td>
+<td><code><span class='Function'>+-×÷⋆√⌊⌈|¬∧∨</span></code>…</td>
+</tr>
+<tr>
+<td>1-modifier</td>
+<td><code><span class='Modifier'>_leading</span></code></td>
+<td><code><span class='Modifier'>˙˜˘¨⌜⁼´˝`</span></code></td>
+</tr>
+<tr>
+<td>2-modifier</td>
+<td><code><span class='Modifier2'>_both_</span></code></td>
+<td><code><span class='Modifier2'>∘○⊸⟜⌾⊘◶⎉⚇⍟⎊</span></code></td>
+</tr>
+</tbody>
+</table>
+<p>Primitive tokens, since they have a fixed value, always have a role that matches their type. They are functions, unless they fall into one of the two modifier patterns. 1-modifiers have superscript glyphs, and 2-modifiers have glyphs with an unbroken circle—that is, one without a line through it, excluding functions <code><span class='Function'>⌽</span></code> and <code><span class='Function'>⍉</span></code>.</p>
+<p>Variable names can be written in any case and with underscores added, and these changes don't affect what <a href="lexical.html">identifier</a> the name refers to. <code><span class='Value'>ab</span></code>, <code><span class='Value'>aB</span></code>, <code><span class='Function'>AB</span></code>, and <code><span class='Modifier2'>_a_B_</span></code> are all the same variable. However, the spelling—specifically the first and last characters—determine the variable's role. A lowercase first letter indicates a subject, and an uppercase first letter makes it a function. A leading underscore (regardless of the following character) indicates a 1-modifier, and both leading and trailing underscores makes a 2-modifier.</p>
+<p>Besides these, character, string, and <a href="arrayrepr.html#list-literals">list literals</a> always have a subject role, and the role of a <a href="block.html">block</a> is determined by its type, which depends either on the header it has or which special variables it uses.</p>
+<p>The role of a compound expression, formed by applying an operation to some inputs, depends on the operation applied. This system is discussed in the remaining sections below.</p>
+<h2 id="kinds-of-application">Kinds of application</h2>
+<p>Here is a table of the modifier and function application rules:</p>
+<table>
+<thead>
+<tr>
+<th>left</th>
+<th>main</th>
+<th>right</th>
+<th>output</th>
+<th>name</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td></td>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Value'>x</span></code></td>
+<td>Subject</td>
+<td>Monadic function</td>
+</tr>
+<tr>
+<td><code><span class='Value'>w</span></code></td>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Value'>x</span></code></td>
+<td>Subject</td>
+<td>Dyadic function</td>
+</tr>
+<tr>
+<td></td>
+<td><code><span class='Function'>F</span></code></td>
+<td><code><span class='Function'>G</span></code></td>
+<td>Function</td>
+<td>2-train</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
+<td><code><span class='Function'>G</span></code></td>
+<td><code><span class='Function'>H</span></code></td>
+<td>Function</td>
+<td>3-train</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
+<td><code><span class='Modifier'>_m</span></code></td>
+<td></td>
+<td>Function</td>
+<td>1-Modifier</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
+<td><code><span class='Modifier2'>_c_</span></code></td>
+<td><code><span class='Function'>G</span><span class='Value'>*</span></code></td>
+<td>Function</td>
+<td>2-Modifier</td>
+</tr>
+<tr>
+<td></td>
+<td><code><span class='Modifier2'>_c_</span></code></td>
+<td><code><span class='Function'>G</span><span class='Value'>*</span></code></td>
+<td>1-Modifier</td>
+<td>Partial application</td>
+</tr>
+<tr>
+<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
+<td><code><span class='Modifier2'>_c_</span></code></td>
+<td></td>
+<td>1-Modifier</td>
+<td>Partial application</td>
+</tr>
+</tbody>
+</table>
+<p>A function with an asterisk indicates that a subject can also be used. Since the role doesn't exist after parting function and subject spellings are indistinguishable in these positions. Modifier applications bind more tightly than functions, and associate left-to-right while functions associate right-to-left.</p>
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 356773a9..737ff56d 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -22,6 +22,7 @@
 <p>Concepts:</p>
 <ul>
 <li><a href="context.html">Context-free grammar</a></li>
+<li><a href="expression.html">Expression syntax</a></li>
 <li><a href="array.html">Arrays</a></li>
 <li><a href="based.html">Based array theory</a></li>
 <li><a href="arrayrepr.html">Array notation and display</a></li>
author	Marshall Lochbaum <mwlochbaum@gmail.com>	2021-08-06 22:10:51 -0400
committer	Marshall Lochbaum <mwlochbaum@gmail.com>	2021-08-06 22:10:51 -0400
commit	d9c8e65f8bf6219c169eddbfb9320a045f70d636 (patch)
tree	523fcedbf14fa6565659399a67a82c33da65be43 /docs
parent	8058cc31eb23393f7c78617d0136e9d21e28d869 (diff)