bug#60530: 28.2; Add tools to find keymaps that bind a given command

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Sean Devlin]

Hi folks,

There is a third-party package "helpful"
(https://github.com/Wilfred/helpful) that provides (in their words) "an
alternative to the built-in Emacs help that provides much more
contextual information".

One nice feature their describe-command replacement provides is a list
of bindings for the given command for all known keymaps. For example,
for find-file it might generate a list like the following:

ctl-x-map C-f
embark-become-file+buffer-map f
embark-file-map RET
embark-file-map f
global-map <open>
global-map C-x C-f
term-raw-map C-c C-f

(Obviously, it depends on what libraries are loaded when the command is
called.)

This is similar to where-is, but it provides a broader view of where the
command is bound. As far as I know, where-is only tells you about
bindings in active maps, and it doesn't tell you which maps contain the
bindings.

It's nice to know exactly which keymaps contain a binding. It gives you
a better idea of where best to tweak a configuration, and it can give
you new ideas about how and where a command might be used.

I looked in helpful.el, and they use some non-trivial logic to generate
their list. I think this functionality should come built-in with Emacs.

I think Emacs should provide low-level functions to generate a list of
bindings similar to the above and a command to describe the bindings. It
might also be nice to expose the information in describe-command like
helpful.el does.

Thanks!

In GNU Emacs 28.2
System Description:  macOS 13

Configured using:
'configure --with-ns '--enable-locallisppath=/Library/Application
Support/Emacs/${version}/site-lisp:/Library/Application
Support/Emacs/site-lisp' --with-modules'

Configured features:
ACL GMP GNUTLS JSON LIBXML2 MODULES NOTIFY KQUEUE NS PDUMPER THREADS
TOOLKIT_SCROLL_BARS ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
rfc822 mml mml-sec epa derived epg rfc6068 epg-config gnus-util rmail
rmail-loaddefs auth-source cl-seq eieio eieio-core cl-macs
eieio-loaddefs password-cache json map text-property-search time-date
subr-x seq byte-opt gv bytecomp byte-compile cconv mm-decode mm-bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader cl-loaddefs
cl-lib sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils
iso-transl tooltip eldoc paren electric uniquify ediff-hook vc-hooks
lisp-float-type elisp-mode mwheel term/ns-win ns-win ucs-normalize
mule-util term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice button
loaddefs faces cus-face macroexp files window text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote threads kqueue cocoa ns multi-tty
make-network-process emacs)

Memory information:
((conses 16 50747 7557)
(symbols 48 6552 1)
(strings 32 18281 2303)
(string-bytes 1 632125)
(vectors 16 13822)
(vector-slots 8 191476 12084)
(floats 8 21 38)
(intervals 56 202 0)
(buffers 992 10))

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Sean Devlin <spd@toadstyle.org> writes:

> Hi folks,
>
> There is a third-party package "helpful"
> (https://github.com/Wilfred/helpful) that provides (in their words) "an
> alternative to the built-in Emacs help that provides much more
> contextual information".
>
> One nice feature their describe-command replacement provides is a list
> of bindings for the given command for all known keymaps. For example,
> for find-file it might generate a list like the following:
>
> ctl-x-map C-f
> embark-become-file+buffer-map f
> embark-file-map RET
> embark-file-map f
> global-map <open>
> global-map C-x C-f
> term-raw-map C-c C-f
>
> [...]
>
> It's nice to know exactly which keymaps contain a binding. It gives you
> a better idea of where best to tweak a configuration, and it can give
> you new ideas about how and where a command might be used.

I saw this message long ago, but recently I came across a situation
where I wanted to know if a command was bound in *some* keymap whose
name I didn't know, and this would be quite a helpful feature for me
personally (pun intended).

> I looked in helpful.el, and they use some non-trivial logic to generate
> their list. I think this functionality should come built-in with Emacs.

Looking in their source, I think (with some handwaving) the logic boils
down to iterating over all keymap objects inside `obarray', and checking
whether the command of interest is actively bound (that is, not
shadowed, etc) in each keymap.  Some other things are happening inside
helpful.el as well, probably regarding other components in the helpful
buffer.

> I think Emacs should provide low-level functions to generate a list of
> bindings similar to the above and a command to describe the bindings. It
> might also be nice to expose the information in describe-command like
> helpful.el does.

If there is interest, maybe I can take a look inside help-fns.el and see
if I can figure out how to add new contents in the *Help* buffer, and
then try to come up with a patchset, with the goal of (correctly and)
concisely implement command-keymap lookups without depending on dash and
f.  This might take a while, though, as some other things of mine are
prioritized over coding ATM.

In addition, this feature probably needs to be guarded behind a boolean
defcustom flag so that people who don't want this addition don't pay for
the cost.

Thoughts?

--
Best,


RY

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Eli Zaretskii]

> Cc: 60530@debbugs.gnu.org
> Date: Mon, 20 Feb 2023 15:07:09 +0800
> From:  Ruijie Yu via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> I saw this message long ago, but recently I came across a situation
> where I wanted to know if a command was bound in *some* keymap whose
> name I didn't know, and this would be quite a helpful feature for me
> personally (pun intended).

Isn't that what where-is and/or where-is-internal already do?

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: 60530@debbugs.gnu.org
>> Date: Mon, 20 Feb 2023 15:07:09 +0800
>> From:  Ruijie Yu via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>
>> I saw this message long ago, but recently I came across a situation
>> where I wanted to know if a command was bound in *some* keymap whose
>> name I didn't know, and this would be quite a helpful feature for me
>> personally (pun intended).
>
> Isn't that what where-is and/or where-is-internal already do?

No, not quite.  The functions where-is{,-internal} only look for
*currently active keymaps*, whereas my intention was to look for all
keybinds for the specified command, be it active or not.

The following is my reason to want this feature.  I use pyim, an input
method that shows candidate words in a small frame (which I believe is
called posframe?), which has `pyim-mode-map' enabled.  Then, while
typing, I want to know how to call the `pyim-next-page' command without
going into pyim source.

If I type M-x where-is, this frame disappears, and I am dropped back
into the editing buffer, which does not have `pyim-mode-map' enabled.
Hence, `where-is' does not show anything bound for `pyim-next-page',
because it indeed is not bound globally.  FTR, C-h b does not work
either.

Similar situations can occur in other popup behaviors with temporary
keybinds, such as lsp-ui package (github.com/emacs-lsp/lsp-ui).

--
Best,


RY

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Eli Zaretskii]

