branch: externals/transient
commit c4e0cba65663b0a2dacd8531e779f2c09f778267
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Require all key bindings to be specified as key descriptions
No longer support vectors. This change isn't backward compatible but
I haven't seen a vector being used even just once.
It also makes sense to take inspiration from `keymap-set' et al., which
didn't exist when Transient was created.
However, we continue to be more permissive than those functions, only
insisting on strings understood by `kbd', including strings that do not
satisfy `key-valid-p'. Being more permissive makes it possible, for
example, to write the key binding, which toggles the "-a" command line
argument, as "-a", instead of having to write "- a". Likewise
additional spaces can be added, which are not removed when displaying
the binding in the menu, which is useful for alignment purposes.
---
docs/transient.org | 30 +++++++++++++++++++++++-------
lisp/transient.el | 23 ++++++++---------------
2 files changed, 31 insertions(+), 22 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index 7e74bcc79e..5aa56bb758 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -875,11 +875,11 @@ The following functions share a few arguments:
{{{var(SUFFIX)}}} may also be a group in the same form as expected by
~transient-define-prefix~. See [[*Group Specifications]].
-- {{{var(LOC)}}} is a command, a key vector, a key description (a string as
- returned by ~key-description~), or a list specifying coordinates (the
- last element may also be a command or key). For example ~(1 0 -1)~
- identifies the last suffix (~-1~) of the first subgroup (~0~) of the
- second group (~1~).
+- {{{var(LOC)}}} is a command, a key description (a string as returned by
+ ~key-description~ and understood by ~kbd~), or a list specifying
+ coordinates (the last element may also be a command or key). For
+ example ~(1 0 -1)~ identifies the last suffix (~-1~) of the first
+ subgroup (~0~) of the second group (~1~).
If {{{var(LOC)}}} is a list of coordinates, then it can be used to identify a
group, not just an individual suffix command.
@@ -1285,7 +1285,15 @@ the object's values just for the binding inside this
transient.
- {{{var(LEVEL)}}} is the suffix level, an integer between 1 and 7. See
[[*Enabling and Disabling Suffixes]].
-- {{{var(KEY)}}} is the key binding, either a vector or key description string.
+- KEY is the key binding, a string in the format returned by
+ ~describe-key~ and understood by ~kbd~.
+
+ That format is more permissive than the one accepted by ~key-valid-p~.
+ Being more permissive makes it possible, for example, to write the
+ key binding, which toggles the ~-a~ command line argument, as "-a",
+ instead of having to write "- a". Likewise additional spaces can be
+ added, which is not removed when displaying the binding in the menu,
+ which is useful for alignment purposes.
- {{{var(DESCRIPTION)}}} is the description, either a string or a function that
takes zero or one arguments (the suffix object) and returns a string.
@@ -2410,7 +2418,15 @@ and ~advice*~ slots (see [[*Slots of
~transient-suffix~]]) are defined.
:UNNUMBERED: notoc
:END:
-- ~key~ The key, a key vector or a key description string.
+- ~key~ is the key binding, a string in the format returned by
+ ~describe-key~ and understood by ~kbd~.
+
+ That format is more permissive than the one accepted by ~key-valid-p~.
+ Being more permissive makes it possible, for example, to write the
+ key binding, which toggles the ~-a~ command line argument, as "-a",
+ instead of having to write "- a". Likewise additional spaces can be
+ added, which is not removed when displaying the binding in the menu,
+ which is useful for alignment purposes.
- ~command~ The command, a symbol.
diff --git a/lisp/transient.el b/lisp/transient.el
index ea13f1a697..df46384562 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -1604,8 +1604,10 @@ See info node `(transient)Modifying Existing
Transients'."
(setq val nil))
(setq val (if loc (car mem) mem)))))
(setq loc (car loc)))
+ (when (stringp loc)
+ (setq loc (kbd loc)))
(if loc
- (transient--layout-member-1 (transient--kbd loc) val remove)
+ (transient--layout-member-1 loc val remove)
val)))
(defun transient--layout-member-1 (loc layout remove)
@@ -1629,19 +1631,11 @@ See info node `(transient)Modifying Existing
Transients'."
(cmd (plist-get def :command)))
(if (symbolp loc)
(eq cmd loc)
- (equal (transient--kbd
- (or (plist-get def :key)
- (transient--command-key cmd)))
+ (equal (kbd (or (plist-get def :key)
+ (transient--command-key cmd)))
loc)))))
(aref group 3)))
-(defun transient--kbd (keys)
- (when (vectorp keys)
- (setq keys (key-description keys)))
- (when (stringp keys)
- (setq keys (kbd keys)))
- keys)
-
(defun transient--spec-key (spec)
(let ((plist (nth 2 spec)))
(or (plist-get plist :key)
@@ -1894,9 +1888,8 @@ probably use this instead:
((length= suffixes 1)
(car suffixes))
((cl-find-if (lambda (obj)
- (equal
- (listify-key-sequence (transient--kbd (oref obj key)))
- (listify-key-sequence (this-command-keys))))
+ (equal (listify-key-sequence (kbd (oref obj key)))
+ (listify-key-sequence (this-command-keys))))
suffixes))
;; COMMAND is only provided if `this-command' is meaningless, in
;; which case `this-command-keys' is also meaningless, making it
@@ -2425,7 +2418,7 @@ value. Otherwise return CHILDREN as is.")
(pcase-let* ((`(,level ,class ,args) spec)
(cmd (plist-get args :command))
(_ (transient--load-command-if-autoload cmd))
- (key (transient--kbd (plist-get args :key)))
+ (key (kbd (plist-get args :key)))
(proto (and cmd (transient--suffix-prototype cmd)))
(level (or (alist-get (cons cmd key) levels nil nil #'equal)
(alist-get cmd levels)
