Finish lexical scope documentation

10 files changed, 75 insertions, 10 deletions

diff --git a/docs/doc/block.html b/docs/doc/block.html
index eb57da8d..cd124aa9 100644
--- a/docs/doc/block.html
+++ b/docs/doc/block.html
@@ -12,7 +12,7 @@
     <span class='Function'>×</span><span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='Number'>4</span>
 16
 </pre>
-<p>Because they use <a href="https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scoping">lexical scoping</a>, blocks can also be used to encapsulate code. If a block uses only variables that it initializes, then it has no dependence on its environment and would work the same way if defined anywhere. But it can also use external variables, defined in a containing block.</p>
+<p>Because they use <a href="lexical.html">lexical scoping</a>, blocks can also be used to encapsulate code. If a block uses only variables that it initializes, then it has no dependence on its environment and would work the same way if defined anywhere. But it can also use external variables, defined in a containing block.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YeKGkGLihpAib3V0ZXIiCnsgYeKGkCJpbm5lciIg4ouEIGHigL9iIH0=">↗️</a><pre>    <span class='Value'>a</span><span class='Gets'>←</span><span class='Value'>b</span><span class='Gets'>←</span><span class='String'>&quot;outer&quot;</span>
     <span class='Brace'>{</span> <span class='Value'>a</span><span class='Gets'>←</span><span class='String'>&quot;inner&quot;</span> <span class='Separator'>⋄</span> <span class='Value'>a</span><span class='Ligature'>‿</span><span class='Value'>b</span> <span class='Brace'>}</span>
 ⟨ "inner" "outer" ⟩
diff --git a/docs/doc/control.html b/docs/doc/control.html
index c00ce6e5..bf8f65de 100644
--- a/docs/doc/control.html
+++ b/docs/doc/control.html
@@ -22,7 +22,7 @@
 <span class='Function'>Test</span>    <span class='Gets'>←</span> <span class='Brace'>{</span><span class='Value'>fn</span><span class='Gets'>←</span><span class='Brace'>{</span><span class='Function'>C</span><span class='Ligature'>‿</span><span class='Function'>A𝕊</span><span class='Value'>e:</span><span class='Function'>C</span><span class='Modifier2'>◶</span><span class='Function'>A</span><span class='Ligature'>‿</span><span class='Function'>E</span><span class='Brace'>}</span><span class='Modifier'>´</span><span class='Value'>𝕩</span><span class='Separator'>⋄</span><span class='Function'>Fn</span><span class='String'>@</span><span class='Brace'>}</span>
 </pre>
 <h2 id="blocks-and-functions">Blocks and functions</h2>
-<p>Control structures are generally defined to work with blocks of code, which they might skip, or execute one or more times. This might sound like a BQN immediate block, which also consists of a sequence of code to execute, but immediate blocks are always executed as soon as they are encountered and can't be manipulated the way that blocks in imperative languages can. They're intended to be used with lexical scoping as a tool for encapsulation. Instead, the main tool we will use to get control structures is the block function.</p>
+<p>Control structures are generally defined to work with blocks of code, which they might skip, or execute one or more times. This might sound like a BQN immediate block, which also consists of a sequence of code to execute, but immediate blocks are always executed as soon as they are encountered and can't be manipulated the way that blocks in imperative languages can. They're intended to be used with <a href="lexical.html">lexical scoping</a> as a tool for encapsulation. Instead, the main tool we will use to get control structures is the block function.</p>
 <p>Using functions as blocks is a little outside their intended purpose, and the fact that they have to be passed an argument and are expected to use it will be a minor annoyance. The following conventions signal a function that ignores its argument and is called purely for the side effects:</p>
 <ul>
 <li>Pass <code><span class='String'>@</span></code> to a function that ignores its argument. It's a nice signal that nothing is happening and is easy to type.</li>
