1 files changed, 20 insertions, 1 deletions
diff --git a/docs/doc/expression.html b/docs/doc/expression.html
index 6b7f588c..c1b4d539 100644
--- a/docs/doc/expression.html
+++ b/docs/doc/expression.html
@@ -173,7 +173,7 @@
 </tbody>
 </table>
 <p>A function with an asterisk indicates that a subject can also be used. Since the role doesn't exist after parsing, function and subject spellings are indistinguishable in these positions. Modifier applications bind more tightly than functions, and associate left-to-right while functions associate right-to-left.</p>
-<h3 id="assignment"><a class="header" href="#assignment">Assignment</a></h3>
+<h2 id="assignment"><a class="header" href="#assignment">Assignment</a></h2>
 <p>Another element that can be included in expressions is assignment, which is written with <code><span class='Gets'>←</span></code> to <em>define</em> (also called &quot;declare&quot; in many other languages) a variable and <code><span class='Gets'>↩</span></code> to <em>change</em> its definition. A variable can only be defined once within a <a href="lexical.html">scope</a>, and can only be changed if it has already been defined. However, it can be shadowed, meaning that it is defined again in an inner scope even though it has a definition in an outer scope already.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=eOKGkDEg4ouEIHt44oaQMiDii4QgeOKGqTMg4ouEIHh9Cng=">↗️</a><pre>    <span class='Value'>x</span><span class='Gets'>←</span><span class='Number'>1</span> <span class='Separator'>⋄</span> <span class='Brace'>{</span><span class='Value'>x</span><span class='Gets'>←</span><span class='Number'>2</span> <span class='Separator'>⋄</span> <span class='Value'>x</span><span class='Gets'>↩</span><span class='Number'>3</span> <span class='Separator'>⋄</span> <span class='Value'>x</span><span class='Brace'>}</span>
 3
@@ -205,6 +205,25 @@
 </tr>
 </tbody>
 </table>
+<h3 id="destructuring"><a class="header" href="#destructuring">Destructuring</a></h3>
+<p>The left hand side of assignment in a subject expression can be <em>compound</em>, so that assigned values are extracted from lists or namespaces. This is called a <em>destructuring</em> assignment. The most common case is list destructuring: the left hand side's written as a list, and the value on the right has to be a list of the same length. Assignments are made element-wise, and the elements can destructure things further.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oceKAv3Isc+KfqSDihpAg4p+oInFyIizihpU04p+pCgpyCgpz">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Value'>q</span><span class='Ligature'>‿</span><span class='Value'>r</span><span class='Separator'>,</span><span class='Value'>s</span><span class='Bracket'>⟩</span> <span class='Gets'>←</span> <span class='Bracket'>⟨</span><span class='String'>&quot;qr&quot;</span><span class='Separator'>,</span><span class='Function'>↕</span><span class='Number'>4</span><span class='Bracket'>⟩</span>
+⟨ "qr" ⟨ 0 1 2 3 ⟩ ⟩
+
+    <span class='Value'>r</span>
+'r'
+
+    <span class='Value'>s</span>
+⟨ 0 1 2 3 ⟩
+</pre>
+<p>Namespace destructuring uses an overlapping syntax, fully described in <a href="namespace.html#imports">its own section</a>. The left hand side is a list of names or aliases <code><span class='Value'>to</span><span class='Gets'>⇐</span><span class='Value'>from</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ceKAv3Ig4oapIHtx4oeQMity4oeQMC41fSDii4QgcQ==">↗️</a><pre>    <span class='Value'>q</span><span class='Ligature'>‿</span><span class='Value'>r</span> <span class='Gets'>↩</span> <span class='Brace'>{</span><span class='Value'>q</span><span class='Gets'>⇐</span><span class='Number'>2</span><span class='Function'>+</span><span class='Value'>r</span><span class='Gets'>⇐</span><span class='Number'>0.5</span><span class='Brace'>}</span> <span class='Separator'>⋄</span> <span class='Value'>q</span>
+2.5
+</pre>
+<p>With destructuring, you might want to discard some values from the right hand side rather than assign them any name. There's special syntax for this: use Nothing (<code><span class='Nothing'>·</span></code>) for a placeholder non-name in the appropriate position, like <code><span class='Nothing'>·</span><span class='Ligature'>‿</span><span class='Value'>y</span><span class='Ligature'>‿</span><span class='Nothing'>·</span> <span class='Gets'>←</span> <span class='Value'>list</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=wrcg4oaQIDYgICAjIERvZXNuJ3QgZG8gYW55dGhpbmc=">↗️</a><pre>    <span class='Nothing'>·</span> <span class='Gets'>←</span> <span class='Number'>6</span>   <span class='Comment'># Doesn't do anything
+</span>6
+</pre>
 <h3 id="exports"><a class="header" href="#exports">Exports</a></h3>
 <p>The double arrow <code><span class='Gets'>⇐</span></code> is used to export variables from a block or program, causing the result to be a <a href="namespace.html">namespace</a>. There are two ways to export variables. First, <code><span class='Gets'>←</span></code> in the variable definition can be replaced with <code><span class='Gets'>⇐</span></code> to export the variable as it's defined. Second, an export statement consisting of an assignment target followed by <code><span class='Gets'>⇐</span></code> with nothing to the right exports the variables in the assignment target and does nothing else. Export statements can be placed anywhere in the relevant program or body, including before declaration or on the last line, and a given variable can be exported any number of times.</p>
 <pre><span class='Bracket'>⟨</span><span class='Value'>alias</span><span class='Gets'>⇐</span><span class='Value'>a</span><span class='Separator'>,</span> <span class='Value'>b</span><span class='Separator'>,</span> <span class='Value'>c0</span><span class='Ligature'>‿</span><span class='Value'>c1</span><span class='Gets'>⇐</span><span class='Value'>c</span><span class='Separator'>,</span> <span class='Value'>b2</span><span class='Gets'>⇐</span><span class='Value'>b</span><span class='Bracket'>⟩</span><span class='Gets'>←</span><span class='Brace'>{</span>