Documentation for Self/Swap

8 files changed, 117 insertions, 2 deletions

diff --git a/doc/README.md b/doc/README.md
index 4f8c49cf..0560a3a6 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -63,6 +63,7 @@ Primitives:
 - [Scan](scan.md) (`` ` ``)
 - [Search functions](search.md) (`⊐⊒∊`)
 - [Select](select.md) (`⊏`)
+- [Self and Swap](swap.md) (`˜`)
 - [Self-search functions](selfcmp.md) (`⊐⊒∊⍷`)
 - [Shift functions](shift.md) (`»«`)
 - [Solo, Couple, and Merge](couple.md) (`≍>`)
diff --git a/doc/primitive.md b/doc/primitive.md
index 03634235..f2b47341 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -68,7 +68,7 @@ Functions that have significant differences from APL equivalents or don't appear
 Glyph | Name(s)            | Definition                     | Description
 ------|--------------------|--------------------------------|---------------------------------------
 `˙`   | Constant           | `{𝕩⋄𝕗}`                        | Return a function that returns the operand
-`˜`   | Self/Swap          | `{𝕩𝔽𝕨⊣𝕩}`                      | Duplicate one argument or exchange two
+`˜`   | [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 `𝔽`
diff --git a/doc/swap.md b/doc/swap.md
new file mode 100644
index 00000000..0d9245e3
--- /dev/null
+++ b/doc/swap.md
@@ -0,0 +1,30 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/swap.html).*
+
+# Self and Swap
+
+<!--GEN combinator.bqn
+DrawComp ≍"˜"
+-->
+
+Have the arguments to a function, but not in the right places? Self/Swap (`˜`) will fix it for you. There are only two APL-style 1-modifiers—that is, operands used as functions and applied to arguments—that make sense, and `˜` is both of them. It always calls its operand with two arguments: if there are two arguments to begin with, they are exchanged (Swap), and if there's only one, it's used for both arguments (Self).
+
+| Name | Call   | Definition
+|------|--------|:----------:
+| Self | ` F˜𝕩` |    `𝕩F𝕩`
+| Swap | `𝕨F˜𝕩` |    `𝕩F𝕨`
+
+Since `𝕩` is always the left argument, these two definitions can be unified as `{𝕩𝔽𝕨⊣𝕩}`, noting that [Left](identity.md) becomes a plain identity function when the left argument `𝕨` isn't given.
+
+Swap is arguably less transformative. Some common examples are `-˜` and `÷˜`, since these two functions run the [wrong way](../commentary/problems.md#subtraction-division-and-span-are-backwards) for BQN's evaluation order. This is very often useful in [tacit](tacit.md) programming, and less useful for explicit code. While it sometimes allows for shorter code by making a pair of parentheses unnecessary (say, `(a×b)-c` is `c-˜a×b`), I personally don't think this is always a good idea. My opinion is that it should be used when it makes the semantics a better fit for BQN, but putting the primary argument on the right and a secondary or control argument on the left.
+
+        'a' ⋈˜ 'b'
+
+        " +" ⊏˜ 0‿1‿1‿0‿0≍1‿0‿1‿0‿1
+
+Self re-uses one argument twice. In this way it's a little like [Over](compose.md), which re-uses one *function* twice. A common combination is with Table, `⌜˜`, so that the operand function is called on each combination of elements from the argument to form a square result. For example, `=⌜˜` applied to `↕n` gives the identity matrix of size `n`.
+
+        ט 4
+
+        =⌜˜ ↕3
+
+Note that Self isn't needed with Before (`⊸`) and After (`⟜`), which essentially have a copy built in: for example `F⊸G 𝕩` is the same as `F⊸G˜ 𝕩` by definition.
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 821de18a..38f7d2cd 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -69,6 +69,7 @@
 <li><a href="scan.html">Scan</a> (<code><span class='Modifier'>`</span></code>)</li>
 <li><a href="search.html">Search functions</a> (<code><span class='Function'>⊐⊒∊</span></code>)</li>
 <li><a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>)</li>