diff --git a/docs/doc/embed.html b/docs/doc/embed.html
index de7709ca..4b4e0365 100644
--- a/docs/doc/embed.html
+++ b/docs/doc/embed.html
@@ -11,7 +11,7 @@
 <p>Probably you can figure out the easy things like calling <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>&quot;×´1+↕6&quot;</span><span class='Paren'>)</span></code> to compute six factorial. But how do you get JS and BQN to <em>talk</em> to each other, for example to compute the factorial of a number <code><span class='Value'>n</span></code>? Constructing a source string with <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>&quot;×´1+↕&quot;</span><span class='Function'>+</span><span class='Value'>n</span><span class='Paren'>)</span></code> isn't the best way—in fact I would recommend you never use this strategy.</p>
 <p>Instead, return a function from BQN and call it: <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>&quot;{×´1+↕𝕩}&quot;</span><span class='Paren'>)(</span><span class='Value'>n</span><span class='Paren'>)</span></code>. This strategy also has the advantage that you can store the function, so that it will only be compiled once. Define <code><span class='Value'>let</span> <span class='Value'>fact</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>&quot;{×´1+↕𝕩}&quot;</span><span class='Paren'>)</span><span class='Value'>;</span></code> at the top of your program and use it as a function elsewhere.</p>
 <p>BQN can also call JS functions, to use functionality that isn't native to BQN or interact with a program written in JS. For example, <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>&quot;{𝕏'a'+↕26}&quot;</span><span class='Paren'>)(</span><span class='Value'>alert</span><span class='Paren'>)</span></code> calls the argument <code><span class='Value'>alert</span></code> from within BQN. The displayed output isn't quite right here, because a BQN string is stored as a JS array, not a string. See the next section for more information.</p>
-<p>Cool, but none of these examples really use closures, just self-contained functions. Closures are functions that use outside state, which is maintained over the course of the program. Here's an example program that defines <code><span class='Value'>i</span></code> and then returns a function that manipulates <code><span class='Value'>i</span></code> and returns its new value.</p>
+<p>Cool, but none of these examples really use closures, just self-contained functions. <a href="lexical.html#closures">Closures</a> are functions that use outside state, which is maintained over the course of the program. Here's an example program that defines <code><span class='Value'>i</span></code> and then returns a function that manipulates <code><span class='Value'>i</span></code> and returns its new value.</p>
 <pre><span class='Value'>let</span> <span class='Value'>push</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='Modifier'>`</span>
     <span class='Value'>i</span><span class='Gets'>←</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='Number'>0</span>
     <span class='Brace'>{</span><span class='Value'>i</span><span class='Function'>+</span><span class='Gets'>↩</span><span class='Value'>𝕩</span><span class='Function'>»</span><span class='Value'>i</span><span class='Brace'>}</span>
diff --git a/docs/doc/fromJ.html b/docs/doc/fromJ.html
index 3c5ad0a2..e5407e07 100644
--- a/docs/doc/fromJ.html
+++ b/docs/doc/fromJ.html
@@ -107,7 +107,7 @@
 </tr>
 </tbody>
 </table>
-<p>BQN's explicit functions and modifiers are called &quot;blocks&quot;, and have a more sophisticated syntax than J; see <a href="block.html">the documentation</a>. BQN uses lexical scope, and has no global variables. BQN also has a <a href="syntax.html#list-notation">list notation</a> using <code><span class='Bracket'>⟨⟩</span></code>.</p>
+<p>BQN's explicit functions and modifiers are called &quot;blocks&quot;, and have a more sophisticated syntax than J; see <a href="block.html">the documentation</a>. BQN uses <a href="lexical.html">lexical scope</a>, and has no global variables. BQN also has a <a href="syntax.html#list-notation">list notation</a> using <code><span class='Bracket'>⟨⟩</span></code>.</p>
 <h2 id="for-reading">For reading</h2>
 <p>J analogues of BQN primitive functions are given below. They are not always the same; usually this is because BQN has extra functionality relative to J, although in some cases it has less or different functionality.</p>
 <p>Functions <code><span class='Function'>+</span></code> <code><span class='Function'>-</span></code> <code><span class='Function'>|</span></code> <code><span class='Function'>&lt;</span></code> <code><span class='Function'>&gt;</span></code> are the same in both languages.</p>
diff --git a/docs/doc/functional.html b/docs/doc/functional.html
index f0149660..50d70af5 100644
--- a/docs/doc/functional.html
+++ b/docs/doc/functional.html
@@ -60,7 +60,7 @@
 </svg>
 
 <p>The term <em>functional programming</em> is more contentious, and has many meanings some of which can be vague. Here I use it for what might be called <em>first-class functional programming</em>, programming that makes significant use of first-class functions; in this usage, Scheme is probably the archetypal functional programming language. However, other definitions are also worth mentioning. APL is often called a functional programming language on the grounds that functions can be assigned and manipulated, and called recursively, all characteristics it shares with Lisp. I prefer the term <em>function-level programming</em> for this usage. A newer usage, which I call <em>pure functional programming</em>, restricts the term &quot;function&quot; to mathematical functions, which have no side effects, so that functional programming is programming with no side effects, often using monads to accumulate effects as part of arguments and results instead. Finally, <em>typed functional programming</em> is closely associated with pure functional programming and refers to languages influenced by type theory such as Haskell, F#, and Idris (the last of which even supports <em>dependently-typed functional programming</em>, but I already said &quot;finally&quot; so we'll stop there). Of these, BQN supports first-class functional and function-level programming, allows but doesn't encourage pure functional programming, and does not support typed functional programming, as it's dynamically and not statically typed.</p>
-<p>Another topic we are interested in is <em>lexical scoping</em> and <em>closures</em>. Lexical scoping means that the realm in which a variable exists is determined by its containing context (in BQN, the surrounding set of curly braces <code><span class='Brace'>{}</span></code>, if any) within the source code. A closure is really an implementation mechanism, but it's often used to refer to a property of lexical scoping that appears when functions defined in a particular block can be accessed after the block finishes execution. For example, they might be returned from a function or assigned to a variable outside of that function's scope. In this case the functions can still access variables in the original scope. I consider this property to be a requirement for a correct lexical scoping implementation, but it's traditionally not a part of APL: implementation might not have lexical scoping (for example, J and I believe A+ use static scoping where functions can't access variables in containing scopes) or might cut off the scope once execution ends, leading to value errors that one wouldn't predict from the rules of lexical scoping.</p>
+<p>Another topic we are interested in is <em>lexical scoping</em> and <em>closures</em>. <a href="lexical.html">Lexical scoping</a> means that the realm in which a variable exists is determined by its containing context (in BQN, the surrounding set of curly braces <code><span class='Brace'>{}</span></code>, if any) within the source code. A closure is really an implementation mechanism, but it's often used to refer to a property of lexical scoping that appears when functions defined in a particular block can be accessed after the block finishes execution. For example, they might be returned from a function or assigned to a variable outside of that function's scope. In this case the functions can still access variables in the original scope. I consider this property to be a requirement for a correct lexical scoping implementation, but it's traditionally not a part of APL: implementation might not have lexical scoping (for example, J and I believe A+ use static scoping where functions can't access variables in containing scopes) or might cut off the scope once execution ends, leading to value errors that one wouldn't predict from the rules of lexical scoping.</p>
 <h2 id="functions-in-apl">Functions in APL</h2>
 <p>This seems like a good place for a brief and entirely optional discussion of how APL handles functions and why it does it this way. As mentioned above, APL's functions are second class rather than first class. But the barriers to making functions first-class objects have been entirely syntactic and conceptual, not technical. In fact, the J language has for a long time had <a href="http://www.jsoftware.com/pipermail/programming/2013-January/031260.html">a bug</a> that allows an array containing a function to be created: by selecting from the array, the function itself can even be passed through tacit functions as an argument!</p>
 <p>The primary reason why APL doesn't allow functions to be passed as arguments is probably syntax: in particular, there's no way to say that a function should be used as the left argument to another function, as an expression like <code><span class='Function'>F</span> <span class='Function'>G</span> <span class='Value'>x</span></code> with functions <code><span class='Function'>F</span></code> and <code><span class='Function'>G</span></code> and an array <code><span class='Value'>x</span></code> will simply be evaluated as two monadic function applications. However, there's no syntactic rule that prevents a function from returning a function, and Dyalog APL for example allows this (so <code><span class='Value'>⍎</span><span class='String'>'+'</span></code> returns the function <code><span class='Function'>+</span></code>). Dyalog's <code><span class='Value'>⎕</span><span class='Function'>OR</span></code> is another interesting phenomenon in this context: it creates an array from a function or operator, which can then be used as an element or argument like any array. The mechanism is essentially the same as BQN's first class functions, and in fact <code><span class='Value'>⎕</span><span class='Function'>OR</span></code>s even share a form of BQN's <a href="../commentary/problems.html#syntactic-type-erasure">syntactic type erasure</a>, as a <code><span class='Value'>⎕</span><span class='Function'>OR</span></code> of a function passed as an operand magically becomes a function again. But outside of this property, it's cumbersome and slow to convert functions to and from <code><span class='Value'>⎕</span><span class='Function'>OR</span></code>s, so they don't work very well as a first-class function mechanism.</p>
@@ -75,7 +75,7 @@
   <span class='Value'>v0</span> <span class='Function'>+</span> <span class='Paren'>((</span><span class='Function'>𝕏</span> <span class='Number'>1</span><span class='Paren'>)</span> <span class='Function'>-</span> <span class='Value'>v0</span><span class='Paren'>)</span> <span class='Function'>×</span> <span class='Function'>⊢</span>
 <span class='Brace'>}</span>
 </pre>
-<p>We can pass it the <a href="arithmetic.html#basic-arithmetic">exponential</a> function as an argument by giving it the name <code><span class='Function'>Exp</span></code> and then referring to it in lowercase (that is, in a subject role). The result is a <a href="train.html">train</a> that adds 1 to <em>e</em>-1 times the argument.</p>
+<p>We can pass it the <a href="arithmetic.html#basic-arithmetic">exponential</a> function as an argument by giving it the name <code><span class='Function'>Exp</span></code> and then referring to it in lowercase (that is, in a subject role). The result is a <a href="train.html">train</a> that adds 1 to <em>e</em>-1 times the argument (we'll discuss only tacit functions here; for blocks see <a href="lexical.html">lexical scoping</a>).</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=TGluIOKGkCB7IHYw4oaQ8J2VjzAg4ouEIHYwKygo8J2VjzEpLXYwKcOX4oqiIH0gICMgKGNvcHkgb2YgYWJvdmUpCkV4cCDihpAg4ouGCkxpbiBleHA=">↗️</a><pre>    <span class='Function'>Lin</span> <span class='Gets'>←</span> <span class='Brace'>{</span> <span class='Value'>v0</span><span class='Gets'>←</span><span class='Function'>𝕏</span><span class='Number'>0</span> <span class='Separator'>⋄</span> <span class='Value'>v0</span><span class='Function'>+</span><span class='Paren'>((</span><span class='Function'>𝕏</span><span class='Number'>1</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Value'>v0</span><span class='Paren'>)</span><span class='Function'>×⊢</span> <span class='Brace'>}</span>  <span class='Comment'># (copy of above)
 </span>    <span class='Function'>Exp</span> <span class='Gets'>←</span> <span class='Function'>⋆</span>
     <span class='Function'>Lin</span> <span class='Value'>exp</span>
diff --git a/docs/doc/lexical.html b/docs/doc/lexical.html
index a4a7da44..d65f269b 100644
--- a/docs/doc/lexical.html
+++ b/docs/doc/lexical.html
@@ -77,4 +77,69 @@ ERROR
 </span>42
 </pre>
 <p>The function <code><span class='Function'>C3_7</span></code> uses the versions of <code><span class='Value'>counter</span></code> and <code><span class='Value'>inc</span></code> created in <code><span class='Modifier'>_makeCount</span></code>, even though it's called not from inside <code><span class='Modifier'>_makeCount</span></code>, but from the top-level program. This is what it means for BQN's scoping to be lexical rather than dynamic. Which identifiers are visible is determined by where the code containing them is located in the source code, not how it's called at runtime. The static nature of lexical scoping makes it much easier to keep track of how variables are used (for compilers, this means optimization opportunities), and for this reason dynamic scoping is very rare in programming languages today.</p>
+<h3 id="post-definition">Post-definition</h3>
+<p>In the top level a block, a variable can only be used after it's defined, and the compiler rejects any code that tries to use an undefined variable. But blocks contained in that block see variables it defines regardless of the positioning. Below, <code><span class='Function'>PlusC</span></code> references the variable <code><span class='Value'>c</span></code> that's defined after it (but when code is executed one line at a time like it is here, I still have to put both definitions on the same line so they are compiled together).</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=UGx1c0Mg4oaQIHsg8J2VqStjIH0g4ouEIGPihpDCrzEKUGx1c0MgNw==">↗️</a><pre>    <span class='Function'>PlusC</span> <span class='Gets'>←</span> <span class='Brace'>{</span> <span class='Value'>𝕩</span><span class='Function'>+</span><span class='Value'>c</span> <span class='Brace'>}</span> <span class='Separator'>⋄</span> <span class='Value'>c</span><span class='Gets'>←</span><span class='Number'>¯1</span>
+    <span class='Function'>PlusC</span> <span class='Number'>7</span>
+6
+</pre>
+<p>But you'll still get an error if the variable is used before its definition is run. Unlike the single-level case, this is a runtime error and only appears when the variable is actually accessed.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=eyAyK2QgfSDii4QgZOKGkMKvMg==">↗️</a><pre>    <span class='Brace'>{</span> <span class='Number'>2</span><span class='Function'>+</span><span class='Value'>d</span> <span class='Brace'>}</span> <span class='Separator'>⋄</span> <span class='Value'>d</span><span class='Gets'>←</span><span class='Number'>¯2</span>
+ERROR
+</pre>
+<p>Why define things this way? It's easier to see if you imagine the variable used is also a function. It's normal for a function to call other functions defined at the top level, of course. And it would be pretty unpleasant for BQN to enforce a specific ordering for them. It would also make recursive functions impossible except by using <code><span class='Function'>𝕊</span></code>, and mutually recursive ones completely impossible. A simple rule that makes all these things just work smoothly seems much better than any alternative.</p>
 <h2 id="closures">Closures</h2>
+<p>Let's run <code><span class='Modifier'>_makeCount</span></code> from above a few more times.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=QzRfMiDihpAgNOKAvzIgX21ha2VDb3VudCAgIyBTdGFydCBhdCA0OyBpbmNyZW1lbnQgYnkgMgpDMV80IOKGkCAx4oC/NCBfbWFrZUNvdW50ICAjICAgICAgICAgIDE7ICAgICAgICAgICAgICA0CgpDNF8yIDAKQzFfNCAwCkM0XzIgMTAKQzFfNCAxMApDNF8yIDAKQzNfNyAwICAjIFRoZSBmaXJzdCBvbmUncyBzdGlsbCBhcm91bmQgdG9v">↗️</a><pre>    <span class='Function'>C4_2</span> <span class='Gets'>←</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Modifier'>_makeCount</span>  <span class='Comment'># Start at 4; increment by 2
+</span>    <span class='Function'>C1_4</span> <span class='Gets'>←</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Modifier'>_makeCount</span>  <span class='Comment'>#          1;              4
+</span>
+    <span class='Function'>C4_2</span> <span class='Number'>0</span>
+4
+    <span class='Function'>C1_4</span> <span class='Number'>0</span>
+1
+    <span class='Function'>C4_2</span> <span class='Number'>10</span>
+24
+    <span class='Function'>C1_4</span> <span class='Number'>10</span>
+41
+    <span class='Function'>C4_2</span> <span class='Number'>0</span>
+24
+    <span class='Function'>C3_7</span> <span class='Number'>0</span>  <span class='Comment'># The first one's still around too
+</span>10
+</pre>
+<p>Each result keeps its own counter and the different copies don't interfere with each other. This is because every call to <code><span class='Modifier'>_makeCount</span></code> is isolated, happening in its own world. We say that whenever a block begins execution it creates an <em>environment</em> where all its variables are stored. This environment might even be exposed later on, as a <a href="namespace.html">namespace</a>.</p>
+<p>Each counter function has access to the environment containing its <code><span class='Value'>counter</span></code> and <code><span class='Value'>inc</span></code>, even though the block that created that environment (<code><span class='Modifier'>_makeCount</span></code>) has finished execution—it must have finished, since we are now using the function it returns on the last line. There's nothing particularly weird about this; just because a block creates an environment when it starts doesn't mean it has to destroy it when it finishes. From the mathematical perspective, it's easiest to say the environment exists forever, but a practical implementation will perform garbage collection to free environments that are no longer reachable.</p>
+<p>Since a function like <code><span class='Function'>C1_4</span></code> maintains access to all the variables it needs to run, we say it <em>encloses</em> those variables, and call it a <em>closure</em>. It doesn't need to modify them. For example, even the following definition of <code><span class='Value'>stdDev</span></code> is a closure.</p>
+<pre><span class='Value'>stdDev</span> <span class='Gets'>←</span> <span class='Brace'>{</span>
+  <span class='Comment'># Arithmetic mean
+</span>  <span class='Function'>Mean</span> <span class='Gets'>←</span> <span class='Function'>+</span><span class='Modifier'>´</span> <span class='Function'>÷</span> <span class='Function'>≠</span>
+
+  <span class='Comment'># Return this function
+</span>  <span class='Brace'>{</span>
+    <span class='Function'>Mean</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Function'>×</span><span class='Modifier'>˜</span><span class='Paren'>)</span> <span class='Value'>𝕩</span> <span class='Function'>-</span> <span class='Function'>Mean</span> <span class='Value'>𝕩</span>
+  <span class='Brace'>}</span>
+<span class='Brace'>}</span>
+</pre>
+<p>The variable <code><span class='Function'>Mean</span></code> is visible only within the outer immediate block. The only way it can be accessed is by code in this block: the two calls in the returned function, which will later be renamed <code><span class='Value'>stdDev</span></code>. Nothing in the block modifies it, so its value is constant. It's just a little utility that exists only for code in the block. Making it visible elsewhere is as simple as moving it out of the block, but it's best not to do this without reason. Keeping a variable in the smallest possible scope makes it easier to understand the program, because it reduces the amount of information needed to understand scopes where that variable doesn't apply.</p>
+<p>Neither the specification nor a typical implementation keep track of what is and isn't a closure, although an advanced interpreter will probably work with some related properties. The existence of closures is an ordinary feature of lexical scoping and not a special case. However, it's sometimes a useful term for discussing the operation of a program. We might define a closure as a block that can be run and access variables from a parent scope even after the block that created that scope finishes execution.</p>
+<h3 id="environments-form-a-tree">Environments form a tree</h3>
+<p>So a block has access to every environment that it might need a variable from, for as long as it needs. This idea is a little fuzzy, so let's clarify by describing how an implementation would support figure out what can access where.</p>
+<p>The mechanism is that each environment can have a <em>parent</em> environment (the topmost environment, which corresponds to the entire program, has no parent). When a variable is accessed, it might be in the current environment, or its parent, or that environment's parent, and so on. Every environment corresponds to one block in the source code, and its parent corresponds to the parent block, so a compiler can figure out how many levels up it will have to go based on the source code.</p>
+<p>We've seen that one block can create many environments. An environment can have only one parent, but many children, so environments form a tree. A forest to be precise, as one execution of BQN can involve multiple programs.</p>
+<p>How does an environment know which of the many environments corresponding to the parent scope is its parent? This information is saved when the block is reached in the program and a <em>block instance</em> is created. Unless it's an immediate block, the block instance won't be run right away: a block instance isn't the same as a block evaluation. But each block evaluation starts with a block instance, and that's where it gets the parent environment. Unlike block evaluation, which can happen anywhere, a block instance is created only during evaluation of the parent block. So the saved parent environment is simply the current environment.</p>
+<h2 id="mutation">Mutation</h2>
+<p>The value of a variable can be modified with <code><span class='Gets'>↩</span></code>. It's similar to definition <code><span class='Gets'>←</span></code> in that it sets the value of the variable, but the way it interacts with scoping is completely different. Defining creates a new variable in the current scope, and modifying refers to an existing variable in the current scope or a parent. In scoping terms, modifying is more like an ordinary variable reference than a definition.</p>
+<p>When a variable's modified, functions with access to it see the new value. They have access to the variable, not any particular value that it has.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ZmFjdG9yIOKGkCAzCk11bCDihpAgeyBmYWN0b3Igw5cg8J2VqSB9CgpNdWwgNgpmYWN0b3Ig4oapIDUKTXVsIDYgICAjIEEgbmV3IHJlc3VsdA==">↗️</a><pre>    <span class='Value'>factor</span> <span class='Gets'>←</span> <span class='Number'>3</span>
+    <span class='Function'>Mul</span> <span class='Gets'>←</span> <span class='Brace'>{</span> <span class='Value'>factor</span> <span class='Function'>×</span> <span class='Value'>𝕩</span> <span class='Brace'>}</span>
+
+    <span class='Function'>Mul</span> <span class='Number'>6</span>
+18
+    <span class='Value'>factor</span> <span class='Gets'>↩</span> <span class='Number'>5</span>
+    <span class='Function'>Mul</span> <span class='Number'>6</span>   <span class='Comment'># A new result
+</span>30
+</pre>
+<p>Only code with access to a variable can modify it! This means that if none of the code in a variable's scope modifies it, then the variable is a constant in each environment that contains it (not necessarily across environments). That is, constant once it's defined: it's still possible to get an error if the variable is accessed before being defined.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=eyB7IGEgfSDii4QgYeKGkDQgfQ==">↗️</a><pre>    <span class='Brace'>{</span> <span class='Brace'>{</span> <span class='Value'>a</span> <span class='Brace'>}</span> <span class='Separator'>⋄</span> <span class='Value'>a</span><span class='Gets'>←</span><span class='Number'>4</span> <span class='Brace'>}</span>
+ERROR
+</pre>
+<p>With lexical scoping, variable mutation automatically leads to mutable data. This is because a function or modifier that depends on the variable value changes its behavior when the variable changes. For further discussion see the documentation on <a href="oop.html#mutability">mutable objects</a>.</p>
diff --git a/docs/doc/namespace.html b/docs/doc/namespace.html
index b8332eae..9ea2f214 100644
--- a/docs/doc/namespace.html
+++ b/docs/doc/namespace.html
@@ -18,7 +18,7 @@
 </span><span class='Function'>DoThing</span> <span class='Gets'>←</span> <span class='String'>&quot;TODO&quot;</span><span class='Modifier2'>⊸</span><span class='Function'>!</span>
 </pre>
 <h2 id="uses">Uses</h2>
-<p>The features of namespaces that make them useful in BQN programming are encapsulation and mutability. But these are exactly the same features that <a href="https://en.wikipedia.org/wiki/Closure_(computer_programming)">closures</a> provide! In fact a namespace is not much more than a closure with a name lookup system. Consequently namespaces don't really expand the basic functionality of the language, but just make it easier to use.</p>
+<p>The features of namespaces that make them useful in BQN programming are encapsulation and mutability. But these are exactly the same features that <a href="lexical.html#closures">closures</a> provide! In fact a namespace is not much more than a closure with a name lookup system. Consequently namespaces don't really expand the basic functionality of the language, but just make it easier to use.</p>
 <p>Namespaces improve encapsulation by allowing many values to be exported at once. With only one way to call them, functions and modifiers aren't such a good way to define a large part of a program. With a namespace you can define lots of things and expose exactly the ones you want to the rest of the world. For example, it's typical for files to define namespaces. A reader can see the exported values just by searching for <code><span class='Gets'>⇐</span></code>, and if you're nice, you might declare them all at the beginning of the file. Careful use of exports can guarantee that potentially dangerous functions are used correctly: if it's only valid to call function <code><span class='Function'>B</span></code> after function <code><span class='Function'>A</span></code> has been called, export <code><span class='Function'>AB</span><span class='Gets'>⇐</span><span class='Brace'>{</span><span class='Function'>A</span><span class='Value'>𝕩</span><span class='Separator'>⋄</span><span class='Function'>B</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code> and don't export <code><span class='Function'>B</span></code>.</p>
 <p>Mutability means that the behavior of one namespace can change over the course of the program. Mutability is often a liability, so make sure you really need it before leaning too heavily on this property. While there's no way to tell from the outside that a particular namespace is mutable, you can tell it isn't if the source code doesn't contain <code><span class='Gets'>↩</span></code>, as this is the only way it can modify the variables it contains.</p>
 <p>A namespace that makes use of mutability is essentially an object: a collection of state along with operations that act on it. <a href="oop.html">Object-oriented programming</a> is the other major use of namespaces. Contrary to the name, there's never a need to orient your programming around objects, and it's perfectly fine to use an object here or there when you need to, for instance to build a mutable queue of values.</p>
diff --git a/docs/doc/oop.html b/docs/doc/oop.html
index 6a0c339d..59a6c851 100644
--- a/docs/doc/oop.html
+++ b/docs/doc/oop.html
@@ -152,7 +152,7 @@
 </pre>
 <p>This is a pretty clunky solution, and exports a useless method <code><span class='Function'>SetThis</span></code> (which gives an error if it's ever called). It would be possible for BQN to define a system value <code><span class='Value'>•this</span></code> that just gets the namespace's value. It would work only at the top level, so it would have to be assigned (<code><span class='Value'>this</span><span class='Gets'>←</span><span class='Value'>•this</span></code>) in order to use it in functions. This means it's always used before the namespace is done being defined, so a drawback is that it introduces the possibility that an object used in a program has undefined fields. The reason this isn't possible for objects without <code><span class='Value'>•this</span></code> is that BQN's blocks don't have any sort of control flow, so that they always execute every statement in order. The namespace becomes accessible as a value once the block finishes, and at this point every statement has been executed and every field is initialized.</p>
 <h2 id="class-members">Class members</h2>
-<p>As with <code><span class='Value'>this</span></code>, giving a class variables that belong to it is a do-it-yourself sort of thing (or more positively, not at all magic (funny how programmer jargon goes the opposite way to ordinary English)). It's an easy one though, as this is exactly what lexical scoping does:</p>
+<p>As with <code><span class='Value'>this</span></code>, giving a class variables that belong to it is a do-it-yourself sort of thing (or more positively, not at all magic (funny how programmer jargon goes the opposite way to ordinary English)). It's an easy one though, as this is exactly what <a href="lexical.html">lexical scoping</a> does:</p>
 <pre><span class='Value'>staticClass</span> <span class='Gets'>←</span> <span class='Brace'>{</span>
   <span class='Value'>counter</span> <span class='Gets'>←</span> <span class='Number'>0</span>
   <span class='Brace'>{</span><span class='Value'>𝕤</span>
diff --git a/docs/doc/paradigms.html b/docs/doc/paradigms.html
index 750e2302..9e2538f2 100644
--- a/docs/doc/paradigms.html
+++ b/docs/doc/paradigms.html
@@ -14,7 +14,7 @@
 <p>Dynamic types and garbage collection introduce overhead relative to a statically-typed or manually managed language. The impact of this overhead can be greatly reduced with array programming, because an array of numbers or characters can be stored as a single unit of memory and processed with functions specialized to its element type.</p>
 <h2 id="styles">Styles</h2>
 <p>BQN is designed for <strong>array</strong> programming. The array is its only built-in collection type and it has many primitives designed to work with arrays.</p>
-<p>BQN is okay for <strong>imperative</strong> programming. Blocks are lists of statements. Variables can be modified with <code><span class='Gets'>↩</span></code>, and while there are no truly global variables, lexical scoping allows variables at the top level of a file, which are similar (<code><span class='Function'>•Import</span></code> with no left argument saves and reuses results, so that data can be shared between files by loading the same namespace-defining file in each). BQN doesn't directly support <strong>structured</strong> programming (which refers to a particular way to structure programs; it also doesn't have a Goto statement, the &quot;unstructured&quot; alternative when the term was coined). However, its first-class functions allow a reasonably similar <a href="control.html">imitation</a> of control structures.</p>
+<p>BQN is okay for <strong>imperative</strong> programming. Blocks are lists of statements. Variables can be modified with <code><span class='Gets'>↩</span></code>, and while there are no truly global variables, <a href="lexical.html">lexical scoping</a> allows variables at the top level of a file, which are similar (<code><span class='Function'>•Import</span></code> with no left argument saves and reuses results, so that data can be shared between files by loading the same namespace-defining file in each). BQN doesn't directly support <strong>structured</strong> programming (which refers to a particular way to structure programs; it also doesn't have a Goto statement, the &quot;unstructured&quot; alternative when the term was coined). However, its first-class functions allow a reasonably similar <a href="control.html">imitation</a> of control structures.</p>
 <p><strong>Functional</strong> programming is a term with many meanings. Using the terms defined in the <a href="functional.html">functional programming document</a>, BQN supports first-class functions and function-level programming, allows but doesn't encourage pure functional programming, and does not support typed functional programming. BQN uses <strong>lexical scope</strong> and has full support for <strong>closures</strong>. In this way BQN is very similar to Lisp, although it lacks Lisp's macro system.</p>
 <p>BQN has excellent <a href="tacit.html">support</a> for <strong>tacit</strong> or <strong>point-free</strong> programming, with <a href="train.html">trains</a> and intuitive symbols for combinators making it much easier to work with (in my opinion) than other languages that support this style. It's near-universally considered a poor choice to implement entire programs in a tacit style, so this paradigm is best used as a small-scale tool within a style like functional or object-oriented programming.</p>
 <p>BQN uses <a href="namespace.html">namespaces</a> as <strong>modules</strong> to organize code; the only possible interaction with a module is by its exported variables. There doesn't seem to be a name for this paradigm, but there should be.</p>
diff --git a/docs/doc/syntax.html b/docs/doc/syntax.html
index 74d7d37b..c22de4f6 100644
--- a/docs/doc/syntax.html
+++ b/docs/doc/syntax.html
@@ -166,6 +166,6 @@
 <p>Lists (1-dimensional arrays) are enclosed in angle brackets <code><span class='Bracket'>⟨⟩</span></code>, with the results of the expressions in between being the list's elements. Lists of two elements or more can also be written with the ligature character <code><span class='Ligature'>‿</span></code>. This character has higher binding strength than any part of an expression. If one of the elements is a compound expression, then it will need to be enclosed in parentheses.</p>
 <h3 id="blocks">Blocks</h3>
 <p><em><a href="block.html">Full documentation</a></em></p>
-<p>Blocks are written with curly braces <code><span class='Brace'>{}</span></code> and can be used to group expressions or define functions and modifiers. The contents are simply a sequence of expressions, where each is evaluated and the result of the last is returned in order to evaluate the block. This result can have any value, and its syntactic role in the calling context is determined by the normal rules: functions return subjects and modifiers return functions. Blocks have lexical scope.</p>
+<p>Blocks are written with curly braces <code><span class='Brace'>{}</span></code> and can be used to group expressions or define functions and modifiers. The contents are simply a sequence of expressions, where each is evaluated and the result of the last is returned in order to evaluate the block. This result can have any value, and its syntactic role in the calling context is determined by the normal rules: functions return subjects and modifiers return functions. Blocks have <a href="lexical.html">lexical scope</a>.</p>
 <p>The special names <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code>, which stand for arguments, and <code><span class='Value'>𝕗</span></code> and <code><span class='Value'>𝕘</span></code>, which stand for operands, are available inside curly braces. Like ordinary names, the lowercase forms indicate subjects and the uppercase forms <code><span class='Function'>𝕎𝕏𝔽𝔾</span></code> indicate functions. The type and syntactic role of the block is determined by its contents: a 2-modifier contains <code><span class='Value'>𝕘</span></code>, a 1-modifier contains <code><span class='Value'>𝕗</span></code> but not <code><span class='Value'>𝕘</span></code>, and a function contains neither but does have one of <code><span class='Value'>𝕨𝕩𝕤</span><span class='Function'>𝕎𝕏𝕊</span></code>. If no special names are present the block is an <em>immediate block</em> and is evaluated as soon as it appears, with the result having a subject role.</p>
 <p>A modifier can be evaluated twice: once when passed operands and again when the resulting function is passed arguments. If it contains <code><span class='Value'>𝕨</span></code> or <code><span class='Value'>𝕩</span></code>, the first evaluation simply remembers the operands, and the contents will be executed only on the second evaluation, when the arguments are available. If it doesn't contain these, then the contents are executed on the first evaluation and the result is treated as a function.</p>