From 520b429ca01b2ecf2d221a984e8dd9ac242c0de3 Mon Sep 17 00:00:00 2001
From: Nicolas Williams <nico@cryptonector.com>
Date: Tue, 9 Jun 2015 17:29:37 -0500
Subject: [PATCH] Clarify array destructuring docs

---
 docs/content/3.manual/manual.yml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index 4e3d330c..8a4f77a1 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -2148,10 +2148,17 @@ sections:
           foreach loop.
 
           Multiple variables may be declared using a single `as` expression by
-          providing a pattern that matches the structure of the input:
+          providing a pattern that matches the structure of the input
+          (this is known as "destructuring"):
 
               . as {realnames: $names, posts: [$first, $second]} | ...
 
+          The variable declarations in array patterns (e.g., `. as
+          [$first, $second]`) bind to the elements of the array in from
+          the element at index zero on up, in order.  When there is no
+          value at the index for an array pattern element, `null` is
+          bound to that variable.
+
           Variables are scoped over the rest of the expression that defines
           them, so
 
@@ -2179,6 +2186,9 @@ sections:
           - program: '. as [$a, $b, {c: $c}] | $a + $b + $c'
             input: '[2, 3, {c: 4, d: 5}]'
             output: ['9']
+          - program: '.[] as [$a, $b] | {a: $a, b: $b}'
+            input: '[[0], [0, 1], [2, 1, 0]]'
+            output: ['[{"a":0,"b":null},{"a":0,"b":1},{"a":2,"b":1}]']
 
       - title: 'Defining Functions'
         body: |