The new keymap functions

The new keymap functions

[Lars Ingebrigtsen]

As previously discussed, we wanted to add make the Emacs key binding
machinery easier to understand, and go for a single syntax for bindings.
This entails adding a bunch of new functions, since the old functions
should continue to work as before.

The most difficult thing here is naming, of course, but after much
discussion, I've settled on these:

keymap-set
keymap-local-set
keymap-global-set
keymap-local-unset
keymap-global-unset
keymap-lookup

define-keymap and defvar-keymap keep their names, but use the
`kbd-valid-p' syntax.  In addition, `kbd' has been refactored, and the
new name `key-parse' has been defined -- which is like `kbd', but always
returns a vector.

Finally, the -unset functions remove the bindings instead of setting
them to nil.

I've added the functions and converted the few define-keymap instances
that are in-tree to the new syntax, but wanted to give all y'all a
chance to discuss this further for a couple of days before I push these
changes.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The most difficult thing here is naming, of course, but after much
> discussion, I've settled on these:
>
> keymap-set
> keymap-local-set
> keymap-global-set
> keymap-local-unset
> keymap-global-unset
> keymap-lookup

Sounds good to me.  Is there a need for a 'keymap-unset'?

Re: The new keymap functions

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Sounds good to me.  Is there a need for a 'keymap-unset'?

Yes, I forgot to mention it -- the other -unset functions use it.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Joost Kremers]

On Sat, Nov 13 2021, Lars Ingebrigtsen wrote:
> The most difficult thing here is naming, of course, but after much
> discussion, I've settled on these:
>
> keymap-set
> keymap-local-set
> keymap-global-set
> keymap-local-unset
> keymap-global-unset
> keymap-lookup
[...]
> Finally, the -unset functions remove the bindings instead of setting
> them to nil.

If they do something different from what `local-unset-key` and
`global-unset-key` do, would it perhaps be useful to name them differently as
well? Perhaps `unbind` instead of `unset`?

-- 
Joost Kremers
Life has its moments

Re: The new keymap functions

[Lars Ingebrigtsen]

Joost Kremers <joostkremers@fastmail.fm> writes:

> If they do something different from what `local-unset-key` and
> `global-unset-key` do, would it perhaps be useful to name them differently as
> well? Perhaps `unbind` instead of `unset`?

Or -remove, perhaps?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Stefan Monnier]

> Finally, the -unset functions remove the bindings instead of setting
> them to nil.

I hope you do that by changing the C code of `define-key`, because doing
it right from outside of it is hard (see recent discussion about it).


        Stefan

Re: The new keymap functions

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I hope you do that by changing the C code of `define-key`, because doing
> it right from outside of it is hard (see recent discussion about it).

I missed that bit of the discussion (I only saw the first bugfix post):

