[elpa] externals/consult 9f2ea67ab8: Update key convention, keys must be `key-valid-p'

[ELPA Syncer]

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

    Update key convention, keys must be `key-valid-p'
    
    This change affects:
    
    - consult-narrow-key
    - consult-widen-key
    - consult-preview-key
    - :preview-key of sources and consult--read
---
 CHANGELOG.org |  4 ++++
 README.org    | 26 +++++++++++------------
 consult.el    | 66 ++++++++++++++++++++++++++++++++++++++---------------------
 3 files changed, 60 insertions(+), 36 deletions(-)

diff --git a/CHANGELOG.org b/CHANGELOG.org
index aefd512964..d2e7845341 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -5,6 +5,10 @@
 * Development
 
 - Bugfixes
+- Update the key convention. Keys must now be strings valid according to
+  =key-valid-p=. This changes affects the keys =consult-narrow-key=,
+  =consult-widen-key=, =consult-preview-key= and the =:preview-key= of sources 
and
+  passed as keyword argument to =consult--read=.
 - Add =consult-info= command (#634, #727).
 - =consult-buffer=: Always select the first candidate when narrowing (#714).
 - =consult-locate-args=: Remove =--existing=, which is not supported by 
=plocate= on
diff --git a/README.org b/README.org
index 3b9c28b1ff..d92220c2d5 100644
--- a/README.org
+++ b/README.org
@@ -439,8 +439,8 @@ following settings are possible:
 
 - Automatic and immediate ='any=
 - Automatic and delayed =(list :debounce 0.5 'any)=
-- Manual and immediate =(kbd "M-.")=
-- Manual and delayed =(list :debounce 0.5 (kbd "M-."))=
+- Manual and immediate ="M-."=
+- Manual and delayed =(list :debounce 0.5 "M-.")=
 - Disabled =nil=
 
 A safe recommendation is to leave automatic immediate previews enabled in
@@ -460,7 +460,7 @@ to be considered.
    consult--source-recent-file consult--source-project-recent-file
    ;; my/command-wrapping-consult    ;; disable auto previews inside my command
    :preview-key '(:debounce 0.4 any) ;; Option 1: Delay preview
-   ;; :preview-key (kbd "M-."))      ;; Option 2: Manual preview
+   ;; :preview-key "M-.")            ;; Option 2: Manual preview
 #+end_src
 
 In this case one may wonder what the difference is between using an Embark
@@ -480,9 +480,9 @@ UI experience.
   ;; Preview immediately on M-., on up/down after 0.5s, on any other key after 
1s
   (consult-customize consult-theme
                      :preview-key
-                     (list (kbd "M-.")
-                           :debounce 0.5 (kbd "<up>") (kbd "<down>")
-                           :debounce 1 'any))
+                     '("M-."
+                       :debounce 0.5 "<up>" "<down>"
+                       :debounce 1 any))
 #+end_src
 
 ** Narrowing and grouping
@@ -636,7 +636,7 @@ configure a manual preview as follows.
   (consult-customize
    consult--source-bookmark consult--source-file-register
    consult--source-recent-file consult--source-project-recent-file
-   :preview-key (kbd "M-."))
+   :preview-key "M-.")
 #+end_src
 
 Sources can be added directly to the =consult-buffer-source= list for 
