From 9c2599cb11346602f84d32a2e327580547f19fa1 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sun, 30 Jan 2022 18:02:45 -0500 Subject: Document destructuring assignment --- docs/doc/block.html | 6 +++--- docs/doc/expression.html | 21 ++++++++++++++++++++- docs/doc/namespace.html | 4 ++-- docs/help/nothing.html | 1 + 4 files changed, 26 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/doc/block.html b/docs/doc/block.html index 40de8ab2..a31d33f3 100644 --- a/docs/doc/block.html +++ b/docs/doc/block.html @@ -166,9 +166,9 @@

Unlike these assignments, the header also constrains what inputs the block can take: a monadic 1-modifier like the one above can't take a right operand or left argument, and consequently its body can't contain 𝔾 or 𝕨. Calling it with a left argument, or a right argument that isn't a two-element list, will result in an error.

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.

-↗️
    Destruct ← { 𝕊 a‿1‿⟨b,2⟩: a≍b }
-    Destruct       5‿1‿⟨7,2⟩
+
Arguments and 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.

+↗️
    Destruct ← { 𝕊 a‿1‿⟨b,·,2⟩: a≍b }
+    Destruct       5‿1‿⟨7,π,2⟩
 ⟨ 5 7 ⟩
 

 
Special names in headers

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 @@
 
 
 
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, 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.

 ↗️
    x←1 ⋄ {x←2 ⋄ x↩3 ⋄ x}
 3
@@ -205,6 +205,25 @@
 
 
 
+
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⟩
+⟨ "qr" ⟨ 0 1 2 3 ⟩ ⟩
+
+    r
+'r'
+
+    s
+⟨ 0 1 2 3 ⟩
+

+
Namespace destructuring uses an overlapping syntax, fully described in its own section. The left hand side is a list of names or aliases to⇐from.

+↗️
    q‿r ↩ {q⇐2+r⇐0.5} ⋄ q
+2.5
+

+
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
+6
+

 
Exports

 
The double arrow ⇐ is used to export variables from a block or program, causing the result to be a namespace. 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.

 
⟨alias⇐a, b, c0‿c1⇐c, b2⇐b⟩←{
diff --git a/docs/doc/namespace.html b/docs/doc/namespace.html
index a0c06d75..ece4d6b6 100644
--- a/docs/doc/namespace.html
+++ b/docs/doc/namespace.html
@@ -32,10 +32,10 @@
 }
 

 
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 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
 

 
The arrows ⇐ used for importing don't indicate that the surrounding block is a namespace or export variables. However, a single statement can both import and export, if it's a destructuring assignment and the main assignment arrow is ⇐.

diff --git a/docs/help/nothing.html b/docs/help/nothing.html
index f4361a83..199406fd 100644
--- a/docs/help/nothing.html
+++ b/docs/help/nothing.html
@@ -20,6 +20,7 @@
 5
 

 
Destructuring

+
→full documentation

 
For pattern matching in assignment or a block header, Nothing indicates an unused value.

 ↗️
    F ← {𝕊 a‿·‿b: a∾b}
 
-- 
cgit v1.2.3