From 1c7fb1463124969b3073b1c8f9c1977c8eff08ca Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sun, 10 Jan 2021 11:27:18 +1100
Subject: [PATCH] Better recursive decent docs

---
 ...sive Descent.md => Recursive Descent (Glob).md} | 14 ++++++++------
 ...sive Descent.md => Recursive Descent (Glob).md} |  0
 pkg/yqlib/operator_recursive_descent_test.go       |  8 ++++----
 3 files changed, 12 insertions(+), 10 deletions(-)
 rename pkg/yqlib/doc/{Recursive Descent.md => Recursive Descent (Glob).md} (89%)
 rename pkg/yqlib/doc/headers/{Recursive Descent.md => Recursive Descent (Glob).md} (100%)

diff --git a/pkg/yqlib/doc/Recursive Descent.md b/pkg/yqlib/doc/Recursive Descent (Glob).md
similarity index 89%
rename from pkg/yqlib/doc/Recursive Descent.md
rename to pkg/yqlib/doc/Recursive Descent (Glob).md
index ee0a61f..b95393d 100644
--- a/pkg/yqlib/doc/Recursive Descent.md	
+++ b/pkg/yqlib/doc/Recursive Descent (Glob).md	
@@ -33,6 +33,8 @@ frog
 ```
 
 ## Recursively find nodes with keys
+Note that this example has wrapped the expression in `[]` to show that there are two matches returned. You do not have to wrap in `[]` in your path expression.
+
 Given a sample.yml file of:
 ```yaml
 a:
@@ -43,16 +45,16 @@ a:
 ```
 then
 ```bash
-yq eval '.. | select(has("name"))' sample.yml
+yq eval '[.. | select(has("name"))]' sample.yml
 ```
 will output
 ```yaml
-name: frog
-b:
-  name: blog
+- name: frog
+  b:
+    name: blog
+    age: 12
+- name: blog
   age: 12
-name: blog
-age: 12
 ```
 
 ## Recursively find nodes with values
diff --git a/pkg/yqlib/doc/headers/Recursive Descent.md b/pkg/yqlib/doc/headers/Recursive Descent (Glob).md
similarity index 100%
rename from pkg/yqlib/doc/headers/Recursive Descent.md
rename to pkg/yqlib/doc/headers/Recursive Descent (Glob).md
diff --git a/pkg/yqlib/operator_recursive_descent_test.go b/pkg/yqlib/operator_recursive_descent_test.go
index 0d25d16..5f63d32 100644
--- a/pkg/yqlib/operator_recursive_descent_test.go
+++ b/pkg/yqlib/operator_recursive_descent_test.go
@@ -64,11 +64,11 @@ var recursiveDescentOperatorScenarios = []expressionScenario{
 	},
 	{
 		description: "Recursively find nodes with keys",
+		subdescription: "Note that this example has wrapped the expression in `[]` to show that there are two matches returned. You do not have to wrap in `[]` in your path expression.",
 		document:    `{a: {name: frog, b: {name: blog, age: 12}}}`,
-		expression:  `.. | select(has("name"))`,
+		expression:  `[.. | select(has("name"))]`,
 		expected: []string{
-			"D0, P[a], (!!map)::{name: frog, b: {name: blog, age: 12}}\n",
-			"D0, P[a b], (!!map)::{name: blog, age: 12}\n",
+			"D0, P[a], (!!seq)::- {name: frog, b: {name: blog, age: 12}}\n- {name: blog, age: 12}\n",
 		},
 	},
 	{
@@ -233,5 +233,5 @@ func TestRecursiveDescentOperatorScenarios(t *testing.T) {
 	for _, tt := range recursiveDescentOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "Recursive Descent", recursiveDescentOperatorScenarios)
+	documentScenarios(t, "Recursive Descent (Glob)", recursiveDescentOperatorScenarios)
 }