Added contains operator

pkg/yqlib/doc/Contains.md

@@ -0,0 +1,85 @@
+
+## Array contains array
+Array is equal or subset of
+
+Given a sample.yml file of:
+```yaml
+- foobar
+- foobaz
+- blarp
+```
+then
+```bash
+yq eval 'contains(["baz", "bar"])' sample.yml
+```
+will output
+```yaml
+true
+```
+
+## Object included in array
+Given a sample.yml file of:
+```yaml
+"foo": 12
+"bar":
+  - 1
+  - 2
+  - "barp": 12
+    "blip": 13
+```
+then
+```bash
+yq eval 'contains({"bar": [{"barp": 12}]})' sample.yml
+```
+will output
+```yaml
+true
+```
+
+## Object not included in array
+Given a sample.yml file of:
+```yaml
+"foo": 12
+"bar":
+  - 1
+  - 2
+  - "barp": 12
+    "blip": 13
+```
+then
+```bash
+yq eval 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml
+```
+will output
+```yaml
+false
+```
+
+## String contains substring
+Given a sample.yml file of:
+```yaml
+foobar
+```
+then
+```bash
+yq eval 'contains("bar")' sample.yml
+```
+will output
+```yaml
+true
+```
+
+## String equals string
+Given a sample.yml file of:
+```yaml
+meow
+```
+then
+```bash
+yq eval 'contains("meow")' sample.yml
+```
+will output
+```yaml
+true
+```
+

pkg/yqlib/doc/With.md

@@ -1,4 +1,4 @@
-Use the `with` operator to conveniently make multiple updates to a deeply nested path.
+Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other.
 
 ## Update and style
 Given a sample.yml file of:
@@ -18,3 +18,43 @@ a:
     nested: 'newValue'
 ```
 
+## Update multiple deeply nested properties
+Given a sample.yml file of:
+```yaml
+a:
+  deeply:
+    nested: value
+    other: thing
+```
+then
+```bash
+yq eval 'with(.a.deeply ; .nested = "newValue" | .other= "newThing")' sample.yml
+```
+will output
+```yaml
+a:
+  deeply:
+    nested: newValue
+    other: newThing
+```
+
+## Update array elements relatively
+Given a sample.yml file of:
+```yaml
+myArray:
+  - a: apple
+  - a: banana
+```
+then
+```bash
+yq eval 'with(.myArray[] ; .b = .a + " yum")' sample.yml
+```
+will output
+```yaml
+myArray:
+  - a: apple
+    b: apple yum
+  - a: banana
+    b: banana yum
+```
+

pkg/yqlib/doc/headers/With.md

@@ -1 +1 @@
-Use the `with` operator to conveniently make multiple updates to a deeply nested path.
+Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other.