Document destructuring assignment

3 files changed, 24 insertions, 6 deletions

diff --git a/doc/block.md b/doc/block.md
index 27018939..b6b83cc9 100644
--- a/doc/block.md
+++ b/doc/block.md
@@ -134,10 +134,10 @@ Unlike these assignments, the header also constrains what inputs the block can t
 
 ### Destructuring
 
-Arguments, but not operands, allow destructuring like assignment does. While assignment only tolerates lists of variables, header destructuring also allows constants. The argument must match the given structure, including the constants where they appear, or an error results.
+Arguments and operands allow [destructuring](expression.md#destructuring) like assignment does. While assignment only tolerates lists of variables, header destructuring also allows constants. The argument must match the given structure, including the constants where they appear, or an error results.
 
-        Destruct ← { 𝕊 a‿1‿⟨b,2⟩: a≍b }
-        Destruct       5‿1‿⟨7,2⟩
+        Destruct ← { 𝕊 a‿1‿⟨b,·,2⟩: a≍b }
+        Destruct       5‿1‿⟨7,π,2⟩
 
 ### Special names in headers
 
diff --git a/doc/expression.md b/doc/expression.md
index 159f8d52..95355ced 100644
--- a/doc/expression.md
+++ b/doc/expression.md
@@ -81,7 +81,7 @@ Here is a table of the modifier and function application rules:
 
 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.
 
-### Assignment
+## Assignment
 
 Another element that can be included in expressions is assignment, which is written with `←` to *define* (also called "declare" in many other languages) a variable and `↩` to *change* its definition. A variable can only be defined once within a [scope](lexical.md), 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.
 
@@ -100,6 +100,24 @@ The modification arrow `↩` can also be used to *update* the value of a variabl
 | `a F↩`   | `a ↩ F a`
 | `a F↩ b` | `a ↩ a F b`
 
+### Destructuring
+
+The left hand side of assignment in a subject expression can be *compound*, so that assigned values are extracted from lists or namespaces. This is called a *destructuring* 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.
+
+        ⟨q‿r,s⟩ ← ⟨"qr",↕4⟩
+
+        r
+
+        s
+
+Namespace destructuring uses an overlapping syntax, fully described in [its own section](namespace.md#imports). The left hand side is a list of names or aliases `to⇐from`.
+
+        q‿r ↩ {q⇐2+r⇐0.5} ⋄ q
+
+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 (`·`) for a placeholder non-name in the appropriate position, like `·‿y‿· ← list`.
+
+        · ← 6   # Doesn't do anything
+
 ### Exports
 
 The double arrow `⇐` is used to export variables from a block or program, causing the result to be a [namespace](namespace.md). There are two ways to export variables. First, `←` in the variable definition can be replaced with `⇐` to export the variable as it's defined. Second, an export statement consisting of an assignment target followed by `⇐` 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.
diff --git a/doc/namespace.md b/doc/namespace.md
index 80aff787..5b7f67e5 100644
--- a/doc/namespace.md
+++ b/doc/namespace.md
@@ -40,11 +40,11 @@ The double arrow `⇐` is used to export variables from a block or file, making
 
 ## Imports
 
-There are also two ways to get values out of a namespace, such as `example` defined above. First, it might be used in a destructuring assignment like the one below. This assignment's target looks like a list, where each entry specifies one of the names exported by the block and what it should be assigned to. The element can be either a single name, like `b`, which gives both, or an aliasing expression like `b2⇐b`. In this case, the value `b` from the namespace is used, but it's given the name `b2` instead of `b`. Imported names can be repeated—but the variables defined can't—and all the names can be spelled with any role (the role is ignored).
+There are also two ways to get values out of a namespace, such as `example` defined above. First, it might be used in a [destructuring](expression.md#destructuring) assignment like the one below. This assignment's target looks like a list, where each entry specifies one of the names exported by the block and what it should be assigned to. The element can be either a single name, like `b`, which gives both, or an aliasing expression like `b2⇐b`. In this case, the value `b` from the namespace is used, but it's given the name `b2` instead of `b`. Imported names can be repeated—but the variables defined can't—and all the names can be spelled with any role (the role is ignored).
 
     ⟨alias⇐a, b, c0‿c1⇐c, b2⇐b⟩ ← example
 
-If aliasing with `⇐` is never used, the names can be given as a strand with `‿`.
+If aliasing with `⇐` is never used (or each use is parenthesized), the names can be given as a strand with `‿`.
 
     c‿a ← example