From 13679e51e281e5769591dd647a851db93d16978c Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Thu, 26 Nov 2020 11:20:53 +1100
Subject: [PATCH] Added get key examples

---
 pkg/yqlib/doc/.gitignore        |  1 +
 pkg/yqlib/doc/Path.md           | 34 +++++++++++++++++++++++++++++++++
 pkg/yqlib/doc/aa.md             |  0
 pkg/yqlib/doc/headers/Path.md   |  4 +++-
 pkg/yqlib/operator_path_test.go | 16 ++++++++++++++++
 5 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 pkg/yqlib/doc/.gitignore
 create mode 100644 pkg/yqlib/doc/aa.md

diff --git a/pkg/yqlib/doc/.gitignore b/pkg/yqlib/doc/.gitignore
new file mode 100644
index 00000000..c4c4ffc6
--- /dev/null
+++ b/pkg/yqlib/doc/.gitignore
@@ -0,0 +1 @@
+*.zip
diff --git a/pkg/yqlib/doc/Path.md b/pkg/yqlib/doc/Path.md
index 4acacce0..9bf1f404 100644
--- a/pkg/yqlib/doc/Path.md
+++ b/pkg/yqlib/doc/Path.md
@@ -1,4 +1,7 @@
 The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
+
+You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.
+
 ## Map path
 Given a sample.yml file of:
 ```yaml
@@ -15,6 +18,21 @@ will output
 - b
 ```
 
+## Get map key
+Given a sample.yml file of:
+```yaml
+a:
+  b: cat
+```
+then
+```bash
+yq eval '.a.b | path | .[-1]' sample.yml
+```
+will output
+```yaml
+b
+```
+
 ## Array path
 Given a sample.yml file of:
 ```yaml
@@ -32,6 +50,22 @@ will output
 - 1
 ```
 
+## Get array index
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - dog
+```
+then
+```bash
+yq eval '.a.[] | select(. == "dog") | path | .[-1]' sample.yml
+```
+will output
+```yaml
+1
+```
+
 ## Print path and value
 Given a sample.yml file of:
 ```yaml
diff --git a/pkg/yqlib/doc/aa.md b/pkg/yqlib/doc/aa.md
new file mode 100644
index 00000000..e69de29b
diff --git a/pkg/yqlib/doc/headers/Path.md b/pkg/yqlib/doc/headers/Path.md
index fdb4ec0b..3347edea 100644
--- a/pkg/yqlib/doc/headers/Path.md
+++ b/pkg/yqlib/doc/headers/Path.md
@@ -1 +1,3 @@
-The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
\ No newline at end of file
+The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
+
+You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.
diff --git a/pkg/yqlib/operator_path_test.go b/pkg/yqlib/operator_path_test.go
index 8102faf3..d9170878 100644
--- a/pkg/yqlib/operator_path_test.go
+++ b/pkg/yqlib/operator_path_test.go
@@ -13,6 +13,14 @@ var pathOperatorScenarios = []expressionScenario{
 			"D0, P[a b], (!!seq)::- a\n- b\n",
 		},
 	},
+	{
+		description: "Get map key",
+		document:    `{a: {b: cat}}`,
+		expression:  `.a.b | path | .[-1]`,
+		expected: []string{
+			"D0, P[a b -1], (!!str)::b\n",
+		},
+	},
 	{
 		description: "Array path",
 		document:    `{a: [cat, dog]}`,
@@ -21,6 +29,14 @@ var pathOperatorScenarios = []expressionScenario{
 			"D0, P[a 1], (!!seq)::- a\n- 1\n",
 		},
 	},
+	{
+		description: "Get array index",
+		document:    `{a: [cat, dog]}`,
+		expression:  `.a.[] | select(. == "dog") | path | .[-1]`,
+		expected: []string{
+			"D0, P[a 1 -1], (!!int)::1\n",
+		},
+	},
 	{
 		description: "Print path and value",
 		document:    `{a: [cat, dog, frog]}`,