Documentation for Valences

9 files changed, 75 insertions, 3 deletions

diff --git a/doc/README.md b/doc/README.md
index 26374f5c..8acd5740 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -71,6 +71,7 @@ Primitives:
 - [Take and Drop](take.md) (`↑`)
 - [Transpose](transpose.md) (`⍉`)
 - [Undo](undo.md) (`⁼`)
+- [Valences](valences.md) (`⊘`)
 - [Windows](windows.md) (`↕`)
 
 Environment:
diff --git a/doc/combinator.bqn b/doc/combinator.bqn
index fa4466f7..e16dc5a9 100644
--- a/doc/combinator.bqn
+++ b/doc/combinator.bqn
@@ -4,7 +4,7 @@ w‿h ← 280‿260
 Pnt ← 32‿57×⌽
 
 comps ← "∘○˙⊸⟜˜⊘"
-names ← (¬×+`)⊸-∘=⟜' '⊸⊔ "Atop Over Constant Before After Self/Swap Cases"
+names ← (¬×+`)⊸-∘=⟜' '⊸⊔ "Atop Over Constant Before After Self/Swap Valences"
 
 ps ← At "class=yellow|style=fill:none|stroke-width=2"
 _trans ← {𝕗 At "transform=translate("∾(⊣∾","∾⊢)○FmtNum∾")"˙}
diff --git a/doc/primitive.md b/doc/primitive.md
index c358d80a..b1253e3c 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -74,7 +74,7 @@ Glyph | Name(s)                 | Definition                     | Description
 `⊸`   | 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
+`⊘`   | [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 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/doc/valences.md b/doc/valences.md
new file mode 100644
index 00000000..7c2c9d59
--- /dev/null
+++ b/doc/valences.md
@@ -0,0 +1,19 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/valences.html).*
+
+# Valences
+
+<!--GEN combinator.bqn
+DrawComp ≍"⊘"
+-->
+
+Every BQN function can be called with one or two arguments, possibly doing completely different things in each case. The Valences (`⊘`) 2-modifier grafts together a one-argument function `𝔽` and a two-argument function `𝔾`, with the resulting function calling one or the other as appropriate. It's the [tacit](tacit.md) equivalent of a block function with [two bodies](block.md#multiple-bodies). So the function `{÷𝕩 ; 𝕩-𝕨}` can also be written `÷⊘(-˜)`. A full definition of Valences as a block is `{𝔽𝕩;𝕨𝔾𝕩}`.
+
+          -⊘+ 6  # - side
+
+        3 -⊘+ 2  # + side
+
+Valences provides one way to check whether `𝕨` is present in a block function. The expression `𝕨0⊘1𝕩` always ignores the values of the arguments, resulting in `0` if `𝕨` isn't given and `1` if it is (if you want `1` or `2`, then `≠𝕨⋈𝕩` is shorter, but I'm not sure if I like it).
+
+            {𝕨0⊘1𝕩} 'x'
+
+        'w' {𝕨0⊘1𝕩} 'x'
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 5d303de3..c3d6ea2b 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -77,6 +77,7 @@
 <li><a href="take.html">Take and Drop</a> (<code><span class='Function'>↑</span></code>)</li>
 <li><a href="transpose.html">Transpose</a> (<code><span class='Function'>⍉</span></code>)</li>
 <li><a href="undo.html">Undo</a> (<code><span class='Modifier'>⁼</span></code>)</li>
+<li><a href="valences.html">Valences</a> (<code><span class='Modifier2'>⊘</span></code>)</li>
 <li><a href="windows.html">Windows</a> (<code><span class='Function'>↕</span></code>)</li>
 </ul>
 <p>Environment:</p>
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index 1601ed08..44a0e14b 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -467,7 +467,7 @@
 </tr>
 <tr>
 <td><code><span class='Modifier2'>⊘</span></code></td>
-<td>Valences</td>
+<td><a href="valences.html">Valences</a></td>
 <td><code><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Head'>;</span><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td>
 <td>Apply <code><span class='Function'>𝔽</span></code> if there's one argument but <code><span class='Function'>𝔾</span></code> if there are two</td>
 </tr>
