Tutorial sections on identity functions and modified assignment

2 files changed, 71 insertions, 1 deletions

diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html
index 33ed9f53..06a0ec5c 100644
--- a/docs/tutorial/index.html
+++ b/docs/tutorial/index.html
@@ -35,7 +35,7 @@
 <tr>
 <td><a href="variable.html">Variables</a></td>
 <td>Declarations, cross-roles</td>
-<td><code><span class='Function'>∧∨¬↑↓«»</span><span class='Modifier2'>⌾</span></code></td>
+<td><code><span class='Function'>∧∨¬⊣⊢↑↓«»</span><span class='Modifier2'>⌾</span></code></td>
 </tr>
 </tbody>
 </table>
diff --git a/docs/tutorial/variable.html b/docs/tutorial/variable.html
index 6e9d5f8b..29a7775b 100644
--- a/docs/tutorial/variable.html
+++ b/docs/tutorial/variable.html
@@ -252,3 +252,73 @@ ERROR
 "abcdEFgh"
 </pre>
 <p>(Here I've snuck in a train <code><span class='Number'>2</span> <span class='Function'>↑</span> <span class='Number'>4</span><span class='Modifier2'>⊸</span><span class='Function'>↓</span></code> to combine the two functions. As an exercise, you might try to write that function using combinators instead, and as an extra hard exercise you might then ponder why someone would want to add trains to a language).</p>
+<h2 id="identity-functions">Identity functions</h2>
+<table class='primitives'>
+  <tr>
+    <td><span class='Function'>⊣</span></td>
+    <td><kbd>\{</kbd></td>
+    <td>Identity</td>
+    <td>Left</td>
+  </tr>
+  <tr>
+    <td><span class='Function'>⊢</span></td>
+    <td><kbd>\}</kbd></td>
+    <td>Identity</td>
+    <td>Right</td>
+  </tr>
+</table>
+
+<p>I'm not going to lie. I'm making this its own section so it looks like I plan ahead when I write these tutorials. The function Right (<code><span class='Function'>⊢</span></code>) always returns its right argument, and Left (<code><span class='Function'>⊣</span></code>) returns its left argument if there is one, and the right argument otherwise.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiICJvbmx5IgoK4oqjICJvbmx5IgoKImxlZnQiIOKKoiAicmlnaHQiCgoibGVmdCIg4oqjICJyaWdodCI=">↗️</a><pre>    <span class='Function'>⊢</span> <span class='String'>&quot;only&quot;</span>
+"only"
+
+    <span class='Function'>⊣</span> <span class='String'>&quot;only&quot;</span>
+"only"
+
+    <span class='String'>&quot;left&quot;</span> <span class='Function'>⊢</span> <span class='String'>&quot;right&quot;</span>
+"right"
+
+    <span class='String'>&quot;left&quot;</span> <span class='Function'>⊣</span> <span class='String'>&quot;right&quot;</span>
+"left"
+</pre>
+<p>They are not complicated functions: if you're confused it's because you don't understand why anyone would ever use them. Indeed, it's harder to see why these functions are useful than to see what they do. That is a fact.</p>
+<h2 id="modified-assignment">Modified assignment</h2>
+<p>Let's revisit our question about modifying an array. As we said, the answer to &quot;how do I modify part of an array?&quot; is simply that you can't, and that the question doesn't make sense. But there's a seemingly similar question with a very different answer: &quot;how do I modify part of a variable whose value is an array?&quot; This is because unlike an array, a variable isn't defined by the value it has, but by the name used to refer to it (and the scope it resides in). Here's how we would modify the variable <code><span class='Value'>a</span></code>:</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDihpAgNCAgICAgICAgICAgICMgRmlyc3QgaXQncyBhIG51bWJlcgphCgphIOKGqSA04oC/NeKAvzYgICAgICAgICMgTm93IGl0J3MgYSBsaXN0IQph">↗️</a><pre>    <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>4</span>            <span class='Comment'># First it's a number
+</span>    <span class='Value'>a</span>
+4
+
+    <span class='Value'>a</span> <span class='Gets'>↩</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>6</span>        <span class='Comment'># Now it's a list!
+</span>    <span class='Value'>a</span>
+⟨ 4 5 6 ⟩
+</pre>
+<p>But this changes the value of <code><span class='Value'>a</span></code> to a completely unrelated value. What if I want to apply a transformation to <code><span class='Value'>a</span></code>, for example to subtract one? Of course I can write the value <code><span class='Value'>a</span></code> on the right hand side of the assignment, but that's extra work and doesn't really seem to represent what I'm doing, which is conceptually just to apply a function to <code><span class='Value'>a</span></code>. So BQN also has a shorthand, called <em>modified assignment</em>. Here, the modified assignment <code><span class='Function'>-</span><span class='Gets'>↩</span></code> subtracts a value from <code><span class='Value'>a</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDihqkgYSAtIDEKYQoKYSAt4oapIDE=">↗️</a><pre>    <span class='Value'>a</span> <span class='Gets'>↩</span> <span class='Value'>a</span> <span class='Function'>-</span> <span class='Number'>1</span>
+    <span class='Value'>a</span>
+⟨ 3 4 5 ⟩
+
+    <span class='Value'>a</span> <span class='Function'>-</span><span class='Gets'>↩</span> <span class='Number'>1</span>
+⟨ 2 3 4 ⟩
+</pre>
+<p>(In case you're wondering why I didn't have to write <code><span class='Value'>a</span></code> again that last time, the evaluator suppresses the printed result for ordinary assignments but not modified ones. This is a feature of my website software and not the BQN language). It looks a lot like the special assignment operators <code><span class='Function'>+=</span></code>, <code><span class='Function'>/=</span></code>, and so on that you'll see in C or Javascript. What BQN brings to the table is that you can use any two-argument function at all here, because two-argument function are always written as operators. For example, we can prepend some elements to <code><span class='Value'>a</span></code>:</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDiiL7LnOKGqSAw4oC/MQ==">↗️</a><pre>    <span class='Value'>a</span> <span class='Function'>∾</span><span class='Modifier'>˜</span><span class='Gets'>↩</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span>
+⟨ 0 1 2 3 4 ⟩
+</pre>
+<p>But what about functions with only one argument? The syntax isn't the best, but at least it's possible. There still needs to be a value on the right side of the assignment even if it'll be ignored; I use the null character <code><span class='String'>@</span></code> for this. Then to turn a function that takes one argument into one that takes two, we can compose it with a function that takes two arguments and returns one of them. The left one, since the variable to modify is on the left hand side. Perhaps… Left? (<code><span class='Function'>⊣</span></code>)?</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImFiY2QiIOKMveKImOKKoyAid3h5eiIKCmEg4oy94oiY4oqj4oapIEA=">↗️</a><pre>    <span class='String'>&quot;abcd&quot;</span> <span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>⊣</span> <span class='String'>&quot;wxyz&quot;</span>
+"dcba"
+
+    <span class='Value'>a</span> <span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>⊣</span><span class='Gets'>↩</span> <span class='String'>@</span>
+⟨ 4 3 2 1 0 ⟩
+</pre>
+<p>Notice that there's no need for parentheses: modifiers bind more strongly than the assignment character. Now what if we want to decrease the last two elements of <code><span class='Value'>a</span></code>? That is, we want to compute the following array while storing it in <code><span class='Value'>a</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=LeKfnDTijL4owq8y4oq44oaRKSBhCgphICAgICAgICAgICAgICAgICMgSXQgaGFzbid0IGNoYW5nZWQsIG9mIGNvdXJzZQ==">↗️</a><pre>    <span class='Function'>-</span><span class='Modifier2'>⟜</span><span class='Number'>4</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'>a</span>
+⟨ 4 3 2 ¯3 ¯4 ⟩
+
+    <span class='Value'>a</span>                <span class='Comment'># It hasn't changed, of course
+</span>⟨ 4 3 2 1 0 ⟩
+</pre>
+<p>The code to do this looks the same as what we did with Reverse (<code><span class='Function'>⌽</span></code>). Again we don't have to parenthesize the function, because modifiers associate from left to right, so Under (<code><span class='Modifier2'>⌾</span></code>) binds to its operands before Compose (<code><span class='Modifier2'>∘</span></code>) does.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSAt4p+cNOKMvijCrzLiirjihpEp4oiY4oqj4oapIEA=">↗️</a><pre>    <span class='Value'>a</span> <span class='Function'>-</span><span class='Modifier2'>⟜</span><span class='Number'>4</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='Modifier2'>∘</span><span class='Function'>⊣</span><span class='Gets'>↩</span> <span class='String'>@</span>
+⟨ 4 3 2 ¯3 ¯4 ⟩
+</pre>