From 99b08fd6125a8325c775df7018d4adced646d2c9 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Mon, 15 Feb 2021 16:38:53 +1100
Subject: [PATCH] Added reduce examples and doc

---
 pkg/yqlib/doc/Reduce.md           | 43 +++++++++++++++++++++++++++++++
 pkg/yqlib/doc/headers/Reduce.md   |  7 +++++
 pkg/yqlib/operator_reduce_test.go | 15 ++++++++---
 3 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 pkg/yqlib/doc/headers/Reduce.md

diff --git a/pkg/yqlib/doc/Reduce.md b/pkg/yqlib/doc/Reduce.md
index e69de29b..824cd9c5 100644
--- a/pkg/yqlib/doc/Reduce.md
+++ b/pkg/yqlib/doc/Reduce.md
@@ -0,0 +1,43 @@
+Reduce is a powerful way to process a collection of data into a new form.
+
+## yq vs jq syntax
+Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn't as sophisticated as `jq` and its only supports infix notation (e.g. a + b, the operator is in the middle of the two parameters) - where as `jq` uses a mix of infix notation with _prefix_ notation (e.g. `reduce a b` is like writing `+ a b`).
+
+To that end, the reduce operator is called `ireduce` for backwards compatability if a prefix version of `reduce` is ever added.
+
+
+## Sum numbers
+Given a sample.yml file of:
+```yaml
+- 10
+- 2
+- 5
+- 3
+```
+then
+```bash
+yq eval '.[] as $item ireduce (0; . + $item)' sample.yml
+```
+will output
+```yaml
+20
+```
+
+## Convert an array to an object
+Given a sample.yml file of:
+```yaml
+- name: Cathy
+  has: apples
+- name: Bob
+  has: bananas
+```
+then
+```bash
+yq eval '.[] as $item ireduce ({}; .[$item | .name] = ($item | .has) )' sample.yml
+```
+will output
+```yaml
+Cathy: apples
+Bob: bananas
+```
+
diff --git a/pkg/yqlib/doc/headers/Reduce.md b/pkg/yqlib/doc/headers/Reduce.md
new file mode 100644
index 00000000..de9afd04
--- /dev/null
+++ b/pkg/yqlib/doc/headers/Reduce.md
@@ -0,0 +1,7 @@
+Reduce is a powerful way to process a collection of data into a new form.
+
+## yq vs jq syntax
+Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn't as sophisticated as `jq` and its only supports infix notation (e.g. a + b, the operator is in the middle of the two parameters) - where as `jq` uses a mix of infix notation with _prefix_ notation (e.g. `reduce a b` is like writing `+ a b`).
+
+To that end, the reduce operator is called `ireduce` for backwards compatability if a prefix version of `reduce` is ever added.
+
diff --git a/pkg/yqlib/operator_reduce_test.go b/pkg/yqlib/operator_reduce_test.go
index acff721a..9b2c0eb5 100644
--- a/pkg/yqlib/operator_reduce_test.go
+++ b/pkg/yqlib/operator_reduce_test.go
@@ -6,17 +6,26 @@ import (
 
 var reduceOperatorScenarios = []expressionScenario{
 	{
-		document:   `[10,2, 5, 3]`,
-		expression: `.[] as $item ireduce (0; . + $item)`,
+		description: "Sum numbers",
+		document:    `[10,2, 5, 3]`,
+		expression:  `.[] as $item ireduce (0; . + $item)`,
 		expected: []string{
 			"D0, P[], (!!int)::20\n",
 		},
 	},
+	{
+		description: "Convert an array to an object",
+		document:    `[{name: Cathy, has: apples},{name: Bob, has: bananas}]`,
+		expression:  `.[] as $item ireduce ({}; .[$item | .name] = ($item | .has) )`,
+		expected: []string{
+			"D0, P[], (!!map)::Cathy: apples\nBob: bananas\n",
+		},
+	},
 }
 
 func TestReduceOperatorScenarios(t *testing.T) {
 	for _, tt := range reduceOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	// documentScenarios(t, "Reduce", reduceOperatorScenarios)
+	documentScenarios(t, "Reduce", reduceOperatorScenarios)
 }