> Actually, it's not guaranteed.  Try it with:
> 
>     (let ((parent (make-sparse-keymap))
>           (child (make-keymap)))
>       (set-keymap-parent child parent)
>       (define-key parent [?a] nil)
>       (define-key child  [?a] 'bar)
>       child)

So the function as posted didn't work in that case...  hm...  yes, I
guess it has to be done in C.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I've added the functions and converted the few define-keymap instances
> that are in-tree to the new syntax, but wanted to give all y'all a
> chance to discuss this further for a couple of days before I push these
> changes.

I've been going through the Emacs and lispref manuals, adjusting them to
the new functions.  I've moved the documentation of the central
functions like `define-keymap' and the description of all the different
syntaxes to a new node that documents these "legacy" functions, but the
manuals otherwise only talk about the new functions.

The good news is that this makes all of these bits go away:

 For example,
 
 @smallexample
-(global-set-key (kbd "C-x C-\\") 'next-line)
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key [?\C-x ?\C-\\] 'next-line)
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key [(control ?x) (control ?\\)] 'next-line)
+(keymap-global-set "C-x C-\\" 'next-line)
 @end smallexample

as well as all the stuff that patiently describe the non-intuitive
difference/similarity between (global-set-key "á") and (global-set-key
"\M-a"), which is mostly irrelevant with the new functions.

The bad news is that during this work, I've discovered a few more
functions that need to have keymap-* equivalents, like

keymap-substitute
keymap-binding
keymap-local-binding
keymap-global-binding

so it's a bit...  er...  more than originally planned.  But it's not bad
bad -- we get a more consistent naming scheme here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Phil Sainty]

On 2021-11-13 19:56, Lars Ingebrigtsen wrote:
> The most difficult thing here is naming, of course, but after
> much discussion, I've settled on these:
> 
> keymap-set
> keymap-local-set
> keymap-global-set
> keymap-unset
> keymap-local-unset
> keymap-global-unset


Any particular argument against putting the global/local last?

keymap-set
keymap-set-local
keymap-set-global
keymap-unset
keymap-unset-local
keymap-unset-global

I haven't pondered it enough to be opinionated, but I feel like
there's some benefits to having common naming prefixes regardless
of the keymap component.  I suspect you already considered this,
and chose to go the other way?


-Phil

Re: The new keymap functions

[Lars Ingebrigtsen]

Phil Sainty <psainty@orcon.net.nz> writes:

> Any particular argument against putting the global/local last?

The trend is to pile up the nouns at the start and then have the verb at
the end when naming things these days.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 14 Nov 2021 06:14:57 +0100
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> Phil Sainty <psainty@orcon.net.nz> writes:
> 
> > Any particular argument against putting the global/local last?
> 
> The trend is to pile up the nouns at the start and then have the verb at
> the end when naming things these days.

FWIW, keymap-set-local sounds better to me than keymap-local-set.

Re: The new keymap functions

[Yuri Khan]

On Sun, 14 Nov 2021 at 12:16, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> > Any particular argument against putting the global/local last?
>
> The trend is to pile up the nouns at the start and then have the verb at
> the end when naming things these days.

-local/-global act as adverbs here though.

Re: The new keymap functions

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> FWIW, keymap-set-local sounds better to me than keymap-local-set.

I don't really have a strong opinion here, but the -set/-unset
variations seemed to be the most popular ones when this was discussed a
few weeks back.

And it does allow for a neater grouping if you're looking for the
commands that operate on the global/local/general bindings:

keymap-global-binding
keymap-global-set
keymap-global-unset

etc.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> keymap-global-binding

Speaking of which...  that should perhaps be keymap-global-lookup for
symmetry, but we currently have both lookup-key, key-binding and
global-key-binding/local-key-binding.

Do we need equivalents for both lookup-key and key-binding?
keymap-lookup with a nil KEYMAP could work the way key-binding works, so
then we'd have

keymap-lookup         = (both the current lookup-key/key-binding)
keymap-global-lookup  = global-key-binding
keymap-local-lookup   = local-key-binding

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The most difficult thing here is naming, of course, but after much
  > discussion, I've settled on these:

  > keymap-set
  > keymap-local-set
  > keymap-global-set
  > keymap-local-unset
  > keymap-global-unset
  > keymap-lookup

How about replacing `keymap' with `key'?  After all, they don't set or
unset (the binding of) a keymap, they set or unset a single key?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: The new keymap functions

[Lars Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

>   > keymap-set
>   > keymap-local-set
>   > keymap-global-set
>   > keymap-local-unset
>   > keymap-global-unset
>   > keymap-lookup
>
> How about replacing `keymap' with `key'?  After all, they don't set or
> unset (the binding of) a keymap, they set or unset a single key?

These functions modify a keymap.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Dmitry Gutov]

On 13.11.2021 15:07, Lars Ingebrigtsen wrote:
> Joost Kremers<joostkremers@fastmail.fm>  writes:
> 
>> If they do something different from what `local-unset-key` and
>> `global-unset-key` do, would it perhaps be useful to name them differently as
>> well? Perhaps `unbind` instead of `unset`?
> Or -remove, perhaps?

And for symmetry with 'remove', we could use 'put' instead of 'set'.

It would sound more like working with a hashmap/hashtable (which a 
keymap is, in a sense).

Re: The new keymap functions

[Lars Ingebrigtsen]

Dmitry Gutov <dgutov@yandex.ru> writes:

>>> If they do something different from what `local-unset-key` and
>>> `global-unset-key` do, would it perhaps be useful to name them
>>> differently as
>>> well? Perhaps `unbind` instead of `unset`?
>> Or -remove, perhaps?

I've decided to keep the old semantics, so -unset is more correct.  (But
removal will be an option:

(defun keymap-local-unset (key &optional remove)
...
  (interactive
   (list (key-description (read-key-sequence "Unset key locally: "))
         current-prefix-arg))

> And for symmetry with 'remove', we could use 'put' instead of 'set'.
>
> It would sound more like working with a hashmap/hashtable (which a
> keymap is, in a sense).

It makes sense, but it feels a bit too...  technical.

Anyway, I think I'm just about ready to push the changes to the trunk,
and I'll do so tomorrow.  The changes to the manuals is still a work in
progress, but it'll take a few more sweeps over the manual to see what
needs to remain and what should be edited out (especially concerning the
many key syntaxes, which we want to de-emphasise, but still keep), and I
think it makes more sense to hold off on doing that until we've got more
experience with the new functions.  (But I think the main work has been
done in the manuals, too.)

After pushing the changes, you'll all have to say "make bootstrap" (or
remove all the .elc files first) because of the changes to the syntax
in `defvar-keymap'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I wrote:

  >   > keymap-set
  >   > keymap-local-set
  >   > keymap-global-set
  >   > keymap-local-unset
  >   > keymap-global-unset
  >   > keymap-lookup

  > How about replacing `keymap' with `key'?  After all, they don't set or
  > unset (the binding of) a keymap, they set or unset a single key?

More correctly, they operate on the binding of a key sequence, not a
single key.  But my suggestion remains the same.  We can shorten "key
sequence" to "key" in a context like this.

The word "map" doesn't seem to contribute anything.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: The new keymap functions

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> After pushing the changes, you'll all have to say "make bootstrap" (or
> remove all the .elc files first) because of the changes to the syntax
> in `defvar-keymap'.

I've now pushed the changes, but it doesn't look like you have to say
"make bootstrap" after all.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

> More correctly, they operate on the binding of a key sequence, not a
> single key.  But my suggestion remains the same.  We can shorten "key
> sequence" to "key" in a context like this.
>
> The word "map" doesn't seem to contribute anything.

Like I said before -- all these functions destructively modify a keymap,
so having "keymap" emphasised in these functions makes sense to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Tue, 16 Nov 2021 08:28:10 +0100
> Cc: Joost Kremers <joostkremers@fastmail.fm>, emacs-devel@gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > After pushing the changes, you'll all have to say "make bootstrap" (or
> > remove all the .elc files first) because of the changes to the syntax
> > in `defvar-keymap'.
> 
> I've now pushed the changes, but it doesn't look like you have to say
> "make bootstrap" after all.