diff --git a/docs/doc/valences.html b/docs/doc/valences.html
new file mode 100644
index 00000000..90812056
--- /dev/null
+++ b/docs/doc/valences.html
@@ -0,0 +1,47 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Valences</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="valences"><a class="header" href="#valences">Valences</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'>Valences</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='Function'>𝔽</tspan><tspan class='Modifier2'>⊘</tspan><tspan class='Function'>𝔾</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0Q0 57 0 114'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='0'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='114'/>
+      <text dy='0.32em' x='0' y='0'><tspan class='Function'>𝔽</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='Function'>𝔽</tspan><tspan class='Modifier2'>⊘</tspan><tspan class='Function'>𝔾</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0C-40 57 -32 51.3 -32 114'/>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0C40 57 32 51.3 32 114'/>
+      <circle r='12' class='code' stroke-width='0' cx='0' cy='0'/>
+      <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='0'><tspan class='Function'>𝔾</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>Every BQN function can be called with one or two arguments, possibly doing completely different things in each case. The Valences (<code><span class='Modifier2'>⊘</span></code>) 2-modifier grafts together a one-argument function <code><span class='Function'>𝔽</span></code> and a two-argument function <code><span class='Function'>𝔾</span></code>, with the resulting function calling one or the other as appropriate. It's the <a href="tacit.html">tacit</a> equivalent of a block function with <a href="block.html#multiple-bodies">two bodies</a>. So the function <code><span class='Brace'>{</span><span class='Function'>÷</span><span class='Value'>𝕩</span> <span class='Head'>;</span> <span class='Value'>𝕩</span><span class='Function'>-</span><span class='Value'>𝕨</span><span class='Brace'>}</span></code> can also be written <code><span class='Function'>÷</span><span class='Modifier2'>⊘</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Modifier'>˜</span><span class='Paren'>)</span></code>. A full definition of Valences as a block is <code><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Head'>;</span><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ICAt4oqYKyA2ICAjIC0gc2lkZQoKMyAt4oqYKyAyICAjICsgc2lkZQ==">↗️</a><pre>      <span class='Function'>-</span><span class='Modifier2'>⊘</span><span class='Function'>+</span> <span class='Number'>6</span>  <span class='Comment'># - side
+</span>¯6
+
+    <span class='Number'>3</span> <span class='Function'>-</span><span class='Modifier2'>⊘</span><span class='Function'>+</span> <span class='Number'>2</span>  <span class='Comment'># + side
+</span>5
+</pre>
+<p>Valences provides one way to check whether <code><span class='Value'>𝕨</span></code> is present in a block function. The expression <code><span class='Value'>𝕨</span><span class='Number'>0</span><span class='Modifier2'>⊘</span><span class='Number'>1</span><span class='Value'>𝕩</span></code> always ignores the values of the arguments, resulting in <code><span class='Number'>0</span></code> if <code><span class='Value'>𝕨</span></code> isn't given and <code><span class='Number'>1</span></code> if it is (if you want <code><span class='Number'>1</span></code> or <code><span class='Number'>2</span></code>, then <code><span class='Function'>≠</span><span class='Value'>𝕨</span><span class='Function'>⋈</span><span class='Value'>𝕩</span></code> is shorter, but I'm not sure if I like it).</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ICAgIHvwnZWoMOKKmDHwnZWpfSAneCcKCid3JyB78J2VqDDiipgx8J2VqX0gJ3gn">↗️</a><pre>        <span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Number'>0</span><span class='Modifier2'>⊘</span><span class='Number'>1</span><span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='String'>'x'</span>
+0
+
+    <span class='String'>'w'</span> <span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Number'>0</span><span class='Modifier2'>⊘</span><span class='Number'>1</span><span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='String'>'x'</span>
+1
+</pre>
diff --git a/docs/help/valences.html b/docs/help/valences.html
index 90848a48..2600623b 100644
--- a/docs/help/valences.html
+++ b/docs/help/valences.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="circled-division-slash-"><a class="header" href="#circled-division-slash-">Circled Division Slash (<code><span class='Modifier2'>⊘</span></code>)</a></h1>
 <h2 id="𝔽𝔾-𝕩-valences"><a class="header" href="#𝔽𝔾-𝕩-valences"><code><span class='Function'>𝔽</span><span class='Modifier2'>⊘</span><span class='Function'>𝔾</span> <span class='Value'>𝕩</span></code>: Valences</a></h2>
+<p><a class="fulldoc" href="../doc/valences.html">→full documentation</a></p>
 <p>Apply <code><span class='Function'>𝔽</span></code> to <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=K+KKmC0gNQoKLeKKmCsgNQ==">↗️</a><pre>    <span class='Function'>+</span><span class='Modifier2'>⊘</span><span class='Function'>-</span> <span class='Number'>5</span>
 5
@@ -14,6 +15,7 @@
 ¯5
 </pre>
 <h2 id="𝕨-𝔽𝔾-𝕩-dyadic-valences"><a class="header" href="#𝕨-𝔽𝔾-𝕩-dyadic-valences"><code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier2'>⊘</span><span class='Function'>𝔾</span> <span class='Value'>𝕩</span></code>: Dyadic Valences</a></h2>
+<p><a class="fulldoc" href="../doc/valences.html">→full documentation</a></p>
 <p>Apply <code><span class='Function'>𝔾</span></code> to <code><span class='Value'>𝕨</span></code> and <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=NCAr4oqYLSA1Cgo0IC3iipgrIDU=">↗️</a><pre>    <span class='Number'>4</span> <span class='Function'>+</span><span class='Modifier2'>⊘</span><span class='Function'>-</span> <span class='Number'>5</span>
 ¯1
diff --git a/help/valences.md b/help/valences.md
index 2a220848..f71c5bc3 100644
--- a/help/valences.md
+++ b/help/valences.md
@@ -3,6 +3,7 @@
 # Circled Division Slash (`⊘`)
 
 ## `𝔽⊘𝔾 𝕩`: Valences
+[→full documentation](../doc/valences.md)
 
 Apply `𝔽` to `𝕩`.
 
@@ -13,6 +14,7 @@ Apply `𝔽` to `𝕩`.
 
 
 ## `𝕨 𝔽⊘𝔾 𝕩`: Dyadic Valences
+[→full documentation](../doc/valences.md)
 
 Apply `𝔾` to `𝕨` and `𝕩`.