From dc45add0e94074c355331aa6fb3236b305f2788d Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 31 Mar 2023 10:22:57 +1100
Subject: [PATCH] toml docs

---
 SUMMARY.md    |   1 +
 usage/toml.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+)
 create mode 100644 usage/toml.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 8ca887f2..f5207201 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -76,6 +76,7 @@
 * [Working with JSON](usage/convert.md)
 * [Working with Properties](usage/properties.md)
 * [Working with XML](usage/xml.md)
+* [Working with TOML](usage/toml.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/toml.md b/usage/toml.md
new file mode 100644
index 00000000..b40b827c
--- /dev/null
+++ b/usage/toml.md
@@ -0,0 +1,111 @@
+# TOML
+
+Decode from TOML. Note that `yq` does not yet support outputting in TOML format (and therefore it cannot roundtrip)
+
+
+## Parse: Simple
+Given a sample.toml file of:
+```toml
+A = "hello"
+B = 12
+
+```
+then
+```bash
+yq -oy '.' sample.toml
+```
+will output
+```yaml
+A: hello
+B: 12
+```
+
+## Parse: Deep paths
+Given a sample.toml file of:
+```toml
+person.name = "hello"
+person.address = "12 cat st"
+
+```
+then
+```bash
+yq -oy '.' sample.toml
+```
+will output
+```yaml
+person:
+  name: hello
+  address: 12 cat st
+```
+
+## Parse: inline table
+Given a sample.toml file of:
+```toml
+name = { first = "Tom", last = "Preston-Werner" }
+```
+then
+```bash
+yq -oy '.' sample.toml
+```
+will output
+```yaml
+name:
+  first: Tom
+  last: Preston-Werner
+```
+
+## Parse: Array Table
+Given a sample.toml file of:
+```toml
+
+[owner.contact]
+name = "Tom Preston-Werner"
+age = 36
+
+[[owner.addresses]]
+street = "first street"
+suburb = "ok"
+
+[[owner.addresses]]
+street = "second street"
+suburb = "nice"
+
+```
+then
+```bash
+yq -oy '.' sample.toml
+```
+will output
+```yaml
+owner:
+  contact:
+    name: Tom Preston-Werner
+    age: 36
+  addresses:
+    - street: first street
+      suburb: ok
+    - street: second street
+      suburb: nice
+```
+
+## Parse: with header
+Given a sample.toml file of:
+```toml
+
+[servers]
+
+[servers.alpha]
+ip = "10.0.0.1"
+
+```
+then
+```bash
+yq -oy '.' sample.toml
+```
+will output
+```yaml
+servers:
+  alpha:
+    ip: 10.0.0.1
+```
+