> From: Ruijie Yu <ruijie@netyu.xyz>
> Cc: spd@toadstyle.org, 60530@debbugs.gnu.org
> Date: Mon, 20 Feb 2023 20:01:27 +0800
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Cc: 60530@debbugs.gnu.org
> >> Date: Mon, 20 Feb 2023 15:07:09 +0800
> >> From:  Ruijie Yu via "Bug reports for GNU Emacs,
> >>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >>
> >> I saw this message long ago, but recently I came across a situation
> >> where I wanted to know if a command was bound in *some* keymap whose
> >> name I didn't know, and this would be quite a helpful feature for me
> >> personally (pun intended).
> >
> > Isn't that what where-is and/or where-is-internal already do?
> 
> No, not quite.  The functions where-is{,-internal} only look for
> *currently active keymaps*, whereas my intention was to look for all
> keybinds for the specified command, be it active or not.

But that's impossible in principle, because loading some package could
produce a binding for a command, and you don't know which packages
will be loaded into a session before they are actually loaded.

Or what am I missing?

> The following is my reason to want this feature.  I use pyim, an input
> method that shows candidate words in a small frame (which I believe is
> called posframe?), which has `pyim-mode-map' enabled.  Then, while
> typing, I want to know how to call the `pyim-next-page' command without
> going into pyim source.
> 
> If I type M-x where-is, this frame disappears, and I am dropped back
> into the editing buffer, which does not have `pyim-mode-map' enabled.
> Hence, `where-is' does not show anything bound for `pyim-next-page',
> because it indeed is not bound globally.  FTR, C-h b does not work
> either.

If what where-is does doesn't suit your needs for reasons of its UI or
how it switches buffers, you could extract (parts of) its code and
make a similar function which presents the results in a way that
doesn't interrupt your workflow.  My point in mentioning the existing
commands is that they already show how to find bindings for an
arbitrary command, so you could reuse some or all of that code for
your purposes (which sound very similar to me).

bug#60530: 28.2; Add tools to find keymaps that bind a given command

[Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Ruijie Yu <ruijie@netyu.xyz>
>> Cc: spd@toadstyle.org, 60530@debbugs.gnu.org
>> Date: Mon, 20 Feb 2023 20:01:27 +0800
>>
>>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> >> Cc: 60530@debbugs.gnu.org
>> >> Date: Mon, 20 Feb 2023 15:07:09 +0800
>> >> From:  Ruijie Yu via "Bug reports for GNU Emacs,
>> >>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> >>
>> >> I saw this message long ago, but recently I came across a situation
>> >> where I wanted to know if a command was bound in *some* keymap whose
>> >> name I didn't know, and this would be quite a helpful feature for me
>> >> personally (pun intended).
>> >
>> > Isn't that what where-is and/or where-is-internal already do?
>>
>> No, not quite.  The functions where-is{,-internal} only look for
>> *currently active keymaps*, whereas my intention was to look for all
>> keybinds for the specified command, be it active or not.
>
> But that's impossible in principle, because loading some package could
> produce a binding for a command, and you don't know which packages
> will be loaded into a session before they are actually loaded.
>
> Or what am I missing?

My idea is to only use the "current state" (whatever that might mean)
for searching for keybinds, and that criterion should exclude things
like autoload, as the key isn't bound until the package is properly
loaded.

So IMO, the only difference between `where-is' and this new function
would be this: instead of looking for active keymaps, the new function
looks for all existing (named) keymaps from `obarray' -- and do the same
action of scanning over the list of keymaps and figure out what
information to show to the user.

But anyways, this can absolutely be simply user-local code, and doesn't
have to live inside emacs.git.

>> The following is my reason to want this feature.  I use pyim, an input
>> method that shows candidate words in a small frame (which I believe is
>> called posframe?), which has `pyim-mode-map' enabled.  Then, while
>> typing, I want to know how to call the `pyim-next-page' command without
>> going into pyim source.
>>
>> If I type M-x where-is, this frame disappears, and I am dropped back
>> into the editing buffer, which does not have `pyim-mode-map' enabled.
>> Hence, `where-is' does not show anything bound for `pyim-next-page',
>> because it indeed is not bound globally.  FTR, C-h b does not work
>> either.
>
> If what where-is does doesn't suit your needs for reasons of its UI or
> how it switches buffers, you could extract (parts of) its code and
> make a similar function which presents the results in a way that
> doesn't interrupt your workflow.  My point in mentioning the existing
> commands is that they already show how to find bindings for an
> arbitrary command, so you could reuse some or all of that code for
> your purposes (which sound very similar to me).

I understand and agree.  See above for further comments.

--
Best,


RY