Documentation for Constant

8 files changed, 99 insertions, 12 deletions

diff --git a/doc/README.md b/doc/README.md
index 0560a3a6..26374f5c 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -42,6 +42,7 @@ Primitives:
 - [Array dimensions](shape.md) (`≢=≠`)
 - [Assert and Catch](assert.md) (`!` and `⎊`)
 - [Atop and Over](compose.md) (`∘○`)
+- [Constant](constant.md) (`˙`)
 - [Deshape and Reshape](reshape.md) (`⥊`)
 - [Enclose](enclose.md) (`<`)
 - [Find](find.md) (`⍷`)
diff --git a/doc/constant.md b/doc/constant.md
new file mode 100644
index 00000000..73413a03
--- /dev/null
+++ b/doc/constant.md
@@ -0,0 +1,28 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/constant.html).*
+
+# Constant
+
+<!--GEN combinator.bqn
+DrawComp ≍"˙"
+-->
+
+It's one of the simple ones: `f˙𝕩` is `f`. And `𝕨f˙𝕩`? It's `f`. Like the [identity functions](identity.md), Constant doesn't compute anything but just returns one of its inputs. It's somewhat different in that it's a deferred modifier, so you have to first apply Constant to its operand and *then* to some arguments for that non-event to happen.
+
+The design of BQN makes Constant unnecessary in most cases, because when a non-operation (number, character, array, namespace) is applied it already returns itself: `π˙` is the same function as `π`. If you've used much [tacit](tacit.md) programming, you've probably written a few [trains](train.md) like `2×+` (twice the sum), which is nicer than the equivalent `2˙×+`. However, a train has to end with a function, so you can't just put a number at the end. Applying `˙` is a convenient way to change the number from a subject to a function role.
+
+        +÷2   # A number
+
+        +÷2˙  # A function
+
+        3 (+÷2˙) 7
+
+When programming with [first-class functions](functional.md), the constant application shortcut becomes a hazard! Consider the program `{𝕨⌾(2⊸⊑) 𝕩}` to insert `𝕨` into an array `𝕩` as an element. It works fine with a number, but with a function it's broken:
+
+        ∞ {𝕨⌾(2⊸⊑) 𝕩} 1‿2‿3‿4
+
+        M ← -
+        m {𝕨⌾(2⊸⊑) 𝕩} 1‿2‿3‿4
+
+Here `m` is applied to `2⊑𝕩` even though we want to discard that value. Spelled as `m`, our [context-free grammar](context.md) knows it's a function argument, but this [doesn't affect](../problems.md#syntactic-type-erasure) later usage. Under always applies `𝔽` as a function. The proper definition of the insertion function should use a `˙`, like this:
+
+        m {𝕨˙⌾(2⊸⊑) 𝕩} 1‿2‿3‿4
diff --git a/doc/primitive.md b/doc/primitive.md
index f2b47341..c358d80a 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -65,17 +65,17 @@ Functions that have significant differences from APL equivalents or don't appear
 
 *Combinators* only control the application of functions. Because a non-function operand applies as a constant function, some combinators have extra meanings when passed a constant. For example, `0˜` is identical to `0˙`—a constant function that always returns 0—and `0⊸<` is the function that tests whether its right argument is greater than 0.
 
-Glyph | Name(s)            | Definition                     | Description
-------|--------------------|--------------------------------|---------------------------------------
-`˙`   | Constant           | `{𝕩⋄𝕗}`                        | Return a function that returns the operand
-`˜`   | [Self/Swap](swap.md) | `{𝕩𝔽𝕨⊣𝕩}`                      | Duplicate one argument or exchange two
-`∘`   | [Atop](compose.md) | `{𝔽𝕨𝔾𝕩}`                       | Apply `𝔾` to both arguments and `𝔽` to the result
-`○`   | [Over](compose.md) | `{(𝔾𝕨)𝔽𝔾𝕩}`                    | Apply `𝔾` to each argument and `𝔽` to the results
-`⊸`   | Before/Bind        | `{(𝔽𝕨⊣𝕩)𝔾𝕩}`                   | `𝔾`'s left argument comes from `𝔽`
-`⟜`   | After/Bind         | `{(𝕨⊣𝕩)𝔽𝔾𝕩}`                   | `𝔽`'s right argument comes from `𝔾`
-`⌾`   | Under              | `{𝔾⁼∘𝔽○𝔾}` OR `{(𝔾𝕩)↩𝕨𝔽○𝔾𝕩⋄𝕩}` | Apply `𝔽` over `𝔾`, then undo `𝔾`
-`⊘`   | Valences           | `{𝔽𝕩;𝕨𝔾𝕩}`                     | Apply `𝔽` if there's one argument but `𝔾` if there are two
-`◶`   | Choose             | `{f←(𝕨𝔽𝕩)⊑𝕘 ⋄ 𝕨F𝕩}`            | Select one of the functions in list `𝕘` based on `𝔽`
+Glyph | Name(s)                 | Definition                     | Description
+------|-------------------------|--------------------------------|---------------------------------------
+`˙`   | [Constant](constant.md) | `{𝕩⋄𝕗}`                        | Return a function that returns the operand
+`˜`   | [Self/Swap](swap.md)    | `{𝕩𝔽𝕨⊣𝕩}`                      | Duplicate one argument or exchange two
+`∘`   | [Atop](compose.md)      | `{𝔽𝕨𝔾𝕩}`                       | Apply `𝔾` to both arguments and `𝔽` to the result
+`○`   | [Over](compose.md)      | `{(𝔾𝕨)𝔽𝔾𝕩}`                    | Apply `𝔾` to each argument and `𝔽` to the results
+`⊸`   | Before/Bind             | `{(𝔽𝕨⊣𝕩)𝔾𝕩}`                   | `𝔾`'s left argument comes from `𝔽`
+`⟜`   | After/Bind              | `{(𝕨⊣𝕩)𝔽𝔾𝕩}`                   | `𝔽`'s right argument comes from `𝔾`
+`⌾`   | Under                   | `{𝔾⁼∘𝔽○𝔾}` OR `{(𝔾𝕩)↩𝕨𝔽○𝔾𝕩⋄𝕩}` | Apply `𝔽` over `𝔾`, then undo `𝔾`
+`⊘`   | Valences                | `{𝔽𝕩;𝕨𝔾𝕩}`                     | Apply `𝔽` if there's one argument but `𝔾` if there are two
+`◶`   | Choose                  | `{f←(𝕨𝔽𝕩)⊑𝕘 ⋄ 𝕨F𝕩}`            | Select one of the functions in list `𝕘` based on `𝔽`
 
 Choose isn't really a combinator since it calls the function `⊑`, and Under is not a true combinator since it has an "undo" step at the end. This step might be implemented using the left operand's inverse (*computational* Under) or its structural properties (*structural* Under).
 
diff --git a/docs/doc/constant.html b/docs/doc/constant.html
new file mode 100644
index 00000000..524a13f5
--- /dev/null
+++ b/docs/doc/constant.html
@@ -0,0 +1,55 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Constant</title>
+</head>
+<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div>
+<h1 id="constant"><a class="header" href="#constant">Constant</a></h1>
+<svg viewBox='-191 0 672 270'>
+  <g font-size='20px' text-anchor='middle' transform='translate(145,20)'>
+    <rect class='code' stroke-width='1' rx='12' x='-120.4' y='1' width='240.8' height='205'/>
+    <text dy='0.32em' y='223' fill='currentColor'>Constant</text>
+    <g font-size='21px' font-family='BQN,monospace' transform='translate(-60.87,25)'>
+      <text dy='0.32em' y='155' font-size='19px'><tspan class='Value'>𝕗</tspan><tspan class='Modifier'>˙</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0L0 57'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='57'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='114'/>
+      <text dy='0.32em' x='0' y='57'><tspan class='Value'>𝕗</tspan></text>
+      <text dy='0.32em' x='0' y='114'><tspan class='Value'>𝕩</tspan></text>
+    </g>
+    <g font-size='21px' font-family='BQN,monospace' transform='translate(60.87,25)'>
+      <text dy='0.32em' y='155' font-size='19px'><tspan class='Value'>𝕨</tspan> <tspan class='Value'>𝕗</tspan><tspan class='Modifier'>˙</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0L0 57'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='57'/>
+      <circle r='12' class='code' stroke-width='0' cx='-32' cy='114'/>
+      <circle r='12' class='code' stroke-width='0' cx='32' cy='114'/>
+      <text dy='0.32em' x='0' y='57'><tspan class='Value'>𝕗</tspan></text>
+      <text dy='0.32em' x='-32' y='114'><tspan class='Value'>𝕨</tspan></text>
+      <text dy='0.32em' x='32' y='114'><tspan class='Value'>𝕩</tspan></text>
+    </g>
+  </g>
+</svg>
+
+<p>It's one of the simple ones: <code><span class='Value'>f</span><span class='Modifier'>˙</span><span class='Value'>𝕩</span></code> is <code><span class='Value'>f</span></code>. And <code><span class='Value'>𝕨f</span><span class='Modifier'>˙</span><span class='Value'>𝕩</span></code>? It's <code><span class='Value'>f</span></code>. Like the <a href="identity.html">identity functions</a>, Constant doesn't compute anything but just returns one of its inputs. It's somewhat different in that it's a deferred modifier, so you have to first apply Constant to its operand and <em>then</em> to some arguments for that non-event to happen.</p>
+<p>The design of BQN makes Constant unnecessary in most cases, because when a non-operation (number, character, array, namespace) is applied it already returns itself: <code><span class='Number'>π</span><span class='Modifier'>˙</span></code> is the same function as <code><span class='Number'>π</span></code>. If you've used much <a href="tacit.html">tacit</a> programming, you've probably written a few <a href="train.html">trains</a> like <code><span class='Number'>2</span><span class='Function'>×+</span></code> (twice the sum), which is nicer than the equivalent <code><span class='Number'>2</span><span class='Modifier'>˙</span><span class='Function'>×+</span></code>. However, a train has to end with a function, so you can't just put a number at the end. Applying <code><span class='Modifier'>˙</span></code> is a convenient way to change the number from a subject to a function role.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8O3MiAgICMgQSBudW1iZXIKCivDtzLLmSAgIyBBIGZ1bmN0aW9uCgozICgrw7cyy5kpIDc=">↗️</a><pre>    <span class='Function'>+÷</span><span class='Number'>2</span>   <span class='Comment'># A number
+</span>0.5
+
+    <span class='Function'>+÷</span><span class='Number'>2</span><span class='Modifier'>˙</span>  <span class='Comment'># A function
+</span>+÷2˙
+
+    <span class='Number'>3</span> <span class='Paren'>(</span><span class='Function'>+÷</span><span class='Number'>2</span><span class='Modifier'>˙</span><span class='Paren'>)</span> <span class='Number'>7</span>
+5
+</pre>
+<p>When programming with <a href="functional.html">first-class functions</a>, the constant application shortcut becomes a hazard! Consider the program <code><span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>⊑</span><span class='Paren'>)</span> <span class='Value'>𝕩</span><span class='Brace'>}</span></code> to insert <code><span class='Value'>𝕨</span></code> into an array <code><span class='Value'>𝕩</span></code> as an element. It works fine with a number, but with a function it's broken:</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oieIHvwnZWo4oy+KDLiirjiipEpIPCdlal9IDHigL8y4oC/M+KAvzQKCk0g4oaQIC0KbSB78J2VqOKMvigy4oq44oqRKSDwnZWpfSAx4oC/MuKAvzPigL80">↗️</a><pre>    <span class='Number'>∞</span> <span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>⊑</span><span class='Paren'>)</span> <span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
+⟨ 1 2 ∞ 4 ⟩
+
+    <span class='Function'>M</span> <span class='Gets'>←</span> <span class='Function'>-</span>
+    <span class='Value'>m</span> <span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>⊑</span><span class='Paren'>)</span> <span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
+⟨ 1 2 ¯3 4 ⟩
+</pre>
+<p>Here <code><span class='Value'>m</span></code> is applied to <code><span class='Number'>2</span><span class='Function'>⊑</span><span class='Value'>𝕩</span></code> even though we want to discard that value. Spelled as <code><span class='Value'>m</span></code>, our <a href="context.html">context-free grammar</a> knows it's a function argument, but this <a href="../problems.html#syntactic-type-erasure">doesn't affect</a> later usage. Under always applies <code><span class='Function'>𝔽</span></code> as a function. The proper definition of the insertion function should use a <code><span class='Modifier'>˙</span></code>, like this:</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bSB78J2VqMuZ4oy+KDLiirjiipEpIPCdlal9IDHigL8y4oC/M+KAvzQ=">↗️</a><pre>    <span class='Value'>m</span> <span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Modifier'>˙</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>⊑</span><span class='Paren'>)</span> <span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
+⟨ 1 2 - 4 ⟩
+</pre>
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 38f7d2cd..5d303de3 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -48,6 +48,7 @@
 <li><a href="shape.html">Array dimensions</a> (<code><span class='Function'>≢=≠</span></code>)</li>
 <li><a href="assert.html">Assert and Catch</a> (<code><span class='Function'>!</span></code> and <code><span class='Modifier2'>⎊</span></code>)</li>
 <li><a href="compose.html">Atop and Over</a> (<code><span class='Modifier2'>∘○</span></code>)</li>
