From 61f561a9e0d8e19fb8a4a6fb1610a67505c966ae Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Wed, 24 Nov 2021 11:15:42 +1100
Subject: [PATCH] Updating docs

---
 SUMMARY.md                     |  2 +
 operators/comment-operators.md |  2 +-
 operators/keys.md              | 78 ++++++++++++++++++++++++++++
 operators/load.md              | 94 ++++++++++++++++++++++++++++++++++
 operators/parent.md            | 52 +++++++++++++++++++
 5 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 operators/load.md
 create mode 100644 operators/parent.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 15f5d9b6..92bde42c 100644
--- a/SUMMARY.md
+++ b/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)
diff --git a/operators/comment-operators.md b/operators/comment-operators.md
index 6086b20a..809ba5c4 100644
--- a/operators/comment-operators.md
+++ b/operators/comment-operators.md
@@ -139,7 +139,7 @@ will output
 welcome!
 ```
 
-## 
+## Head comment with document split
 Given a sample.yml file of:
 ```yaml
 # welcome!
diff --git a/operators/keys.md b/operators/keys.md
index 9d1cea1b..746f7a68 100644
--- a/operators/keys.md
+++ b/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
+```
+
diff --git a/operators/load.md b/operators/load.md
new file mode 100644
index 00000000..aa43f486
--- /dev/null
+++ b/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.
+```
+
diff --git a/operators/parent.md b/operators/parent.md
new file mode 100644
index 00000000..30c78929
--- /dev/null
+++ b/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
+```
+