+<li><a href="swap.html">Self and Swap</a> (<code><span class='Modifier'>˜</span></code>)</li>
 <li><a href="selfcmp.html">Self-search functions</a> (<code><span class='Function'>⊐⊒∊⍷</span></code>)</li>
 <li><a href="shift.html">Shift functions</a> (<code><span class='Function'>»«</span></code>)</li>
 <li><a href="couple.html">Solo, Couple, and Merge</a> (<code><span class='Function'>≍&gt;</span></code>)</li>
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index dda31281..c4b48a20 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -431,7 +431,7 @@
 </tr>
 <tr>
 <td><code><span class='Modifier'>˜</span></code></td>
-<td>Self/Swap</td>
+<td><a href="swap.html">Self/Swap</a></td>
 <td><code><span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Function'>𝔽</span><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td>
 <td>Duplicate one argument or exchange two</td>
 </tr>
diff --git a/docs/doc/swap.html b/docs/doc/swap.html
new file mode 100644
index 00000000..190b0d0a
--- /dev/null
+++ b/docs/doc/swap.html
@@ -0,0 +1,79 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Self and Swap</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="self-and-swap"><a class="header" href="#self-and-swap">Self and Swap</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'>Self/Swap</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='Modifier'>˜</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0Q-41.6 57 0 114'/>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0Q41.6 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='Modifier'>˜</tspan> <tspan class='Value'>𝕩</tspan></text>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0C-40 28.5 0 57 32 114'/>
+      <path class='yellow' style='fill:none' stroke-width='2' d='M0 0C40 28.5 0 57 -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>Have the arguments to a function, but not in the right places? Self/Swap (<code><span class='Modifier'>˜</span></code>) will fix it for you. There are only two APL-style 1-modifiers—that is, operands used as functions and applied to arguments—that make sense, and <code><span class='Modifier'>˜</span></code> is both of them. It always calls its operand with two arguments: if there are two arguments to begin with, they are exchanged (Swap), and if there's only one, it's used for both arguments (Self).</p>
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Call</th>
+<th align="center">Definition</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Self</td>
+<td><code> <span class='Function'>F</span><span class='Modifier'>˜</span><span class='Value'>𝕩</span></code></td>
+<td align="center"><code><span class='Value'>𝕩</span><span class='Function'>F</span><span class='Value'>𝕩</span></code></td>
+</tr>
+<tr>
+<td>Swap</td>
+<td><code><span class='Value'>𝕨</span><span class='Function'>F</span><span class='Modifier'>˜</span><span class='Value'>𝕩</span></code></td>
+<td align="center"><code><span class='Value'>𝕩</span><span class='Function'>F</span><span class='Value'>𝕨</span></code></td>
+</tr>
+</tbody>
+</table>
+<p>Since <code><span class='Value'>𝕩</span></code> is always the left argument, these two definitions can be unified as <code><span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Function'>𝔽</span><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code>, noting that <a href="identity.html">Left</a> becomes a plain identity function when the left argument <code><span class='Value'>𝕨</span></code> isn't given.</p>
+<p>Swap is arguably less transformative. Some common examples are <code><span class='Function'>-</span><span class='Modifier'>˜</span></code> and <code><span class='Function'>÷</span><span class='Modifier'>˜</span></code>, since these two functions run the <a href="../commentary/problems.html#subtraction-division-and-span-are-backwards">wrong way</a> for BQN's evaluation order. This is very often useful in <a href="tacit.html">tacit</a> programming, and less useful for explicit code. While it sometimes allows for shorter code by making a pair of parentheses unnecessary (say, <code><span class='Paren'>(</span><span class='Value'>a</span><span class='Function'>×</span><span class='Value'>b</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Value'>c</span></code> is <code><span class='Value'>c</span><span class='Function'>-</span><span class='Modifier'>˜</span><span class='Value'>a</span><span class='Function'>×</span><span class='Value'>b</span></code>), I personally don't think this is always a good idea. My opinion is that it should be used when it makes the semantics a better fit for BQN, but putting the primary argument on the right and a secondary or control argument on the left.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=J2EnIOKLiMucICdiJwoKIiArIiDiio/LnCAw4oC/MeKAvzHigL8w4oC/MOKJjTHigL8w4oC/MeKAvzDigL8x">↗️</a><pre>    <span class='String'>'a'</span> <span class='Function'>⋈</span><span class='Modifier'>˜</span> <span class='String'>'b'</span>
+"ba"
+
+    <span class='String'>&quot; +&quot;</span> <span class='Function'>⊏</span><span class='Modifier'>˜</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Function'>≍</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span>
+┌─       
+╵" ++    
+  + + +" 
+        ┘
+</pre>
+<p>Self re-uses one argument twice. In this way it's a little like <a href="compose.html">Over</a>, which re-uses one <em>function</em> twice. A common combination is with Table, <code><span class='Modifier'>⌜˜</span></code>, so that the operand function is called on each combination of elements from the argument to form a square result. For example, <code><span class='Function'>=</span><span class='Modifier'>⌜˜</span></code> applied to <code><span class='Function'>↕</span><span class='Value'>n</span></code> gives the identity matrix of size <code><span class='Value'>n</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=w5fLnCA0Cgo94oycy5wg4oaVMw==">↗️</a><pre>    <span class='Function'>×</span><span class='Modifier'>˜</span> <span class='Number'>4</span>
+16
+
+    <span class='Function'>=</span><span class='Modifier'>⌜˜</span> <span class='Function'>↕</span><span class='Number'>3</span>
+┌─       
+╵ 1 0 0  
+  0 1 0  
+  0 0 1  
+        ┘
+</pre>
+<p>Note that Self isn't needed with Before (<code><span class='Modifier2'>⊸</span></code>) and After (<code><span class='Modifier2'>⟜</span></code>), which essentially have a copy built in: for example <code><span class='Function'>F</span><span class='Modifier2'>⊸</span><span class='Function'>G</span> <span class='Value'>𝕩</span></code> is the same as <code><span class='Function'>F</span><span class='Modifier2'>⊸</span><span class='Function'>G</span><span class='Modifier'>˜</span> <span class='Value'>𝕩</span></code> by definition.</p>
diff --git a/docs/help/self_swap.html b/docs/help/self_swap.html
index 3cf26801..cd3e0a1c 100644
--- a/docs/help/self_swap.html
+++ b/docs/help/self_swap.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="small-tilde-"><a class="header" href="#small-tilde-">Small Tilde (<code><span class='Modifier'>˜</span></code>)</a></h1>
 <h2 id="𝔽-𝕩-self"><a class="header" href="#𝔽-𝕩-self"><code><span class='Function'>𝔽</span><span class='Modifier'>˜</span> <span class='Value'>𝕩</span></code>: Self</a></h2>
