From e93c43f7a044cc4f2119efaa6e47994f64fe6251 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 26 Feb 2021 11:31:43 +1100
Subject: [PATCH] Improving docs

---
 .../doc/{Assign.md => Assign (Update).md}     |  6 -----
 pkg/yqlib/doc/Comment Operators.md            | 11 +++++++++
 pkg/yqlib/doc/Has.md                          | 23 +++++++++++++++++++
 .../headers/{Assign.md => Assign (Assign).md} |  0
 pkg/yqlib/doc/headers/Comment Operators.md    | 12 +++++++++-
 pkg/yqlib/operator_assign_test.go             |  2 +-
 pkg/yqlib/operator_has_test.go                |  9 ++++++++
 7 files changed, 55 insertions(+), 8 deletions(-)
 rename pkg/yqlib/doc/{Assign.md => Assign (Update).md} (84%)
 rename pkg/yqlib/doc/headers/{Assign.md => Assign (Assign).md} (100%)

diff --git a/pkg/yqlib/doc/Assign.md b/pkg/yqlib/doc/Assign (Update).md
similarity index 84%
rename from pkg/yqlib/doc/Assign.md
rename to pkg/yqlib/doc/Assign (Update).md
index a0b7ce5f..28983bcf 100644
--- a/pkg/yqlib/doc/Assign.md
+++ b/pkg/yqlib/doc/Assign (Update).md	
@@ -1,10 +1,4 @@
-This operator is used to update node values. It can be used in either the:
 
-### plain form: `=`
-Which will assign the LHS node values to the RHS node values. The RHS expression is run against the matching nodes in the pipeline.
-
-### relative form: `|=`
-This will do a similar thing to the plain form, however, the RHS expression is run against _the LHS nodes_. This is useful for updating values based on old values, e.g. increment.
 ## Create yaml file
 Running
 ```bash
diff --git a/pkg/yqlib/doc/Comment Operators.md b/pkg/yqlib/doc/Comment Operators.md
index accc9b47..5a847d88 100644
--- a/pkg/yqlib/doc/Comment Operators.md	
+++ b/pkg/yqlib/doc/Comment Operators.md	
@@ -1,4 +1,15 @@
 Use these comment operators to set or retrieve comments.
+
+Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
+
+
+### plain form: `=`
+This will assign the LHS nodes comments to the expression on the RHS. The RHS is run against the matching nodes in the pipeline
+
+### relative form: `|=` 
+Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.
+
+
 ## Set line comment
 Given a sample.yml file of:
 ```yaml
diff --git a/pkg/yqlib/doc/Has.md b/pkg/yqlib/doc/Has.md
index 1f25009c..6dbfe0f8 100644
--- a/pkg/yqlib/doc/Has.md
+++ b/pkg/yqlib/doc/Has.md
@@ -19,6 +19,29 @@ true
 false
 ```
 
+## Select, checking for existence of deep paths
+Simply pipe in parent expressions into `has`
+
+Given a sample.yml file of:
+```yaml
+- a:
+    b:
+      c: cat
+- a:
+    b:
+      d: dog
+```
+then
+```bash
+yq eval '.[] | select(.a.b | has("c"))' sample.yml
+```
+will output
+```yaml
+a:
+  b:
+    c: cat
+```
+
 ## Has array index
 Given a sample.yml file of:
 ```yaml
diff --git a/pkg/yqlib/doc/headers/Assign.md b/pkg/yqlib/doc/headers/Assign (Assign).md
similarity index 100%
rename from pkg/yqlib/doc/headers/Assign.md
rename to pkg/yqlib/doc/headers/Assign (Assign).md
diff --git a/pkg/yqlib/doc/headers/Comment Operators.md b/pkg/yqlib/doc/headers/Comment Operators.md
index aacd9771..0740a76d 100644
--- a/pkg/yqlib/doc/headers/Comment Operators.md	
+++ b/pkg/yqlib/doc/headers/Comment Operators.md	
@@ -1 +1,11 @@
-Use these comment operators to set or retrieve comments.
\ No newline at end of file
+Use these comment operators to set or retrieve comments.
+
+Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
+
+
+### plain form: `=`
+This will assign the LHS nodes comments to the expression on the RHS. The RHS is run against the matching nodes in the pipeline
+
+### relative form: `|=` 
+Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.
+
diff --git a/pkg/yqlib/operator_assign_test.go b/pkg/yqlib/operator_assign_test.go
index dc397c86..54901f7e 100644
--- a/pkg/yqlib/operator_assign_test.go
+++ b/pkg/yqlib/operator_assign_test.go
@@ -143,5 +143,5 @@ func TestAssignOperatorScenarios(t *testing.T) {
 	for _, tt := range assignOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	documentScenarios(t, "Assign", assignOperatorScenarios)
+	documentScenarios(t, "Assign (Update)", assignOperatorScenarios)
 }
diff --git a/pkg/yqlib/operator_has_test.go b/pkg/yqlib/operator_has_test.go
index 1ca54f5e..453dc0d8 100644
--- a/pkg/yqlib/operator_has_test.go
+++ b/pkg/yqlib/operator_has_test.go
@@ -28,6 +28,15 @@ var hasOperatorScenarios = []expressionScenario{
 			"D0, P[3], (!!bool)::false\n",
 		},
 	},
+	{
+		description:    "Select, checking for existence of deep paths",
+		subdescription: "Simply pipe in parent expressions into `has`",
+		document:       "- {a: {b: {c: cat}}}\n- {a: {b: {d: dog}}}",
+		expression:     `.[] | select(.a.b | has("c"))`,
+		expected: []string{
+			"D0, P[0], (!!map)::{a: {b: {c: cat}}}\n",
+		},
+	},
 	{
 		dontFormatInputForDoc: true,
 		description:           "Has array index",