convenience.
@@ -856,8 +856,8 @@ configuration examples.
     ;; Optionally configure preview. The default value
     ;; is 'any, such that any key triggers the preview.
     ;; (setq consult-preview-key 'any)
-    ;; (setq consult-preview-key (kbd "M-."))
-    ;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>")))
+    ;; (setq consult-preview-key "M-.")
+    ;; (setq consult-preview-key '("S-<down>" "S-<up>"))
     ;; For some commands and buffer sources it is useful to configure the
     ;; :preview-key on a per-command basis using the `consult-customize' macro.
     (consult-customize
@@ -866,12 +866,12 @@ configuration examples.
      consult-bookmark consult-recent-file consult-xref
      consult--source-bookmark consult--source-file-register
      consult--source-recent-file consult--source-project-recent-file
-     ;; :preview-key (kbd "M-.")
+     ;; :preview-key "M-."
      :preview-key '(:debounce 0.4 any))
 
     ;; Optionally configure the narrowing key.
     ;; Both < and C-+ work reasonably well.
-    (setq consult-narrow-key "<") ;; (kbd "C-+")
+    (setq consult-narrow-key "<") ;; "C-+"
 
     ;; Optionally make narrowing help available in the minibuffer.
     ;; You may want to use `embark-prefix-help-command' or which-key instead.
@@ -979,13 +979,13 @@ Useful options are:
    ;; Disable preview for `consult-theme' completely.
    consult-theme :preview-key nil
    ;; Set preview for `consult-buffer' to key `M-.'
-   consult-buffer :preview-key (kbd "M-.")
+   consult-buffer :preview-key "M-."
    ;; For `consult-line' change the prompt and specify multiple preview
    ;; keybindings. Note that you should bind <S-up> and <S-down> in the
    ;; `minibuffer-local-completion-map' or `vertico-map' to the commands which
    ;; select the previous or next candidate.
    consult-line :prompt "Search: "
-   :preview-key (list (kbd "<S-down>") (kbd "<S-up>")))
+   :preview-key '("S-<down>" "S-<up>"))
 #+end_src
 
 The configuration values are evaluated at runtime, just before the completion
diff --git a/consult.el b/consult.el
index ee80740c47..2dedec742c 100644
--- a/consult.el
+++ b/consult.el
@@ -71,20 +71,16 @@
 (defcustom consult-narrow-key nil
   "Prefix key for narrowing during completion.
 
-Good choices for this key are (kbd \"<\") or (kbd \"C-+\") for example.
-
-The key must be either a string or a vector.
-This is the key representation accepted by `define-key'."
-  :type '(choice key-sequence (const nil)))
+Good choices for this key are \"<\" and \"C-+\" for example. The
+key must be a string accepted by `key-valid-p'."
+  :type '(choice string (const nil)))
 
 (defcustom consult-widen-key nil
   "Key used for widening during completion.
 
 If this key is unset, defaults to twice the `consult-narrow-key'.
-
-The key must be either a string or a vector.
-This is the key representation accepted by `define-key'."
-  :type '(choice key-sequence (const nil)))
+The key must be a string accepted by `key-valid-p'."
+  :type '(choice string (const nil)))
 
 (defcustom consult-project-function
   #'consult--default-project-function
@@ -296,15 +292,17 @@ Can be either a string, or a list of strings or 
expressions."
   :type '(choice string (repeat (choice string expression))))
 
 (defcustom consult-preview-key 'any
-  "Preview trigger keys, can be nil, `any', a single key or a list of keys."
+  "Preview trigger keys, can be nil, `any', a single key or a list of keys.
+Debouncing can be specified via the `:debounce' attribute.  The
+individual keys must be strings accepted by `key-valid-p'."
   :type '(choice (const :tag "Any key" any)
                  (list :tag "Debounced"
                        (const :debounce)
                        (float :tag "Seconds" 0.1)
                        (const any))
                  (const :tag "No preview" nil)
-                 (key-sequence :tag "Key")
-                 (repeat :tag "List of keys" key-sequence)))
+                 (string :tag "Key")
+                 (repeat :tag "List of keys" string)))
 
 (defcustom consult-preview-max-size 10485760
   "Files larger than this byte limit are not previewed."
@@ -1520,7 +1518,13 @@ The result can be passed as :state argument to 
`consult--read'." type)
       (if (eq (car preview-key) :debounce)
           (setq debounce (cadr preview-key)
                 preview-key (cddr preview-key))
-        (push (cons (car preview-key) debounce) keys)
+        (let ((key (car preview-key)))
+          (unless (eq key 'any)
+            (if (key-valid-p key)
+                (setq key (key-parse key))
+              ;; TODO: Remove compatibility code, throw error.
+              (message "Invalid preview key: %S" key)))
+          (push (cons key debounce) keys))
         (pop preview-key)))
     keys))
 
@@ -1531,10 +1535,10 @@ The result can be passed as :state argument to 
`consult--read'." type)
   (let ((map (make-sparse-keymap))
         (keys (this-single-command-keys))
         any)
-    (dolist (x (consult--preview-key-normalize preview-key))
-      (if (eq (car x) 'any)
-          (setq any (cdr x))
-        (define-key map (car x) `(lambda () ,(cdr x)))))
+    (pcase-dolist (`(,k . ,d) (consult--preview-key-normalize preview-key))
+      (if (eq k 'any)
+          (setq any d)
+        (define-key map k `(lambda () ,d))))
     (setq keys (lookup-key map keys))
     (if (functionp keys) (funcall keys) any)))
 
@@ -1695,7 +1699,20 @@ invoked, the state function will also be called with 
`exit' and
 (defun consult--widen-key ()
   "Return widening key, if `consult-widen-key' is not set.
 The default is twice the `consult-narrow-key'."
-  (or consult-widen-key (and consult-narrow-key (vconcat consult-narrow-key 
consult-narrow-key))))
+  (cond
+   (consult-widen-key
+    (if (key-valid-p consult-widen-key)
+        (key-parse consult-widen-key)
+      ;; TODO: Remove compatibility code, throw error.
+      (message "Invalid `consult-widen-key': %S" consult-widen-key)
+      consult-widen-key))
+   (consult-narrow-key
+    (let ((key consult-narrow-key))
+      (if (key-valid-p key)
+          (setq key (key-parse key))
+        ;; TODO: Remove compatibility code, throw error.
+        (message "Invalid `consult-narrow-key': %S" key))
+      (vconcat key key)))))
 
 (defun consult-narrow (key)
   "Narrow current completion with KEY.
@@ -1767,12 +1784,15 @@ to make it available for commands with narrowing."
             consult--narrow-keys (plist-get settings :keys))
     (setq consult--narrow-predicate nil
           consult--narrow-keys settings))
-  (when consult-narrow-key
+  (when-let ((key consult-narrow-key))
+    (if (key-valid-p key)
+        (setq key (key-parse key))
+      ;; TODO: Remove compatibility code, throw error.
+      (message "Invalid `consult-narrow-key': %S" key))
     (dolist (pair consult--narrow-keys)
-      (define-key map
-        (vconcat consult-narrow-key (vector (car pair)))
-        (cons (cdr pair) #'consult-narrow))))
-  (when-let (widen (consult--widen-key))
+      (define-key map (vconcat key (vector (car pair)))
+                  (cons (cdr pair) #'consult-narrow))))
+  (when-let ((widen (consult--widen-key)))
     (define-key map widen (cons "All" #'consult-narrow))))
 
 ;; Emacs 28: hide in M-X