The changes to the ELisp manual completely removed the documentation
of global-set-key and other "legacy" functions, AFAICT.  I don't think
we can do that: the code which uses those will remain with us for the
years to come, and Lisp programmers should be able to read and
understand what these functions do.  It is okay to say "don't use
those in new code" (as you already did say), but we should put back
the documentation of those few functions.  There aren't too many of
them, and their documentation is quite short, so it isn't a big deal
to have them in the manual.

Re: The new keymap functions

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> The changes to the ELisp manual completely removed the documentation
> of global-set-key and other "legacy" functions, AFAICT.  I don't think
> we can do that: the code which uses those will remain with us for the
> years to come, and Lisp programmers should be able to read and
> understand what these functions do.  It is okay to say "don't use
> those in new code" (as you already did say), but we should put back
> the documentation of those few functions.  There aren't too many of
> them, and their documentation is quite short, so it isn't a big deal
> to have them in the manual.

They are still in the lispref manual (and indexed, if I didn't mess that
up), so people should be able to find them.  However, they just point to
the new functions -- which have the same call signature and semantics
(except for one function), which is why I didn't think it was worth
talking more about them in the manual.  The documentation of the new
function (along with the doc strings) seems sufficient to me.

A manual is primarily for people who are writing new code, not for
rooting out how legacy functions work.  The built-in doc system is
better for that.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: dgutov@yandex.ru,  joostkremers@fastmail.fm,  emacs-devel@gnu.org
> Date: Tue, 16 Nov 2021 15:24:09 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The changes to the ELisp manual completely removed the documentation
> > of global-set-key and other "legacy" functions, AFAICT.  I don't think
> > we can do that: the code which uses those will remain with us for the
> > years to come, and Lisp programmers should be able to read and
> > understand what these functions do.  It is okay to say "don't use
> > those in new code" (as you already did say), but we should put back
> > the documentation of those few functions.  There aren't too many of
> > them, and their documentation is quite short, so it isn't a big deal
> > to have them in the manual.
> 
> They are still in the lispref manual (and indexed, if I didn't mess that
> up), so people should be able to find them.

The names are there, but not the signatures, and there isn't even a
minimal description of the arguments.  That is too radical, IMO.

> A manual is primarily for people who are writing new code, not for
> rooting out how legacy functions work.

The manual is also for people who want to understand what the code
they look at does.

> The built-in doc system is better for that.

Then why do we have the ELisp manual at all?

I'm really unhappy about deleting that from the manual.  Would you
mind if I added back some minimal docs?

Re: The new keymap functions

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Then why do we have the ELisp manual at all?

For people to read to when they want to write code?

> I'm really unhappy about deleting that from the manual.  Would you
> mind if I added back some minimal docs?

To the Low-Level Key Binding section?  No, go ahead.

