From 3388f9f3e2c1c065e275ff0b62cede7988f98afc Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Tue, 23 May 2023 13:28:47 +1000
Subject: [PATCH] v4.34.1

---
 SUMMARY.md              |  1 +
 usage/shellvariables.md | 86 +++++++++++++++++++++++++++++++++++++++++
 usage/toml.md           | 16 ++++++++
 3 files changed, 103 insertions(+)
 create mode 100644 usage/shellvariables.md

diff --git a/SUMMARY.md b/SUMMARY.md
index f5207201..6788a995 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -77,6 +77,7 @@
 * [Working with Properties](usage/properties.md)
 * [Working with XML](usage/xml.md)
 * [Working with TOML](usage/toml.md)
+* [Working with Shell Output](usage/shellvariables.md)
 * [Front Matter](usage/front-matter.md)
 * [Split into multiple files](usage/split-into-multiple-files.md)
 * [GitHub Action](usage/github-action.md)
diff --git a/usage/shellvariables.md b/usage/shellvariables.md
new file mode 100644
index 00000000..a2919715
--- /dev/null
+++ b/usage/shellvariables.md
@@ -0,0 +1,86 @@
+
+## Encode shell variables
+Note that comments are dropped and values will be enclosed in single quotes as needed.
+
+Given a sample.yml file of:
+```yaml
+# comment
+name: Mike Wazowski
+eyes:
+  color: turquoise
+  number: 1
+friends:
+  - James P. Sullivan
+  - Celia Mae
+```
+then
+```bash
+yq -o=shell sample.yml
+```
+will output
+```sh
+name='Mike Wazowski'
+eyes_color=turquoise
+eyes_number=1
+friends_0='James P. Sullivan'
+friends_1='Celia Mae'
+```
+
+## Encode shell variables: illegal variable names as key.
+Keys that would be illegal as variable keys are adapted.
+
+Given a sample.yml file of:
+```yaml
+ascii_=_symbols: replaced with _
+"ascii_	_controls": dropped (this example uses \t)
+nonascii_א_characters: dropped
+effrot_expeñded_tò_preserve_accented_latin_letters: moderate (via unicode NFKD)
+
+```
+then
+```bash
+yq -o=shell sample.yml
+```
+will output
+```sh
+ascii___symbols='replaced with _'
+ascii__controls='dropped (this example uses \t)'
+nonascii__characters=dropped
+effrot_expended_to_preserve_accented_latin_letters='moderate (via unicode NFKD)'
+```
+
+## Encode shell variables: empty values, arrays and maps
+Empty values are encoded to empty variables, but empty arrays and maps are skipped.
+
+Given a sample.yml file of:
+```yaml
+empty:
+  value:
+  array: []
+  map:   {}
+```
+then
+```bash
+yq -o=shell sample.yml
+```
+will output
+```sh
+empty_value=
+```
+
+## Encode shell variables: single quotes in values
+Single quotes in values are encoded as '"'"' (close single quote, double-quoted single quote, open single quote).
+
+Given a sample.yml file of:
+```yaml
+name: Miles O'Brien
+```
+then
+```bash
+yq -o=shell sample.yml
+```
+will output
+```sh
+name='Miles O'"'"'Brien'
+```
+
diff --git a/usage/toml.md b/usage/toml.md
index 1ebe2336..65ed5348 100644
--- a/usage/toml.md
+++ b/usage/toml.md
@@ -38,6 +38,22 @@ person:
   address: 12 cat st
 ```
 
+## Encode: Scalar
+Given a sample.toml file of:
+```toml
+person.name = "hello"
+person.address = "12 cat st"
+
+```
+then
+```bash
+yq '.person.name' sample.toml
+```
+will output
+```yaml
+hello
+```
+
 ## Parse: inline table
 Given a sample.toml file of:
 ```toml