From 3bb896cfa8e94fbb1e6963f6fee1593dfc7781e1 Mon Sep 17 00:00:00 2001
From: Bram Schoenmakers <me@bramschoenmakers.nl>
Date: Wed, 10 Apr 2024 18:16:48 +0200
Subject: [PATCH] Explain a prompt text generated by a function

---
 README.org | 18 ++++++++++++++++++
 kagi.el    |  7 ++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index ecebac5..030e98c 100644
--- a/README.org
+++ b/README.org
@@ -143,6 +143,24 @@ The first argument is the name of the command that will be defined. The second a
 
 The defined prompt becomes a typical Emacs command that takes one argument to fill the placeholder. You could bind the prompt command to a key, use it to integrate with Embark (see below) or to list all your prompts with a Hydra.
 
+The prompt string may also be a function that returns the prompt
+string. The function may take one argument: whether the command was
+called interactively or not. This can be used to alter the prompt
+based on how the command was called. E.g. a non-interactive version
+could contain an instruction to say either /Yes/ or /No/. See
+=kagi-proofread= for an example:
+
+#+begin_src elisp
+  (define-kagi-fastgpt-prompt kagi-proofread
+                              (lambda (interactive-p)
+                                (format "Proofread the following text. %s
+
+  %%s" (if interactive-p "" "Say OK if there are no issues.")))
+                              "Proofread")
+#+end_src
+
+Note the =%%s= notation, =format= turns it into =%s= which becomes the prompt placeholder.
+
 ** Embark integration
 
 The kagi.el package can be integrated with [[https://github.com/oantolin/embark][Embark]]. Use it to easily summarize, translate or proofread a buffer, region or a URL. It can also be used to call your custom prompts with =define-kagi-fastgpt-prompt=.
diff --git a/kagi.el b/kagi.el
index 0d8bc48..e9ef540 100644
--- a/kagi.el
+++ b/kagi.el
@@ -79,7 +79,12 @@ https://kagi.com/settings?p=api"
 (defmacro define-kagi-fastgpt-prompt (symbol-name prompt &optional name)
   "Define a command SYMBOL-NAME that executes the given PROMPT.
 
-PROMPT can be a string or a function returning a string.
+PROMPT can be a string or a function returning a string. The
+function may take one argument: whether the command was called
+interactively or not. This can be used to alter the prompt based
+on how the command was called. E.g. a non-interactive version
+could contain an instruction to say either Yes or No. See
+`kagi-proofread' for an example.
 
 When PROMPT contains %s, it will be replaced with the region (if
 active), the (narrowed) buffer content of the selected buffer or