Spec commentary sections on combinators and array properties

2 files changed, 55 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>
diff --git a/spec/primitive.md b/spec/primitive.md
index 028cd80d..f888c0b9 100644
--- a/spec/primitive.md
+++ b/spec/primitive.md
@@ -74,3 +74,33 @@ Inferred properties are specified in [their own document](inferred.md), not in t
 ## Other provided functionality
 
 - **Assert** (`!`) causes an error if the argument is not `1`. If `𝕨` is provided, it gives a message to be associated with this error (which can be any value, not necessarily a string).
+
+## Commentary on other primitives
+
+As noted above, see [reference.bqn](reference.bqn) for the authoritative definitions. Commentary here gives an overall description and highlights implementation subtleties and edge cases.
+
+### Combinators
+
+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.
+
+- **Choose** (`◶`) is later redefined to use the complete `⊑` rather than the simple version assumed (using this primitive means it's not a true combinator).
+- **Constant** (`˙`)
+- **Valences** (`⊘`) uses a trick with ambivalent `-` to find out whether there's a left argument, described below.
+- **Right** (`⊢`)
+- **Left** (`⊣`)
+- **Self**/**Swap** (`˜`)
+- **Atop** (`∘`)
+- **Over** (`○`)
+- **Before**/**Bind** (`⊸`)
+- **After**/**Bind** (`⟜`)
+
+The somewhat complicated definition of Valences could be replaced with `{𝔽𝕩;𝕨𝔾𝕩}` 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 `𝕨` works like `·` if no left argument is given: `(1˙𝕨)-0` is `1-0` or `1` if `𝕨` is present and `(1˙·)-0` otherwise: this reduces to `·-0` or `0`.
+
+### Array properties
+
+The reference implementations extend Shape (`≢`) to atoms as well as arrays, in addition to implementing other properties. In all cases, an atom behaves as if it has shape `⟨⟩`. The functions in this section never cause an error.
+
+- **Shape** (`≢`) gives the shape of an array or atom.
+- **Rank** (`=`) gives the length of the shape.
+- **Length** (`≠`) gives the number of major cells, or `1` for an argument of rank `0`.
+- **Depth** (`≡`) gives the nesting depth. It ignores the shapes of arrays, and considering only the depths of their elements.