Spec commentary sections on combinators and array properties

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/spec/primitive.html b/docs/spec/primitive.html
index 53a74f25..e62158f2 100644
--- a/docs/spec/primitive.html
+++ b/docs/spec/primitive.html
@@ -68,3 +68,28 @@
 <ul>
 <li><strong>Assert</strong> (<code><span class='Function'>!</span></code>) causes an error if the argument is not <code><span class='Number'>1</span></code>. If <code><span class='Value'>𝕨</span></code> is provided, it gives a message to be associated with this error (which can be any value, not necessarily a string).</li>
 </ul>
+<h2 id="commentary-on-other-primitives">Commentary on other primitives</h2>
+<p>As noted above, see <a href="https://github.com/mlochbaum/BQN/blob/master/spec/reference.bqn">reference.bqn</a> for the authoritative definitions. Commentary here gives an overall description and highlights implementation subtleties and edge cases.</p>
+<h3 id="combinators">Combinators</h3>
+<p>There's little to say about BQN's true combinators, since each is simply a pattern of function application. All primitive combinators use their operands as functions, and thus treat a data operand as a constant function.</p>
+<ul>
+<li><strong>Choose</strong> (<code><span class='Modifier2'>◶</span></code>) is later redefined to use the complete <code><span class='Function'>⊑</span></code> rather than the simple version assumed (using this primitive means it's not a true combinator).</li>
+<li><strong>Constant</strong> (<code><span class='Modifier'>˙</span></code>)</li>
+<li><strong>Valences</strong> (<code><span class='Modifier2'>⊘</span></code>) uses a trick with ambivalent <code><span class='Function'>-</span></code> to find out whether there's a left argument, described below.</li>
+<li><strong>Right</strong> (<code><span class='Function'>⊢</span></code>)</li>
+<li><strong>Left</strong> (<code><span class='Function'>⊣</span></code>)</li>
+<li><strong>Self</strong>/<strong>Swap</strong> (<code><span class='Modifier'>˜</span></code>)</li>
+<li><strong>Atop</strong> (<code><span class='Modifier2'>∘</span></code>)</li>
+<li><strong>Over</strong> (<code><span class='Modifier2'>○</span></code>)</li>
+<li><strong>Before</strong>/<strong>Bind</strong> (<code><span class='Modifier2'>⊸</span></code>)</li>
+<li><strong>After</strong>/<strong>Bind</strong> (<code><span class='Modifier2'>⟜</span></code>)</li>
+</ul>
+<p>The somewhat complicated definition of Valences could be replaced with <code><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Value'>𝕩;𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code> using headers. However, reference.bqn uses a simple subset of BQN's syntax that doesn't include headers. Instead, the definition relies on the fact that <code><span class='Value'>𝕨</span></code> works like <code><span class='Nothing'>·</span></code> if no left argument is given: <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Modifier'>˙</span><span class='Value'>𝕨</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Number'>0</span></code> is <code><span class='Number'>1</span><span class='Function'>-</span><span class='Number'>0</span></code> or <code><span class='Number'>1</span></code> if <code><span class='Value'>𝕨</span></code> is present and <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Modifier'>˙</span><span class='Nothing'>·</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Number'>0</span></code> otherwise: this reduces to <code><span class='Nothing'>·</span><span class='Function'>-</span><span class='Number'>0</span></code> or <code><span class='Number'>0</span></code>.</p>
+<h3 id="array-properties">Array properties</h3>
+<p>The reference implementations extend Shape (<code><span class='Function'>≢</span></code>) to atoms as well as arrays, in addition to implementing other properties. In all cases, an atom behaves as if it has shape <code><span class='Bracket'>⟨⟩</span></code>. The functions in this section never cause an error.</p>
+<ul>
+<li><strong>Shape</strong> (<code><span class='Function'>≢</span></code>) gives the shape of an array or atom.</li>
+<li><strong>Rank</strong> (<code><span class='Function'>=</span></code>) gives the length of the shape.</li>
+<li><strong>Length</strong> (<code><span class='Function'>≠</span></code>) gives the number of major cells, or <code><span class='Number'>1</span></code> for an argument of rank <code><span class='Number'>0</span></code>.</li>
+<li><strong>Depth</strong> (<code><span class='Function'>≡</span></code>) gives the nesting depth. It ignores the shapes of arrays, and considering only the depths of their elements.</li>
+</ul>