From e7f040106b5f5a892ebd984f19b21c605e87c142 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Tue, 8 Feb 2022 23:03:04 -0800
Subject: [PATCH] Add an example of --text too, refs #404

---
 docs/cli-reference.rst | 12 ++++++++++--
 sqlite_utils/cli.py    |  7 +++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst
index abfacc2..3359d5b 100644
--- a/docs/cli-reference.rst
+++ b/docs/cli-reference.rst
@@ -22,7 +22,9 @@ This page lists the ``--help`` for every ``sqlite-utils`` CLI sub-command.
     refs = {
         "query": "cli_query",
         "memory": "cli_memory",
-        "insert": ["cli_inserting_data", "cli_insert_csv_tsv"],
+        "insert": [
+            "cli_inserting_data", "cli_insert_csv_tsv", "cli_insert_unstructured", "cli_insert_convert"
+        ],
         "upsert": "cli_upsert",
         "tables": "cli_tables",
         "views": "cli_views",
@@ -182,7 +184,7 @@ See :ref:`cli_memory`.
 insert
 ======
 
-See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`.
+See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`, :ref:`cli_insert_unstructured`, :ref:`cli_insert_convert`.
 
 ::
 
@@ -222,6 +224,12 @@ See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`.
       If you are using --lines your code will be passed a "line" variable, and for
       --text a "text" variable.
 
+      When using --text your function can return an iterator of rows to insert. This
+      example inserts one record per word in the input:
+
+          echo 'A bunch of words' | sqlite-utils insert words.db words - \
+            --text --convert '({"word": w} for w in text.split())'
+
     Options:
       --pk TEXT                 Columns to use as the primary key, e.g. id
       --flatten                 Flatten nested JSON objects, so {"a": {"b": 1}}
diff --git a/sqlite_utils/cli.py b/sqlite_utils/cli.py
index 0da3817..9e0289f 100644
--- a/sqlite_utils/cli.py
+++ b/sqlite_utils/cli.py
@@ -1158,6 +1158,13 @@ def insert(
 
     If you are using --lines your code will be passed a "line" variable,
     and for --text a "text" variable.
+
+    When using --text your function can return an iterator of rows to
+    insert. This example inserts one record per word in the input:
+
+    \b
+        echo 'A bunch of words' | sqlite-utils insert words.db words - \\
+          --text --convert '({"word": w} for w in text.split())'
     """
     try:
         insert_upsert_implementation(