From bded701f73e3bad6a9f42b74a9f7d93ba36c8fae Mon Sep 17 00:00:00 2001
From: Simon de Vlieger <cmdr@supakeen.com>
Date: Mon, 3 Jun 2024 13:00:01 +0200
Subject: [PATCH] doc: add external example

Signed-off-by: Simon de Vlieger <cmdr@supakeen.com>
---
 doc/03-omnifest/02-external.md | 58 ++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/doc/03-omnifest/02-external.md b/doc/03-omnifest/02-external.md
index 5672870e..ef9da06d 100644
--- a/doc/03-omnifest/02-external.md
+++ b/doc/03-omnifest/02-external.md
@@ -67,6 +67,64 @@ Into this YAML structure:
 dummy:
 ```
 
+## Example
+
+The following example demonstrates how an external can be used to implement string
+concatenation.
+
+Given the following script called `concat` in `/usr/local/libexec/otk/concat`:
+
+```bash
+#!/usr/bin/env bash
+
+output="$(jq -jr '.tree."otk.external.concat".parts[]' <<< "${1}")"
+echo "{\"tree\":{\"output\":\"$output\"}}"
+```
+
+and the following directive:
+
+```yaml
+examplestring:
+  otk.external.concat:
+    parts:
+      - list
+      - of
+      - strings
+```
+
+the script is called with the following data on stdin:
+
+```json
+{
+  "tree": {
+    "otk.external.concat": {
+      "parts": [
+        "list",
+        "of",
+        "strings"
+      ]
+    }
+  }
+}
+```
+
+which results in the following output:
+
+```json
+{
+  "tree": {
+    "string": "listofstrings"
+  }
+}
+```
+
+and the final omnifest will be:
+
+```yaml
+examplestring:
+  listofstrings
+```
+
 ## Paths
 
 `otk` will look for external directives in the following paths, stopping when