From e0c5bdca38e8509b8e913f18b10637afeb4edfe2 Mon Sep 17 00:00:00 2001
From: Tim Van Baak <tim.vanbaak@gmail.com>
Date: Thu, 20 Feb 2025 19:20:38 -0800
Subject: [PATCH] Add snippets to README

---
 README.md          | 28 ++++++++++++++++++++++++++++
 test/test_items.sh |  2 +-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3c57f8a..2506f90 100644
--- a/README.md
+++ b/README.md
@@ -140,3 +140,31 @@ Future features
 * Nix flake templates
   * [ ] parsing a news feed
   * [ ] following a webcomic
+
+## Useful snippets
+
+`sh -c` is very useful for turning small shell pipelines into intake sources, especially combined with `jq`.
+This fetch action warns when the disk is getting full:
+
+```bash
+sh -c 'df -h --output=pcent /home/user | grep -oe '\''[0-9]*'\'' | jq -c '\''if . > 85 then { id: "warning", title: "Free space usage: \(.)%", ttd: 1 } else empty end'\'''
+```
+
+Note that the last parameter to `df` narrows the listing down to just the mount with the home directory on it, so there's only one percentage being reported.
+The threshold is defined by the `if` in the `jq` expression.
+By using the `empty` output when below the threshold, the source returns no items when usage is low.
+This is necessary to allow the item `ttd` to delete it.
+
+If you want a source to act as a scheduled reminder, it is necessary for the fetch to return an item with a new id every time.
+A short `/dev/random` pipeline can provide a random id to a `jq` expression:
+
+```bash
+sh -c "cat /dev/random | base32 | head -c8 | jq -cR '{id: ., title: \"Hello\"}'"
+```
+
+You can generalize this using `jq`'s `env` and set the message as a source environment variable:
+
+```bash
+# with MESSAGE defined on the source
+sh -c "cat /dev/random | base32 | head -c8 | jq -cR '{id: ., title: env.MESSAGE}'"
+```
diff --git a/test/test_items.sh b/test/test_items.sh
index 8937e70..3b2a4c2 100755
--- a/test/test_items.sh
+++ b/test/test_items.sh
@@ -57,7 +57,7 @@ tmp/intake item add -s page --id 212 --title "Item 212" --body "This is the body
 # test auto update
 tmp/intake source env -s nothing --set "INTAKE_FETCH=every 5m"
 tmp/intake source add -s hello
-tmp/intake action add -s hello -a fetch -- sh -c "cat /dev/random | tr -dc 'A-Za-z0-9' | head -c16 | jq -cR '{id: ., title: \"Hello\"}'"
+tmp/intake action add -s hello -a fetch -- sh -c "cat /dev/random | base32 | head -c8 | jq -cR '{id: ., title: \"Hello\"}'"
 tmp/intake source env -s hello --set "INTAKE_FETCH=every 1m"
 
 # default password, comment out to test no password