Added recursive update map keys example

Author: mikefarah

pkg/yqlib/doc/operators/entries.md

@@ -2,6 +2,8 @@
 
 Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.
 
+Use `with_entries(op)` as a syntatic sugar for doing `to_entries | op | from_entries`.
+
 ## to_entries Map
 Given a sample.yml file of:
 ```yaml
@@ -101,6 +103,28 @@ KEY_a: 1
 KEY_b: 2
 ```
 
+## Use with_entries to update keys recursively
+We use (.. | select(tag="map")) to find all the maps in the doc, then |= to update each one of those maps. In the update, with_entries is used.
+
+Given a sample.yml file of:
+```yaml
+a: 1
+b:
+  b_a: nested
+  b_b: thing
+```
+then
+```bash
+yq '(.. | select(tag=="!!map")) |= with_entries(.key |= "KEY_" + .)' sample.yml
+```
+will output
+```yaml
+KEY_a: 1
+KEY_b:
+  KEY_b_a: nested
+  KEY_b_b: thing
+```
+
 ## Custom sort map keys
 Use to_entries to convert to an array of key/value pairs, sort the array using sort/sort_by/etc, and convert it back.
 

pkg/yqlib/doc/operators/headers/entries.md

@@ -1,3 +1,5 @@
 # Entries
 
 Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.
+
+Use `with_entries(op)` as a syntatic sugar for doing `to_entries | op | from_entries`.

pkg/yqlib/doc/operators/sort.md

@@ -110,7 +110,7 @@ cool:
 ```
 
 ## Sort a map
-Sorting a map, by default, will sort by the values
+Sorting a map, by default this will sort by the values
 
 Given a sample.yml file of:
 ```yaml

pkg/yqlib/operator_entries_test.go

@@ -72,6 +72,15 @@ var entriesOperatorScenarios = []expressionScenario{
 			"D0, P[], (!!map)::KEY_a: 1\nKEY_b: 2\n",
 		},
 	},
+	{
+		description:    "Use with_entries to update keys recursively",
+		document:       `{a: 1, b: {b_a: nested, b_b: thing}}`,
+		expression:     `(.. | select(tag=="!!map")) |= with_entries(.key |= "KEY_" + .)`,
+		subdescription: "We use (.. | select(tag=\"map\")) to find all the maps in the doc, then |= to update each one of those maps. In the update, with_entries is used.",
+		expected: []string{
+			"D0, P[], (!!map)::{KEY_a: 1, KEY_b: {KEY_b_a: nested, KEY_b_b: thing}}\n",
+		},
+	},
 	{
 		skipDoc:     true,
 		description: "Use with_entries to update keys comment",