Adding recipes

README.md

@@ -45,6 +45,11 @@ yq -i '
 ' file.yaml
 ```
 
+Find and update an item in an array:
+```bash
+yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'
+```
+
 Convert JSON to YAML
 ```bash
 yq -Poy sample.json

pkg/yqlib/doc/usage/recipes.md

@@ -0,0 +1,52 @@
+
+## Find items in an array
+Given a sample.yml file of:
+```yaml
+- name: Foo
+  numBuckets: 0
+- name: Bar
+  numBuckets: 0
+```
+then
+```bash
+yq '.[] | select(.name == "Foo")' sample.yml
+```
+will output
+```yaml
+name: Foo
+numBuckets: 0
+```
+
+### Explanation:
+- `.[]` splats the array, and puts all the items in the context.
+- These items are then piped (`|`) into `select(.name == "Foo")` which will select all the nodes that have a name property set to 'Foo'.
+- See the [select](https://mikefarah.gitbook.io/yq/operators/select) operator for more information.
+
+## Find and update items in an array
+Given a sample.yml file of:
+```yaml
+- name: Foo
+  numBuckets: 0
+- name: Bar
+  numBuckets: 0
+```
+then
+```bash
+yq '(.[] | select(.name == "Foo") | .numBuckets) |= . + 1' sample.yml
+```
+will output
+```yaml
+- name: Foo
+  numBuckets: 1
+- name: Bar
+  numBuckets: 0
+```
+
+### Explanation:
+- Following from the example above`.[]` splats the array, selects filters the items.
+- We then pipe (`|`) that into `.numBuckets`, which will select that field from all the matching items
+- Splat, select and the field are all in brackets, that whole expression is passed to the `|=` operator as the left hand side expression, with `. + 1` as the right hand side expression.
+- `|=` is the operator that updates fields relative to their own value, which is referenced as dot (`.`).
+- The expression `. + 1` increments the numBuckets counter.
+- See the [assign](https://mikefarah.gitbook.io/yq/operators/assign-update) and [add](https://mikefarah.gitbook.io/yq/operators/add) operators for more information.
+

pkg/yqlib/operators_test.go

@@ -20,6 +20,7 @@ import (
 type expressionScenario struct {
 	description           string
 	subdescription        string
+	explanation           []string
 	environmentVariables  map[string]string
 	document              string
 	document2             string
@@ -256,6 +257,14 @@ func documentOperatorScenario(t *testing.T, w *bufio.Writer, i interface{}) {
 	writeOrPanic(w, "will output\n")
 
 	documentOutput(t, w, s, formattedDoc, formattedDoc2)
+
+	if len(s.explanation) > 0 {
+		writeOrPanic(w, "### Explanation:\n")
+		for _, text := range s.explanation {
+			writeOrPanic(w, fmt.Sprintf("- %v\n", text))
+		}
+		writeOrPanic(w, "\n")
+	}
 }
 
 func documentInput(w *bufio.Writer, s expressionScenario) (string, string) {

pkg/yqlib/recipes_test.go

@@ -0,0 +1,48 @@
+package yqlib
+
+import (
+	"testing"
+)
+
+var recipes = []expressionScenario{
+	{
+		description: "Find items in an array",
+		explanation: []string{
+			"`.[]` splats the array, and puts all the items in the context.",
+			"These items are then piped (`|`) into `select(.name == \"Foo\")` which will select all the nodes that have a name property set to 'Foo'.",
+			"See the [select](https://mikefarah.gitbook.io/yq/operators/select) operator for more information.",
+		},
+		document:   `[{name: Foo, numBuckets: 0}, {name: Bar, numBuckets: 0}]`,
+		expression: `.[] | select(.name == "Foo")`,
+		expected: []string{
+			"D0, P[0], (!!map)::{name: Foo, numBuckets: 0}\n",
+		},
+	},
+	{
+		description: "Find and update items in an array",
+		document:    `[{name: Foo, numBuckets: 0}, {name: Bar, numBuckets: 0}]`,
+		expression:  `(.[] | select(.name == "Foo") | .numBuckets) |= . + 1`,
+		explanation: []string{
+			"Following from the example above`.[]` splats the array, selects filters the items.",
+			"We then pipe (`|`) that into `.numBuckets`, which will select that field from all the matching items",
+			"Splat, select and the field are all in brackets, that whole expression is passed to the `|=` operator as the left hand side expression, with `. + 1` as the right hand side expression.",
+			"`|=` is the operator that updates fields relative to their own value, which is referenced as dot (`.`).",
+			"The expression `. + 1` increments the numBuckets counter.",
+			"See the [assign](https://mikefarah.gitbook.io/yq/operators/assign-update) and [add](https://mikefarah.gitbook.io/yq/operators/add) operators for more information.",
+		},
+		expected: []string{
+			"D0, P[], (doc)::[{name: Foo, numBuckets: 1}, {name: Bar, numBuckets: 0}]\n",
+		},
+	},
+}
+
+func TestRecipes(t *testing.T) {
+	for _, tt := range recipes {
+		testScenario(t, &tt)
+	}
+	genericScenarios := make([]interface{}, len(recipes))
+	for i, s := range recipes {
+		genericScenarios[i] = s
+	}
+	documentScenarios(t, "usage", "recipes", genericScenarios, documentOperatorScenario)
+}