+<p><a class="fulldoc" href="../doc/swap.html">→full documentation</a></p>
 <p>Supplies <code><span class='Value'>𝕩</span></code> as a left argument to <code><span class='Function'>𝔽</span></code> (<code><span class='Value'>𝕩</span> <span class='Function'>𝔽</span> <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=MSArIDEKCivLnCAx">↗️</a><pre>    <span class='Number'>1</span> <span class='Function'>+</span> <span class='Number'>1</span>
 2
@@ -14,6 +15,7 @@
 2
 </pre>
 <h2 id="𝕨-𝔽-𝕩-swap"><a class="header" href="#𝕨-𝔽-𝕩-swap"><code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier'>˜</span> <span class='Value'>𝕩</span></code>: Swap</a></h2>
+<p><a class="fulldoc" href="../doc/swap.html">→full documentation</a></p>
 <p>Swaps the arguments of <code><span class='Function'>𝔽</span></code> (<code><span class='Value'>𝕩</span> <span class='Function'>𝔽</span> <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=MSAtIDIKCjEgLcucIDI=">↗️</a><pre>    <span class='Number'>1</span> <span class='Function'>-</span> <span class='Number'>2</span>
 ¯1
diff --git a/help/self_swap.md b/help/self_swap.md
index c1e66008..23f1372d 100644
--- a/help/self_swap.md
+++ b/help/self_swap.md
@@ -3,6 +3,7 @@
 # Small Tilde (`˜`)
 
 ## `𝔽˜ 𝕩`: Self
+[→full documentation](../doc/swap.md)
 
 Supplies `𝕩` as a left argument to `𝔽` (`𝕩 𝔽 𝕩`).
 
@@ -13,6 +14,7 @@ Supplies `𝕩` as a left argument to `𝔽` (`𝕩 𝔽 𝕩`).
 
 
 ## `𝕨 𝔽˜ 𝕩`: Swap
+[→full documentation](../doc/swap.md)
 
 Swaps the arguments of `𝔽` (`𝕩 𝔽 𝕨`).