Added DELPATHS operator

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

@@ -1,5 +1,8 @@
 # Path
 
-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.
+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.
+
+Use `setpath` to set a value to the path array returned by `path`, and similarly `delpaths` for an array of path arrays.
+

pkg/yqlib/doc/operators/path.md

@@ -1,9 +1,12 @@
 # Path
 
-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.
+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.
 
+Use `setpath` to set a value to the path array returned by `path`, and similarly `delpaths` for an array of path arrays.
+
+
 {% hint style="warning" %}
 Note that versions prior to 4.18 require the 'eval/e' command to be specified. 
 
@@ -154,3 +157,58 @@ a:
   - things
 ```
 
+## Delete path
+Notice delpaths takes an _array_ of paths.
+
+Given a sample.yml file of:
+```yaml
+a:
+  b: cat
+  c: dog
+  d: frog
+```
+then
+```bash
+yq 'delpaths([["a", "c"], ["a", "d"]])' sample.yml
+```
+will output
+```yaml
+a:
+  b: cat
+```
+
+## Delete array path
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - frog
+```
+then
+```bash
+yq 'delpaths([["a", 0]])' sample.yml
+```
+will output
+```yaml
+a:
+  - frog
+```
+
+## Delete - wrong parameter
+delpaths does not work with a single path array
+
+Given a sample.yml file of:
+```yaml
+a:
+  - cat
+  - frog
+```
+then
+```bash
+yq 'delpaths(["a", 0])' sample.yml
+```
+will output
+```bash
+Error: DELPATHS: expected entry [0] to be a sequence, but its a !!str. Note that delpaths takes an array of path arrays, e.g. [["a", "b"]]
+```
+