Updating docs

SUMMARY.md

@@ -34,7 +34,9 @@
   * [Has](operators/has.md)
   * [Keys](operators/keys.md)
   * [Length](operators/length.md)
+  * [Load](operators/load.md)
   * [Multiply (Merge)](operators/multiply-merge.md)
+  * [Parent](operators/parent.md)
   * [Path](operators/path.md)
   * [Pipe](operators/pipe.md)
   * [Recursive Descent (Glob)](operators/recursive-descent-glob.md)

operators/comment-operators.md

@@ -139,7 +139,7 @@ will output
 welcome!
 ```
 
-## 
+## Head comment with document split
 Given a sample.yml file of:
 ```yaml
 # welcome!

operators/keys.md

@@ -34,3 +34,81 @@ will output
 - 1
 ```
 
+## Retrieve array key
+Given a sample.yml file of:
+```yaml
+- 1
+- 2
+- 3
+```
+then
+```bash
+yq eval '.[1] | key' sample.yml
+```
+will output
+```yaml
+1
+```
+
+## Retrieve map key
+Given a sample.yml file of:
+```yaml
+a: thing
+```
+then
+```bash
+yq eval '.a | key' sample.yml
+```
+will output
+```yaml
+a
+```
+
+## No key
+Given a sample.yml file of:
+```yaml
+{}
+```
+then
+```bash
+yq eval 'key' sample.yml
+```
+will output
+```yaml
+```
+
+## Update map key
+Given a sample.yml file of:
+```yaml
+a:
+  x: 3
+  y: 4
+```
+then
+```bash
+yq eval '(.a.x | key) = "meow"' sample.yml
+```
+will output
+```yaml
+a:
+  meow: 3
+  y: 4
+```
+
+## Get comment from map key
+Given a sample.yml file of:
+```yaml
+a:
+  # comment on key
+  x: 3
+  y: 4
+```
+then
+```bash
+yq eval '.a.x | key | headComment' sample.yml
+```
+will output
+```yaml
+comment on key
+```
+

operators/load.md

@@ -0,0 +1,94 @@
+# Load
+
+The `load`/`strload` operator allows you to load in content from another file referenced in your yaml document.
+
+Note that you can use string operators like `+` and `sub` to modify the value in the yaml file to a path that exists in your system.
+
+Use `strload` to load text based content as a string block, and `load` to interpret the file as yaml.
+
+Lets say there is a file `../../examples/thing.yml`:
+
+```yaml
+a: apple is included
+b: cool
+```
+
+## Simple example
+Given a sample.yml file of:
+```yaml
+myFile: ../../examples/thing.yml
+```
+then
+```bash
+yq eval 'load(.myFile)' sample.yml
+```
+will output
+```yaml
+a: apple is included
+b: cool.
+```
+
+## Replace node with referenced file
+Note that you can modify the filename in the load operator if needed.
+
+Given a sample.yml file of:
+```yaml
+something:
+  file: thing.yml
+```
+then
+```bash
+yq eval '.something |= load("../../examples/" + .file)' sample.yml
+```
+will output
+```yaml
+something:
+  a: apple is included
+  b: cool.
+```
+
+## Replace _all_ nodes with referenced file
+Recursively match all the nodes (`..`) and then filter the ones that have a 'file' attribute. 
+
+Given a sample.yml file of:
+```yaml
+something:
+  file: thing.yml
+over:
+  here:
+    - file: thing.yml
+```
+then
+```bash
+yq eval '(.. | select(has("file"))) |= load("../../examples/" + .file)' sample.yml
+```
+will output
+```yaml
+something:
+  a: apple is included
+  b: cool.
+over:
+  here:
+    - a: apple is included
+      b: cool.
+```
+
+## Replace node with referenced file as string
+This will work for any text based file
+
+Given a sample.yml file of:
+```yaml
+something:
+  file: thing.yml
+```
+then
+```bash
+yq eval '.something |= strload("../../examples/" + .file)' sample.yml
+```
+will output
+```yaml
+something: |-
+  a: apple is included
+  b: cool.
+```
+

operators/parent.md

@@ -0,0 +1,52 @@
+# Parent
+
+Parent simply returns the parent nodes of the matching nodes.
+
+## Simple example
+Given a sample.yml file of:
+```yaml
+a:
+  nested: cat
+```
+then
+```bash
+yq eval '.a.nested | parent' sample.yml
+```
+will output
+```yaml
+nested: cat
+```
+
+## Parent of nested matches
+Given a sample.yml file of:
+```yaml
+a:
+  fruit: apple
+  name: bob
+b:
+  fruit: banana
+  name: sam
+```
+then
+```bash
+yq eval '.. | select(. == "banana") | parent' sample.yml
+```
+will output
+```yaml
+fruit: banana
+name: sam
+```
+
+## No parent
+Given a sample.yml file of:
+```yaml
+{}
+```
+then
+```bash
+yq eval 'parent' sample.yml
+```
+will output
+```yaml
+```
+