+<li><a href="constant.html">Constant</a> (<code><span class='Modifier'>˙</span></code>)</li>
 <li><a href="reshape.html">Deshape and Reshape</a> (<code><span class='Function'>⥊</span></code>)</li>
 <li><a href="enclose.html">Enclose</a> (<code><span class='Function'>&lt;</span></code>)</li>
 <li><a href="find.html">Find</a> (<code><span class='Function'>⍷</span></code>)</li>
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index c4b48a20..1601ed08 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -425,7 +425,7 @@
 <tbody>
 <tr>
 <td><code><span class='Modifier'>˙</span></code></td>
-<td>Constant</td>
+<td><a href="constant.html">Constant</a></td>
 <td><code><span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Separator'>⋄</span><span class='Value'>𝕗</span><span class='Brace'>}</span></code></td>
 <td>Return a function that returns the operand</td>
 </tr>
diff --git a/docs/help/constant.html b/docs/help/constant.html
index 17ba5562..97bf2c16 100644
--- a/docs/help/constant.html
+++ b/docs/help/constant.html
@@ -6,6 +6,7 @@
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">help</a></div>
 <h1 id="dot-above-"><a class="header" href="#dot-above-">Dot Above (<code><span class='Modifier'>˙</span></code>)</a></h1>
 <h2 id="𝔽-𝕩-𝕨-𝔽-𝕩-constant"><a class="header" href="#𝔽-𝕩-𝕨-𝔽-𝕩-constant"><code><span class='Function'>𝔽</span><span class='Modifier'>˙</span> <span class='Value'>𝕩</span></code>, <code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier'>˙</span> <span class='Value'>𝕩</span></code>: Constant</a></h2>
+<p><a class="fulldoc" href="../doc/constant.html">→full documentation</a></p>
 <p>Returns a function that will always return <code><span class='Value'>𝕗</span></code>.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImhlbGxvIiAxy5kgMgoKImhlbGxvIiB78J2VqCvwnZWpfcuZIDI=">↗️</a><pre>    <span class='String'>&quot;hello&quot;</span> <span class='Number'>1</span><span class='Modifier'>˙</span> <span class='Number'>2</span>
 1
diff --git a/help/constant.md b/help/constant.md
index 25957a43..639da7c3 100644
--- a/help/constant.md
+++ b/help/constant.md
@@ -3,6 +3,7 @@
 # Dot Above (`˙`)
 
 ## `𝔽˙ 𝕩`, `𝕨 𝔽˙ 𝕩`: Constant
+[→full documentation](../doc/constant.md)
 
 Returns a function that will always return `𝕗`.