Like I said earlier, the manual needs to be gone over a couple of times
to see what we should alter and what we should keep, but I thought we
should wait a couple of weeks to see where we're at (after getting some
feedback).  (There's a lot of discussion about key bindings in various
different sections.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

RE: [External] : Re: The new keymap functions

[Drew Adams]

> I wrote:
>   >   > keymap-set
>   >   > keymap-local-set
>   >   > keymap-global-set
>   >   > keymap-local-unset
>   >   > keymap-global-unset
>   >   > keymap-lookup
>   > How about replacing `keymap' with `key'?  After all,
>   > they don't set or unset (the binding of) a keymap,
>   > they set or unset a single key?
> 
> More correctly, they operate on the binding of a key sequence, not a
> single key.  But my suggestion remains the same.  We can shorten "key
> sequence" to "key" in a context like this.
> 
> The word "map" doesn't seem to contribute anything.

I agree (and said the same thing).

RE: [External] : Re: The new keymap functions

[Drew Adams]

> > The word "map" doesn't seem to contribute anything.
> 
> Like I said before -- all these functions destructively modify a keymap,
> so having "keymap" emphasised in these functions makes sense to me.

`define-key' also changes a keymap.  We don't call it
`keymap-update', for a reason.  It's about defining a
key sequence.  Users think first and foremost in terms
of defining/setting/specifying/describing keys.  They
think about keymaps only when they have to, and as
"containers" for keys (key sequences).

Re: The new keymap functions

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: dgutov@yandex.ru,  joostkremers@fastmail.fm,  emacs-devel@gnu.org
> Date: Tue, 16 Nov 2021 16:19:14 +0100
> 
> > I'm really unhappy about deleting that from the manual.  Would you
> > mind if I added back some minimal docs?
> 
> To the Low-Level Key Binding section?  No, go ahead.

Done.

Note that some of the @defun's I added are copies of those we have in
other places; I assume that they will be removed from those other
places in due time.

Re: The new keymap functions

[Juri Linkov]

> keymap-set
> keymap-local-set
> keymap-global-set
> keymap-local-unset
> keymap-global-unset
> keymap-lookup
>
> define-keymap and defvar-keymap keep their names, but use the
> `kbd-valid-p' syntax.

Whereas the name `defvar-keymap' is nice since it's a top-level macro,
`define-keymap' looks out of place in the same group of functions.
And indeed, such mismatch looks odd:

  (define-keymap "C-c C-c" #'quit-buffer)
  (keymap-set map "C-c C-c" #'quit-buffer)

What about renaming it to `keymap-define'?  Then:

  (keymap-define "C-c C-c" #'quit-buffer)
  (keymap-set map "C-c C-c" #'quit-buffer)

Re: The new keymap functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   (define-keymap "C-c C-c" #'quit-buffer)
  >   (keymap-set map "C-c C-c" #'quit-buffer)

  > What about renaming it to `keymap-define'?  Then:

Definition constructs should have names that start with `def'.
It's a general convention, and following it provides regularity.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: The new keymap functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Like I said before -- all these functions destructively modify a keymap,

That is true, but what users think of operating on is a key sequence,
not the keymap.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: The new keymap functions

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Note that some of the @defun's I added are copies of those we have in
> other places; I assume that they will be removed from those other
> places in due time.

Probably; I intend to go over the manuals in a couple of weeks and make
adjustments.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Whereas the name `defvar-keymap' is nice since it's a top-level macro,
> `define-keymap' looks out of place in the same group of functions.
> And indeed, such mismatch looks odd:
>
>   (define-keymap "C-c C-c" #'quit-buffer)
>   (keymap-set map "C-c C-c" #'quit-buffer)
>
> What about renaming it to `keymap-define'?  Then:
>
>   (keymap-define "C-c C-c" #'quit-buffer)
>   (keymap-set map "C-c C-c" #'quit-buffer)

I like that all the `keymap-*' functions take a map as the first
parameter (except the commands that have the map "in the name", like
`keymap-global-set').  And using `define-*' for a form that defines
something (and has a (potentially) long body) is a very long-standing
tradition in Emacs, so I'd prefer to keep it as is.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

>   > Like I said before -- all these functions destructively modify a keymap,
>
> That is true, but what users think of operating on is a key sequence,
> not the keymap.

Perhaps they think that because we've called the functions stuff like
`define-key'.  (Which we're now not doing.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Juri Linkov]

>> What about renaming it to `keymap-define'?  Then:
>>
>>   (keymap-define "C-c C-c" #'quit-buffer)
>>   (keymap-set map "C-c C-c" #'quit-buffer)
>
> I like that all the `keymap-*' functions take a map as the first
> parameter (except the commands that have the map "in the name", like
> `keymap-global-set').  And using `define-*' for a form that defines
> something (and has a (potentially) long body) is a very long-standing
> tradition in Emacs, so I'd prefer to keep it as is.

This is fine.  I see that `define-key' avoids this dilemma
by removing `define-' in its replacement `keymap-set' 🙃

The reason why I'm asking this is to know how the corresponding
function/macro for repeat-mode should be named in master.
And it seems `define-repeat-map' would be the right name.

Re: The new keymap functions

[Robert Pluim]

>>>>> On Wed, 17 Nov 2021 10:10:40 +0200, Juri Linkov <juri@linkov.net> said:
    Juri> The reason why I'm asking this is to know how the corresponding
    Juri> function/macro for repeat-mode should be named in master.
    Juri> And it seems `define-repeat-map' would be the right name.

Are you sure you need a `define-repeat-map'? Just adding a :repeat
keyword to `defvar-keymap' would be enough. I might even have a patch
lying around somewhere :-)

Robert
-- 

RE: [External] : Re: The new keymap functions

[Drew Adams]

>>> Like I said before -- all these functions
>>> destructively modify a keymap,

Is "destructively" important here?  If you
intend to make the same argument without it,
then you should maybe drop it, for clarity.

Otherwise, in the future someone wanting to be
faithful to this `Lars Doctrine' may think or
claim that it applies _only_ when destructively
modifying.  (Or is that what you mean/want?)

You should be clear about what you're setting
down in your new tablets of stone.
___

>> That is true, but what users think of operating
>> on is a key sequence, not the keymap.
> 
> Perhaps they think that because we've called the
> functions stuff like `define-key'.  (Which we're
> now not doing.)

Perhaps.  But perhaps not only for that reason.

They think that because that's what the operation
does.

Users are primarily concerned with _keys_, not
keymaps, if only (but not only) because most user
settings of keys are in the global map.

Knowing about different keymaps and having a need
to change a map other than `global-map' is not in
the first approximation view of an Emacs user.

And rightfully so.  We have, and manipulate,
multiple keymaps _not for their own sake_, but to
_organize key bindings_.
___

But if you're really set on doing this then you
should, I think, be consistent with what we do
currently, and have always done, with other
objects that have parts/attributes:

we use the name `set-<object>-<part>', not
`<object>-set-<part>'.

Consider:

set-buffer-*
set-case-*
set-char-table-*
set-coding-*
set-cursor-*
set-display-table-*
set-face-*
set-file-*
set-font-*
set-frame-*
set-fringe-*
set-input-*
set-justification-*
set-keyboard-coding-*
set-language-*
set-marker-*
set-mouse-*
set-process-*
set-shell-*
set-terminal-*
set-window-*

Not only that, but names matching `.*-set-',
that is, with some name part before `set',
typically have, as the part that precedes
`set', a library prefix or a language prefix,
not an object/type name.

There are relatively few exceptions, where an
object name precedes `set'.  And even in those
cases the object name can usually be seen to
also be a library prefix.

With your preference of emphasizing the keymap,
setting a key binding in a given keymap should,
in keeping with our convention, be called
something like `set-keymap-binding'.

You're instead creating more inconsistency, it
seems.

Please take a look at existing names, and I
think you'll see that I'm right.  They follow
a pattern, and it ain't the pattern you're
trying to follow now.
___

Oh, and I don't find any existing `unset-*'
functions (i.e., names starting with `unset').
The only unsetting functions I see are the
`*-unset-key' functions.

You could think of those as almost starting
with `unset', as the part that precedes it is
just local|global.  But again, nothing like
using the prefix `keymap-'.

Unsetting has traditionally been seen and
handled as just a particular kind of setting,
AFAICT.

Re: The new keymap functions

[Juri Linkov]

>>>>>> On Wed, 17 Nov 2021 10:10:40 +0200, Juri Linkov <juri@linkov.net> said:
>     Juri> The reason why I'm asking this is to know how the corresponding
>     Juri> function/macro for repeat-mode should be named in master.
>     Juri> And it seems `define-repeat-map' would be the right name.
>
> Are you sure you need a `define-repeat-map'? Just adding a :repeat
> keyword to `defvar-keymap' would be enough. I might even have a patch
> lying around somewhere :-)

But this macro should put a special property to all commands bound
to repeatable keys.  This means that `defvar-keymap' should include
special-handling of repeatable commands.

Re: The new keymap functions

[Bob Rogers]

   From: Lars Ingebrigtsen <larsi@gnus.org>
   Date: Wed, 17 Nov 2021 08:36:23 +0100

   Juri Linkov <juri@linkov.net> writes:

   > Whereas the name `defvar-keymap' is nice since it's a top-level macro,
   > `define-keymap' looks out of place in the same group of functions.
   > And indeed, such mismatch looks odd:
   >
   >   (define-keymap "C-c C-c" #'quit-buffer)
   >   (keymap-set map "C-c C-c" #'quit-buffer)
   >
   > What about renaming it to `keymap-define'?  Then:
   >
   >   (keymap-define "C-c C-c" #'quit-buffer)
   >   (keymap-set map "C-c C-c" #'quit-buffer)

   I like that all the `keymap-*' functions take a map as the first
   parameter (except the commands that have the map "in the name", like
   `keymap-global-set').  And using `define-*' for a form that defines
   something (and has a (potentially) long body) is a very long-standing
   tradition in Emacs, so I'd prefer to keep it as is.

The purist in me can't resist pointing out that these are not so much
defining something as making a binding between an existing command and a
given key sequence.  But using binding in the naming may be too geeky
even for the average Emacs user, so FWIW I agree "keymap-" is a good
choice, but "define-" is too grand.

					-- Bob Rogers
					   http://www.rgrjr.com/

Re: The new keymap functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Tne function name define-keymap sounds like a function to create a
keymap and name it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: The new keymap functions

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> But this macro should put a special property to all commands bound
> to repeatable keys.  This means that `defvar-keymap' should include
> special-handling of repeatable commands.

I think that should be possible.  

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Robert Pluim]

>>>>> On Thu, 18 Nov 2021 10:15:26 +0100, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> Juri Linkov <juri@linkov.net> writes:
    >> But this macro should put a special property to all commands bound
    >> to repeatable keys.  This means that `defvar-keymap' should include
    >> special-handling of repeatable commands.

    Lars> I think that should be possible.  

Iʼm sure Iʼve forgotten some subtlety of key definitions, but
something like this:

diff --git a/lisp/subr.el b/lisp/subr.el
index 7ba764880e..b405c80c96 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -6613,27 +6613,44 @@ defvar-keymap
 
 In addition to the keywords accepted by `define-keymap', this
 macro also accepts a `:doc' keyword, which (if present) is used
-as the variable documentation string.
+as the variable documentation string.  Passing in a non-nil
+`:repeat' keyword will cause the definitions to be marked as
+repeatable.
 
-\(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP &rest [KEY DEFINITION]...)"
+\(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP REPEAT &rest [KEY DEFINITION]...)"
   (declare (indent 1))
   (let ((opts nil)
-        doc)
+        doc repeatable props)
     (while (and defs
                 (keywordp (car defs))
                 (not (eq (car defs) :menu)))
       (let ((keyword (pop defs)))
         (unless defs
           (error "Uneven number of keywords"))
-        (if (eq keyword :doc)
-            (setq doc (pop defs))
+        (cond
+         ((eq keyword :doc)
+          (setq doc (pop defs)))
+         ((eq keyword :repeat)
+          (setq repeatable (pop defs)))
+         (t
           (push keyword opts)
-          (push (pop defs) opts))))
+          (push (pop defs) opts)))))
     (unless (zerop (% (length defs) 2))
       (error "Uneven number of key/definition pairs: %s" defs))
-    `(defvar ,variable-name
+    (when repeatable
+      (let ((defs defs)
+            def)
+        (while defs
+          (pop defs)
+          (setq def (pop defs))
+          (when (or (eq (car def) 'function)
+                    (eq (car def) 'quote))
+            (push `(put ,def 'repeat-map ',variable-name) props)))))
+    `(progn
+       ,@props
+       (defvar ,variable-name
        (define-keymap--define (list ,@(nreverse opts) ,@defs))
-       ,@(and doc (list doc)))))
+       ,@(and doc (list doc))))))
 
 (defmacro with-delayed-message (args &rest body)
   "Like `progn', but display MESSAGE if BODY takes longer than TIMEOUT seconds.

Re: The new keymap functions

[Lars Ingebrigtsen]

Robert Pluim <rpluim@gmail.com> writes:

> Iʼm sure Iʼve forgotten some subtlety of key definitions, but
> something like this:

Looks OK to me, but perhaps the actual code should go into define-keymap
(i.e., define-keymap--define) instead of defvar-keymap?  Is there a
reason why an anonymous keymap can't be repeatable? 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Lars Ingebrigtsen]

It has been suggested that `defvar-keymap' should be renamed to
`define-keymap', which I guess makes sense.  Then we need to rename
`define-keymap' to something, so...  `keymap-make'?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Robert Pluim]

>>>>> On Thu, 18 Nov 2021 11:37:26 +0100, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> It has been suggested that `defvar-keymap' should be renamed to
    Lars> `define-keymap', which I guess makes sense.  Then we need to rename
    Lars> `define-keymap' to something, so...  `keymap-make'?

But `defvar-keymap' doesnʼt just create the keymap, it defines the
variable as well, so Iʼd keep the name, and change the name of just
`define-keymap'.

`keymap-Factory-Instance-Create-Anonymous-Once'? Or is that too short?

Robert
-- 

Re: The new keymap functions

[Lars Ingebrigtsen]

Robert Pluim <rpluim@gmail.com> writes:

> But `defvar-keymap' doesnʼt just create the keymap, it defines the
> variable as well,

Some `define-' functions and macros do the same, like
`define-derived-mode', which defines a whole bunch of things, but also
sets a symbol.  (Other `define-' things do not create a name for the
thing it's defining.)

> so Iʼd keep the name, and change the name of just
> `define-keymap'.
>
> `keymap-Factory-Instance-Create-Anonymous-Once'? Or is that too short?

Way too short.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: The new keymap functions

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 653 bytes --]

>> The reason why I'm asking this is to know how the corresponding
>> function/macro for repeat-mode should be named in master.
>> And it seems `define-repeat-map' would be the right name.
>
> Are you sure you need a `define-repeat-map'? Just adding a :repeat
> keyword to `defvar-keymap' would be enough.

Thanks for the patch.  It would be nice to add also
:repeat-enter and :repeat-exit.  For example:

  :repeat-map t
  :repeat-enter '(enter-command ...)
  :repeat-exit '(exit-command ...)

Or maybe a shorter variant would be preferable?

  :repeat '(:enter '(enter-command ...) :exit '(exit-command ...))

Anyway this supports the first variant:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: defvar-keymap-repeat-map.patch --]
[-- Type: text/x-diff, Size: 3993 bytes --]

diff --git a/lisp/bindings.el b/lisp/bindings.el
index c1ad5f7520e..fcaa44648ab 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -1031,12 +1036,10 @@ global-map
 
 (defvar-keymap buffer-navigation-repeat-map
   :doc "Keymap to repeat `next-buffer' and `previous-buffer'.  Used in `repeat-mode'."
+  :repeat-map t
   "<right>" #'next-buffer
   "<left>"  #'previous-buffer)
 
-(put 'next-buffer 'repeat-map 'buffer-navigation-repeat-map)
-(put 'previous-buffer 'repeat-map 'buffer-navigation-repeat-map)
-
 (let ((map minibuffer-local-map))
   (define-key map "\en"   'next-history-element)
   (define-key map [next]  'next-history-element)
diff --git a/lisp/keymap.el b/lisp/keymap.el
index 107565590c1..15b00a8401c 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -557,22 +557,39 @@ defvar-keymap
 
 In addition to the keywords accepted by `define-keymap', this
 macro also accepts a `:doc' keyword, which (if present) is used
-as the variable documentation string.
+as the variable documentation string.  Also it accepts:
 
-\(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP &rest [KEY DEFINITION]...)"
+:repeat-map   If non-nil, put the `repeat-map' symbol properties
+              on commands in this map for `repeat-mode'.
+
+:repeat-enter A list of additional commands that only enter `repeat-mode'.
+              When the list is empty then by default all commands in the
+              map enter `repeat-mode'.  This is applicable when a command
+              has the `repeat-map' symbol property on its symbol, but
+              doesn't exist in the map.
+
+:repeat-exit A list of commands that exit `repeat-mode'.  When the
+             list is empty, no commands in the map exit `repeat-mode'.
+             This is applicable when a command exists in the map, but
+             doesn't have the `repeat-map' symbol property on its symbol.
+
+\(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP REPEAT-MAP REPEAT-ENTER REPEAT-EXIT &rest [KEY DEFINITION]...)"
   (declare (indent 1))
   (let ((opts nil)
-        doc)
+        doc repeat-map repeat-enter repeat-exit props)
     (while (and defs
                 (keywordp (car defs))
                 (not (eq (car defs) :menu)))
       (let ((keyword (pop defs)))
         (unless defs
           (error "Uneven number of keywords"))
-        (if (eq keyword :doc)
-            (setq doc (pop defs))
-          (push keyword opts)
-          (push (pop defs) opts))))
+        (pcase keyword
+          (:doc (setq doc (pop defs)))
+          (:repeat-map   (setq repeat-map   (pop defs)))
+          (:repeat-enter (setq repeat-enter (pop defs)))
+          (:repeat-exit  (setq repeat-exit  (pop defs)))
+          (_ (push keyword opts)
+             (push (pop defs) opts)))))
     (unless (zerop (% (length defs) 2))
       (error "Uneven number of key/definition pairs: %s" defs))
     (let ((defs defs)
@@ -585,9 +602,24 @@ defvar-keymap
               (error "Duplicate definition for key '%s' in keymap '%s'"
                      key variable-name)
             (push key seen-keys)))))
-    `(defvar ,variable-name
-       (define-keymap ,@(nreverse opts) ,@defs)
-       ,@(and doc (list doc)))))
+    (when repeat-map
+      (let ((defs defs)
+            def)
+        (while defs
+          (pop defs)
+          (setq def (pop defs))
+          (when (and (or (eq (car def) 'function)
+                         (eq (car def) 'quote))
+                     (or (null repeat-exit)
+                         (not (memq def repeat-exit))))
+            (push `(put ,def 'repeat-map ',variable-name) props)))
+        (dolist (def repeat-enter)
+          (push `(put ',def 'repeat-map ',variable-name) props))))
+    `(progn
+       (defvar ,variable-name
+         (define-keymap ,@(nreverse opts) ,@defs)
+         ,@(and doc (list doc)))
+       ,@props)))
 
 (defun make-non-key-event (symbol)
   "Mark SYMBOL as an event that shouldn't be returned from `where-is'."

Re: The new keymap functions

[Juri Linkov]

> Or maybe a shorter variant would be preferable?
>
>   :repeat (:enter (enter-command ...) :exit (exit-command ...))

I pushed the rewrite that uses the above.  Please check in the commit
ddbc33343c.

Re: The new keymap functions

[Robert Pluim]

>>>>> On Thu, 17 Nov 2022 09:31:51 +0200, Juri Linkov <juri@linkov.net> said:

    >> Or maybe a shorter variant would be preferable?
    >> 
    >> :repeat (:enter (enter-command ...) :exit (exit-command ...))

    Juri> I pushed the rewrite that uses the above.  Please check in the commit
    Juri> ddbc33343c.

It looks good. I think the docstring needs some small adjustements,
Iʼll work on those over the next few days.

Thanks

Robert
-- 

Re: The new keymap functions

[Robert Pluim]

>>>>> On Thu, 17 Nov 2022 09:35:56 +0100, Robert Pluim <rpluim@gmail.com> said:

    Robert> It looks good. I think the docstring needs some small adjustements,
    Robert> Iʼll work on those over the next few days.

Juri, what do you think of the following:

diff --git a/lisp/keymap.el b/lisp/keymap.el
index 0285c0571f..eaeba96644 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -559,18 +559,26 @@ defvar-keymap
 macro also accepts a `:doc' keyword, which (if present) is used
 as the variable documentation string.
 
-When a `:repeat' keyword is non-nil, put `repeat-map' symbol
-properties on commands in this map for `repeat-mode'.  The value
-could also be a property list with properties `:enter' and `:exit',
-for example, :repeat (:enter (commands ...) :exit (commands ...)).
-`:enter' is a list of additional commands that only enter `repeat-mode'.
-When the list is empty then by default all commands in the map enter
-`repeat-mode'.  This is applicable when a command has the `repeat-map'
-symbol property on its symbol, but doesn't exist in the map.  `:exit'
-is a list of commands that exit `repeat-mode'.  When the list is
-empty, no commands in the map exit `repeat-mode'.  This is applicable
-when a command exists in the map, but doesn't have the `repeat-map'
-symbol property on its symbol.
+The `:repeat' keyword can also be specified; it controls the
+`repeat-mode' behavior of the bindings in the keymap.  When it is
+non-nil, all commands in the map will have the `repeat-map'
+symbol property.
+
+More control is available over which commands are repeatable; the
+value can also be a property list with properties `:enter' and
+`:exit', for example:
+
+     :repeat (:enter (commands ...) :exit (commands ...))
+
+`:enter' specifies the list of additional commands that only
+enter `repeat-mode'.  When the list is empty, then by default all
+commands in the map enter `repeat-mode'.  This is useful when
+there is a command that has the `repeat-map' symbol property, but
+doesn't exist in this specific map.  `:exit' is a list of
+commands that exit `repeat-mode'.  When the list is empty, no
+commands in the map exit `repeat-mode'.  This is useful when a
+command exists in this specific map, but it doesn't have the
+`repeat-map' symbol property on its symbol.
 
 \(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP REPEAT &rest [KEY DEFINITION]...)"
   (declare (indent 1))

Robert
-- 

Re: The new keymap functions

[Juri Linkov]

> Robert> It looks good. I think the docstring needs some small adjustements,
> Robert> Iʼll work on those over the next few days.
>
> Juri, what do you think of the following:

Thanks, your version is much better than the current docstring.

Re: The new keymap functions

[Robert Pluim]

[-- Attachment #1: Type: text/plain, Size: 428 bytes --]

On Thu, Nov 17, 2022, 18:31 Juri Linkov <juri@linkov.net> wrote:

> > Robert> It looks good. I think the docstring needs some small
> adjustements,
> > Robert> Iʼll work on those over the next few days.
> >
> > Juri, what do you think of the following:
>
> Thanks, your version is much better than the current docstring.
>

Ok, I'll push it once my internet is back up (hopefully tonight)

Regards

Robert

>

[-- Attachment #2: Type: text/html, Size: 1024 bytes --]

Re: The new keymap functions

[Robert Pluim]

>>>>> On Fri, 18 Nov 2022 09:33:24 +0100, Robert Pluim <rpluim@gmail.com> said:

    Robert> On Thu, Nov 17, 2022, 18:31 Juri Linkov <juri@linkov.net> wrote:
    >> > Robert> It looks good. I think the docstring needs some small
    >> adjustements,
    >> > Robert> Iʼll work on those over the next few days.
    >> >
    >> > Juri, what do you think of the following:
    >> 
    >> Thanks, your version is much better than the current docstring.
    >> 

    Robert> Ok, I'll push it once my internet is back up (hopefully tonight)

New ways to connect to Internet means new and fun failure modes, which
require new methods to fix that end users donʼt have access to 😀

Anyway, now pushed as 4506b005ab

Thanks

Robert
-- 

Re: The new keymap functions

[Robert Pluim]

So I re-read the `defvar-keymap' docstring, and failed to grasp what I
myself had written. So, another proposed improvement:

@@ -579,14 +581,17 @@ defvar-keymap
      :repeat (:enter (commands ...) :exit (commands ...))
 
 `:enter' specifies the list of additional commands that only
-enter `repeat-mode'.  When the list is empty, then by default all
-commands in the map enter `repeat-mode'.  This is useful when
-there is a command that has the `repeat-map' symbol property, but
-doesn't exist in this specific map.  `:exit' is a list of
-commands that exit `repeat-mode'.  When the list is empty, no
-commands in the map exit `repeat-mode'.  This is useful when a
-command exists in this specific map, but it doesn't have the
-`repeat-map' symbol property on its symbol.
+enter `repeat-mode'.  When the list is empty, then only the
+commands defined in the map enter `repeat-mode'.  Specifying a
+list of commands is useful when there are commands that have the
+`repeat-map' symbol property, but don't exist in this specific
+map.
+
+`:exit' is a list of commands that exit `repeat-mode'.  When the
+list is empty, no commands in the map exit `repeat-mode'.
+Specifying a list of commands is useful when those commands exist
+in this specific map, but should not have the `repeat-map' symbol
+property.

Robert
-- 

Re: The new keymap functions

[Juri Linkov]

> So I re-read the `defvar-keymap' docstring, and failed to grasp what I
> myself had written. So, another proposed improvement:
>
> @@ -579,14 +581,17 @@ defvar-keymap
>       :repeat (:enter (commands ...) :exit (commands ...))
>  
>  `:enter' specifies the list of additional commands that only
> -enter `repeat-mode'.  When the list is empty, then by default all
> -commands in the map enter `repeat-mode'.  This is useful when
> -there is a command that has the `repeat-map' symbol property, but
> -doesn't exist in this specific map.  `:exit' is a list of
> -commands that exit `repeat-mode'.  When the list is empty, no
> -commands in the map exit `repeat-mode'.  This is useful when a
> -command exists in this specific map, but it doesn't have the
> -`repeat-map' symbol property on its symbol.
> +enter `repeat-mode'.  When the list is empty, then only the
> +commands defined in the map enter `repeat-mode'.  Specifying a
> +list of commands is useful when there are commands that have the
> +`repeat-map' symbol property, but don't exist in this specific
> +map.
> +
> +`:exit' is a list of commands that exit `repeat-mode'.  When the
> +list is empty, no commands in the map exit `repeat-mode'.
> +Specifying a list of commands is useful when those commands exist
> +in this specific map, but should not have the `repeat-map' symbol
> +property.

Thanks, I confirm this is more clear and correct.

Re: The new keymap functions

[Robert Pluim]

>>>>> On Sat, 18 Mar 2023 20:04:32 +0200, Juri Linkov <juri@linkov.net> said:
    Juri> Thanks, I confirm this is more clear and correct.

Thanks Juri, pushed to emacs-29


Robert
--