Documentation for Choose

9 files changed, 64 insertions, 3 deletions

diff --git a/doc/README.md b/doc/README.md
index 8acd5740..98c61d51 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) (`∘○`)
+- [Choose](choose.md) (`◶`)
 - [Constant](constant.md) (`˙`)
 - [Deshape and Reshape](reshape.md) (`⥊`)
 - [Enclose](enclose.md) (`<`)
diff --git a/doc/choose.md b/doc/choose.md
new file mode 100644
index 00000000..4362b9f5
--- /dev/null
+++ b/doc/choose.md
@@ -0,0 +1,27 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/choose.html).*
+
+# Choose
+
+The 2-modifier Choose (`◶`) applies one function from a list `𝕘`, based on a selection function `𝔽` that returns an index. It's a combinator form of [Pick](pick.md) (`⊑`), so that `{f←(𝕨𝔽𝕩)⊑𝕘 ⋄ 𝕨F𝕩}` is a complete definition. For example, the function below subtracts 1 from an argument if negative and adds 1 if positive.
+
+        0⊸≤◶⟨-⟜1, +⟜1⟩¨ 3‿¯1‿5
+
+Here the selection function `𝔽` is `0⊸≤`, while `𝕘` is a list of two functions `⟨-⟜1, +⟜1⟩`. On the first argument, `3`, `𝔽3` is `0≤3`, or `1`, so the function `+⟜1` from `𝕘` is chosen. The use of array indices means "false" comes first in `𝕘` and "true" comes second, which is backwards relative to if-else constructs in most programming languages (including BQN's own predicates). When using a comparison for `𝔽` I strongly prefer to phrase it as `n⊸<` or `n⊸≤` so that smaller values go through the first one and larger functions go through the second. This doesn't apply so much when comparing two arguments since one is smaller but the other's larger, so I don't have an easy technique for that.
+
+        2 >◶⊣‿⊢ 6  # A minimum function (⌊)
+
+The advantage of using an index is that Choose works with any number of options.
+
+        Fn ← (⊑"rtd"⊒⊏)◶⟨⌽, 1⊸↑, 1⊸↓, ⊢⟩  # Reverse, take 1, drop 1
+
+        Fn "r123"
+
+        Fn "d123"
+
+        Fn "123"  # Default
+
+The selection function in `Fn` uses [Index of](search.md#index-of) (`⊒`) to find the index of the first character in the list `"rtd"`. An extra value in `𝕘` serves as a default function if it's none of those, since the result of `𝔽` is `3` in that case. A similar function that's often useful is [Bins](order.md#bins), for grouping inputs into intervals rather than by exact matching.
+
+Choose is necessary for [tacit](tacit.md) programming, but tacit programming is not necessary to be an effective BQN programmer! Consider using block features like [predicates](block.md#predicates) when Choose isn't working with your program's flow.
+
+Because Choose is based on [Pick](pick.md), it retains the features of negative, multidimensional, and multiple selection. Negative indexing might make sense if there's some special `¯1` value, and if the options naturally form an array, multidimensional indexing is pretty neat. Selecting multiple values from `𝕘`, which happens if the result of `𝔽` is an array of arrays, is never useful because the array result from `𝔽` acts as a constant function. It's much clearer to express it as `𝔽⊑𝕘˙`.
diff --git a/doc/primitive.md b/doc/primitive.md
index 318d360f..79d6120b 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -75,7 +75,7 @@ Glyph | Name(s)                 | Definition                     | Description
 `⟜`   | After/Bind              | `{(𝕨⊣𝕩)𝔽𝔾𝕩}`                   | `𝔽`'s right argument comes from `𝔾`
 `⌾`   | Under                   | `{𝔾⁼∘𝔽○𝔾}` OR `{(𝔾𝕩)↩𝕨𝔽○𝔾𝕩⋄𝕩}` | Apply `𝔽` over `𝔾`, then undo `𝔾`
 `⊘`   | [Valences](valences.md) | `{𝔽𝕩;𝕨𝔾𝕩}`                     | Apply `𝔽` if there's one argument but `𝔾` if there are two
-`◶`   | Choose                  | `{f←(𝕨𝔽𝕩)⊑𝕘 ⋄ 𝕨F𝕩}`            | Select one of the functions in list `𝕘` based on `𝔽`
+`◶`   | [Choose](choose.md)     | `{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/choose.html b/docs/doc/choose.html
new file mode 100644
index 00000000..2bcaa223
--- /dev/null
+++ b/docs/doc/choose.html
@@ -0,0 +1,30 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Choose</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="choose"><a class="header" href="#choose">Choose</a></h1>
+<p>The 2-modifier Choose (<code><span class='Modifier2'>◶</span></code>) applies one function from a list <code><span class='Value'>𝕘</span></code>, based on a selection function <code><span class='Function'>𝔽</span></code> that returns an index. It's a combinator form of <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>), so that <code><span class='Brace'>{</span><span class='Value'>f</span><span class='Gets'>←</span><span class='Paren'>(</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>⊑</span><span class='Value'>𝕘</span> <span class='Separator'>⋄</span> <span class='Value'>𝕨</span><span class='Function'>F</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code> is a complete definition. For example, the function below subtracts 1 from an argument if negative and adds 1 if positive.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MOKKuOKJpOKXtuKfqC3in5wxLCAr4p+cMeKfqcKoIDPigL/CrzHigL81">↗️</a><pre>    <span class='Number'>0</span><span class='Modifier2'>⊸</span><span class='Function'>≤</span><span class='Modifier2'>◶</span><span class='Bracket'>⟨</span><span class='Function'>-</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Bracket'>⟩</span><span class='Modifier'>¨</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>5</span>
+⟨ 4 ¯2 6 ⟩
+</pre>
+<p>Here the selection function <code><span class='Function'>𝔽</span></code> is <code><span class='Number'>0</span><span class='Modifier2'>⊸</span><span class='Function'>≤</span></code>, while <code><span class='Value'>𝕘</span></code> is a list of two functions <code><span class='Bracket'>⟨</span><span class='Function'>-</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Bracket'>⟩</span></code>. On the first argument, <code><span class='Number'>3</span></code>, <code><span class='Function'>𝔽</span><span class='Number'>3</span></code> is <code><span class='Number'>0</span><span class='Function'>≤</span><span class='Number'>3</span></code>, or <code><span class='Number'>1</span></code>, so the function <code><span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Number'>1</span></code> from <code><span class='Value'>𝕘</span></code> is chosen. The use of array indices means &quot;false&quot; comes first in <code><span class='Value'>𝕘</span></code> and &quot;true&quot; comes second, which is backwards relative to if-else constructs in most programming languages (including BQN's own predicates). When using a comparison for <code><span class='Function'>𝔽</span></code> I strongly prefer to phrase it as <code><span class='Value'>n</span><span class='Modifier2'>⊸</span><span class='Function'>&lt;</span></code> or <code><span class='Value'>n</span><span class='Modifier2'>⊸</span><span class='Function'>≤</span></code> so that smaller values go through the first one and larger functions go through the second. This doesn't apply so much when comparing two arguments since one is smaller but the other's larger, so I don't have an easy technique for that.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiA+4pe24oqj4oC/4oqiIDYgICMgQSBtaW5pbXVtIGZ1bmN0aW9uICjijIop">↗️</a><pre>    <span class='Number'>2</span> <span class='Function'>&gt;</span><span class='Modifier2'>◶</span><span class='Function'>⊣</span><span class='Ligature'>‿</span><span class='Function'>⊢</span> <span class='Number'>6</span>  <span class='Comment'># A minimum function (⌊)
+</span>2
+</pre>
+<p>The advantage of using an index is that Choose works with any number of options.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Rm4g4oaQICjiipEicnRkIuKKkuKKjynil7bin6jijL0sIDHiirjihpEsIDHiirjihpMsIOKKouKfqSAgIyBSZXZlcnNlLCB0YWtlIDEsIGRyb3AgMQoKRm4gInIxMjMiCgpGbiAiZDEyMyIKCkZuICIxMjMiICAjIERlZmF1bHQ=">↗️</a><pre>    <span class='Function'>Fn</span> <span class='Gets'>←</span> <span class='Paren'>(</span><span class='Function'>⊑</span><span class='String'>&quot;rtd&quot;</span><span class='Function'>⊒⊏</span><span class='Paren'>)</span><span class='Modifier2'>◶</span><span class='Bracket'>⟨</span><span class='Function'>⌽</span><span class='Separator'>,</span> <span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>↑</span><span class='Separator'>,</span> <span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>↓</span><span class='Separator'>,</span> <span class='Function'>⊢</span><span class='Bracket'>⟩</span>  <span class='Comment'># Reverse, take 1, drop 1
+</span>
+    <span class='Function'>Fn</span> <span class='String'>&quot;r123&quot;</span>
+"321r"
+
+    <span class='Function'>Fn</span> <span class='String'>&quot;d123&quot;</span>
+"123"
+
+    <span class='Function'>Fn</span> <span class='String'>&quot;123&quot;</span>  <span class='Comment'># Default
+</span>"123"
+</pre>
+<p>The selection function in <code><span class='Function'>Fn</span></code> uses <a href="search.html#index-of">Index of</a> (<code><span class='Function'>⊒</span></code>) to find the index of the first character in the list <code><span class='String'>&quot;rtd&quot;</span></code>. An extra value in <code><span class='Value'>𝕘</span></code> serves as a default function if it's none of those, since the result of <code><span class='Function'>𝔽</span></code> is <code><span class='Number'>3</span></code> in that case. A similar function that's often useful is <a href="order.html#bins">Bins</a>, for grouping inputs into intervals rather than by exact matching.</p>
+<p>Choose is necessary for <a href="tacit.html">tacit</a> programming, but tacit programming is not necessary to be an effective BQN programmer! Consider using block features like <a href="block.html#predicates">predicates</a> when Choose isn't working with your program's flow.</p>
+<p>Because Choose is based on <a href="pick.html">Pick</a>, it retains the features of negative, multidimensional, and multiple selection. Negative indexing might make sense if there's some special <code><span class='Number'>¯1</span></code> value, and if the options naturally form an array, multidimensional indexing is pretty neat. Selecting multiple values from <code><span class='Value'>𝕘</span></code>, which happens if the result of <code><span class='Function'>𝔽</span></code> is an array of arrays, is never useful because the array result from <code><span class='Function'>𝔽</span></code> acts as a constant function. It's much clearer to express it as <code><span class='Function'>𝔽⊑</span><span class='Value'>𝕘</span><span class='Modifier'>˙</span></code>.</p>
diff --git a/docs/doc/index.html b/docs/doc/index.html
index c3d6ea2b..66bdbfec 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="choose.html">Choose</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>
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index db9140b6..aa3fd087 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -473,7 +473,7 @@
 </tr>
 <tr>
 <td><code><span class='Modifier2'>◶</span></code></td>
-<td>Choose</td>
+<td><a href="choose.html">Choose</a></td>
 <td><code><span class='Brace'>{</span><span class='Value'>f</span><span class='Gets'>←</span><span class='Paren'>(</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>⊑</span><span class='Value'>𝕘</span> <span class='Separator'>⋄</span> <span class='Value'>𝕨</span><span class='Function'>F</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td>
 <td>Select one of the functions in list <code><span class='Value'>𝕘</span></code> based on <code><span class='Function'>𝔽</span></code></td>
 </tr>
diff --git a/docs/help/choose.html b/docs/help/choose.html
index f56496f0..5c0562a3 100644
--- a/docs/help/choose.html
+++ b/docs/help/choose.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="circle-with-lower-right-quadrant-"><a class="header" href="#circle-with-lower-right-quadrant-">Circle with Lower Right Quadrant (<code><span class='Modifier2'>◶</span></code>)</a></h1>
 <h2 id="𝔽𝕘-𝕩-𝕨-𝔽𝕘-𝕩-choose"><a class="header" href="#𝔽𝕘-𝕩-𝕨-𝔽𝕘-𝕩-choose"><code><span class='Function'>𝔽</span><span class='Modifier2'>◶</span><span class='Value'>𝕘</span> <span class='Value'>𝕩</span></code>, <code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier2'>◶</span><span class='Value'>𝕘</span> <span class='Value'>𝕩</span></code>: Choose</a></h2>
+<p><a class="fulldoc" href="../doc/choose.html">→full documentation</a></p>
 <p>Apply <code><span class='Function'>𝔽</span></code> to the arguments and use the result to <a href="first_pick.html#𝕨--𝕩-pick">pick</a> (<code><span class='Function'>⊑</span></code>) a function from list <code><span class='Value'>𝕘</span></code>. Apply the picked function to the arguments.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=RiDihpAg4oqi4pe2K+KAvy3igL/Dt+KAv8OXCgpGIDAKCkYgMQoKRiAyCgpGIDM=">↗️</a><pre>    <span class='Function'>F</span> <span class='Gets'>←</span> <span class='Function'>⊢</span><span class='Modifier2'>◶</span><span class='Function'>+</span><span class='Ligature'>‿</span><span class='Function'>-</span><span class='Ligature'>‿</span><span class='Function'>÷</span><span class='Ligature'>‿</span><span class='Function'>×</span>
 
diff --git a/help/choose.md b/help/choose.md
index 02ebfc23..b0ca6001 100644
--- a/help/choose.md
+++ b/help/choose.md
@@ -3,6 +3,7 @@
 # Circle with Lower Right Quadrant (`◶`)
 
 ## `𝔽◶𝕘 𝕩`, `𝕨 𝔽◶𝕘 𝕩`: Choose
+[→full documentation](../doc/choose.md)
 
 Apply `𝔽` to the arguments and use the result to [pick](first_pick.md#𝕨--𝕩-pick) (`⊑`) a function from list `𝕘`. Apply the picked function to the arguments.
 
diff --git a/md.bqn b/md.bqn
index d252c192..646dc1f3 100644
--- a/md.bqn
+++ b/md.bqn
@@ -216,7 +216,7 @@ Markdown ← {filename𝕊𝕩:
     # Don't show assignment results by default
     ShowRslt ← {
       depth ← +` "(){}⟨⟩" (⊣(≠⊸>ׯ1⋆2|⊢)⊐) 𝕩
-      𝕩 /˜↩ ¬ ∨`⌾⌽ (0=depth) ∧ 𝕩∊"⋄,"  # Just the last statement
+      𝕩 /˜↩ ¬ ∨`⌾⌽ (0=depth) ∧ (∧`𝕩≠'#') ∧ 𝕩∊"⋄,"  # Just the last statement
       g ← 𝕩∊"←↩"
       (⊑g⊐1) (<⟜(≠g))◶⟨1,¬(" "∾∾idChars)∧´∘∊˜↑⟩ 𝕩
     }