fix #95 destructuring assignment and splats

docs/List.md

@@ -92,6 +92,34 @@ Open end ranges remove head and tail elements:
     assert( [1, 2, 3] !== [1, 2, 3])
     >>> void
 
+## Destructuring
+
+Lists can be used as L-values for destructuring assignments. This allows you to unpack list elements into multiple variables.
+
+### Basic Destructuring
+```lyng
+val [a, b, c] = [1, 2, 3]
+```
+
+### With Splats (Variadic)
+A single ellipsis `...` can be used to capture remaining elements into a list. It can be placed at the beginning, middle, or end of the pattern.
+```lyng
+val [head, rest...] = [1, 2, 3] // head=1, rest=[2, 3]
+val [first, middle..., last] = [1, 2, 3, 4, 5] // first=1, middle=[2, 3, 4], last=5
+```
+
+### Nested Patterns
+Destructuring patterns can be nested to unpack multi-dimensional lists.
+```lyng
+val [a, [b, c...], d] = [1, [2, 3, 4], 5]
+```
+
+### Reassignment
+Destructuring can also be used to reassign existing variables:
+```lyng
+[x, y] = [y, x] // Swap values
+```
+
 ## In-place sort
 
 List could be sorted in place, just like [Collection] provide sorted copies, in a very like way:

docs/declaring_arguments.md

@@ -75,6 +75,13 @@ destructuring arrays when calling functions and lambdas:
     getFirstAndLast( ...(1..10) ) // see "splats" section below
     >>> [1,10]
 
+Note that array destructuring can also be used in assignments:
+
+    val [first, middle..., last] = [1, 2, 3, 4, 5]
+    [x, y] = [y, x] // Swap
+
+See [tutorial] and [List] documentation for more details on destructuring assignments.
+
 # Splats
 
 Ellipsis allows to convert argument lists to lists. The inversa algorithm that converts [List],
@@ -155,3 +162,4 @@ If a call is immediately followed by a block `{ ... }`, it is treated as an extr
     
 
 [tutorial]: tutorial.md
+[List]: List.md

docs/tutorial.md

@@ -107,6 +107,41 @@ Assignemnt is an expression that changes its lvalue and return assigned value:
     >>> 11
     >>> 6
 
+### Destructuring assignments
+
+Lyng supports destructuring assignments for lists. This allows you to unpack list elements into multiple variables at once:
+
+    val [a, b, c] = [1, 2, 3]
+    assertEquals(1, a)
+    assertEquals(2, b)
+    assertEquals(3, c)
+
+It also supports *splats* (ellipsis) to capture multiple elements into a list:
+
+    val [head, rest...] = [1, 2, 3]
+    assertEquals(1, head)
+    assertEquals([2, 3], rest)
+
+    val [first, middle..., last] = [1, 2, 3, 4, 5]
+    assertEquals(1, first)
+    assertEquals([2, 3, 4], middle)
+    assertEquals(5, last)
+
+Destructuring can be nested:
+
+    val [x, [y, z...]] = [1, [2, 3, 4]]
+    assertEquals(1, x)
+    assertEquals(2, y)
+    assertEquals([3, 4], z)
+
+And it can be used for reassigning existing variables, for example, to swap values:
+
+    var x = 5
+    var y = 10
+    [x, y] = [y, x]
+    assertEquals(10, x)
+    assertEquals(5, y)
+
 As the assignment itself is an expression, you can use it in strange ways. Just remember
 to use parentheses as assignment operation insofar is left-associated and will not
 allow chained assignments (we might fix it later). Use parentheses insofar: