[elpa] externals/consult 1e9153dfd1 2/4: README: Revise hacking section

[ELPA Syncer]

branch: externals/consult
commit 1e9153dfd1d9d89a5b89c9706d405d58c03c1437
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    README: Revise hacking section
---
 README.org | 98 +++++++++++++++++++++++++-------------------------------------
 1 file changed, 40 insertions(+), 58 deletions(-)

diff --git a/README.org b/README.org
index af43229490..398aaac680 100644
--- a/README.org
+++ b/README.org
@@ -1113,89 +1113,71 @@ When evaluating Consult-related code snippets you 
should enable [[https://www.gn
 Consult often relies on lambdas and lexical closures.
 
 * Hacking
-** Creating a new asynchronous completion source
+** Creating asynchronous completion commands
 
 If you have a completion source that's both dynamic and expensive to generate,
 =completing-read= may not be the best choice. Instead, =consult--read= serves 
as a
-thin wrapper around =completing-read= that provides this functionality.
-
-For example, consider the following script that splits its input on space:
+thin wrapper around =completing-read= that provides this functionality. For
+example, consider the following slow script that splits its input on space:
 
 #+begin_src sh
-  #!/usr/bin/env bash
-
-  # simulate work
-  sleep .1
-
-  # generate completion candidates
-  printf "%s\n" "$*" | tr " " "\n" | sort
+#!/usr/bin/env bash
+# simulate work
+sleep .1
+# generate completion candidates
+printf "%s\n" "$*" | tr " " "\n" | sort
 #+end_src
 
-Let's assume this script is callable as =testibus hello world=.
-
-To have Consult use it as a completion source, use =consult--async-command=:
+Let's assume this script is callable as =testibus hello world=. To have Consult
+use it for completion, use =consult--async-command=:
 
 #+begin_src emacs-lisp
-  (consult--read
-   (consult--async-command (lambda (input) (list "testibus" (s-trim input))))
-   :prompt "run testibus: ")
+(consult--read
+ (consult--async-command (lambda (input) (list "testibus" (string-trim 
input))))
+ :prompt "run testibus: ")
 #+end_src
 
-If your completion source is generated by Lisp instead, use
+If the completion candidates are generated by Lisp instead, use
 =consult--dynamic-collection=:
 
 #+begin_src emacs-lisp
-  (consult--read
-   (consult--dynamic-collection
-    (lambda (input)
-      (sit-for 0.1)
-      (thread-first
-        (string-trim input)
-        (split-string nil t)
-        (sort #'string<)))))
-   :prompt "run testibus: ")
+(consult--read
+ (consult--dynamic-collection
+  (lambda (input)
+    (sleep-for 0.1) ;; Simulate work
+    (sort (split-string (string-trim input) nil t) #'string<)))
+ :prompt "run testibus: ")
 #+end_src
 
-*** ...with live preview
+** Live preview
 
-Implementing live preview is a little more involved and requires the definition
-of a =STATE= function as defined by =consult--with-preview=.
-
-The =STATE= function receives the candidate and some action to perform (e.g.,
-='preview=). In its simplest form supporting live preview, it looks something 
like
-this:
+Implementing live preview requires the definition of a state or preview 
function
+as defined by =consult--with-preview=. The preview function receives the 
candidate
+and some action to perform (e.g., ='preview=). In its simplest form supporting
+live preview, it looks something like this:
 
 #+begin_src emacs-lisp
-  (defun testibus--state ()
-    (lambda (action cand)
-      (pcase action
-        ('preview
-         (with-current-buffer-window " *testibus*" 'action nil
-           (erase-buffer)
-           (insert (format "input: %s\n" cand)))))))
+(defun testibus--preview (action cand)
+  (pcase action
+    ('preview
+     (with-current-buffer-window " *testibus*" 'action nil
+       (erase-buffer)
+       (insert (format "input: %s\n" cand))))))
 #+end_src
 
-See =consult--with-preview= for the lifecycle of =ACTION=.
-
-Once defined, we can use this =STATE= function in =consult--read=:
+See the docstring of =consult--with-preview= for the lifecycle of the action
+argument. Once defined, we can use this preview function in =consult--read=:
 
 #+begin_src emacs-lisp
-  (consult--read
-   (consult--dynamic-collection
-    (lambda (input)
-      (sit-for 0.1)
-      (thread-first
-        (string-trim input)
-        (split-string nil t)
-        (sort #'string<))))
-   :prompt "run testibus: "
-   :state (testibus--state))
+(consult--read
+ (consult--dynamic-collection
+  (lambda (input)
+    (sleep-for 0.1) ;; Simulate work
+    (sort (split-string (string-trim input) nil t) #'string<)))
+ :prompt "run testibus: "
+ :state #'testibus--preview)
 #+end_src
 
-Note that depending on how expensive the ='preview= logic is, you may wish to 
take
-advantage of the built-in threading support or use an external package such as
-[[https://github.com/jwiegley/emacs-async][emacs-async]].
-
 * Contributions
 :properties:
 :description: Feature requests and pull requests