Suggestion for improving ergonomics of repeat-maps: define-repeat-map

Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[acdw]

Hi Emacs maintainers!

I've written a package[1] for my own ease of use in defining repeat-maps for Emacs 28, and a few people have told me I should see about adding it to Emacs proper.  So here we are.

The elevator pitch:

The new functionality defined in repeat.el in Emacs 28 is very useful, but usually requires a large amount of configuration, to wit:

~~~
(defalias 'forward-word-with-case 'forward-word
  "Alias for `forward-word' for use in `case-repeat-map'.")
(defalias 'backward-word-with-case 'backward-word
  "Alias for `backward-word for use in `case-repeat-map'.")

(defvar case-repeat-map
  (let ((map (make-sparse-keymap)))
    (define-key map "c" #'capitalize-word)
    (define-key map "u" #'upcase-word)
    (define-key map "l" #'downcase-word)
    ;; movement
    (define-key map "f" #'forward-word-with-case)
    (define-key map "b" #'backward-word-with-case)
    map)
  "A map to repeat word-casing commands.  For use with `repeat-mode'.")
  
(dolist (command '(capitalize-word
                   capitalize-dwim
                   upcase-word
                   upcase-dwim
                   downcase-word
                   downcase-dwim
                   forward-word-with-case
                   backward-word-with-case))
  (put command 'repeat-map 'case-repeat-map))
~~~

I wrote the macro `define-repeat-map' to alleviate this large amount of configuration.  Using this macro, the above turns into this:

~~~
(define-repeat-map case
  ("c" capitalize-word
   "u" upcase-word
   "l" downcase-word)
  (:continue "f" forward-word
             "b" backward-word)
  (:enter downcase-dwim
          upcase-dwim
          capitalize-dwim))
~~~

As you can see, `define-repeat-map' makes it easier to not only define repeating keys for commands, but to define commands that can enter the keymap, keys that are in the keymap and can continue the binds, but not enter the map, and commands that will exit the map when they're pressed.  I was inspired by the repeaters[2] package on GitHub, but wrote my own because I wanted better (to me) ergonomics.

Please let me know what you think about this macro and package.  I've written some elisp for my own enjoyment but never submitted a package to Emacs, or looked into including it in core.  I'm open to any and all suggestions, including simply adding this package to GNU ELPA.

Thanks for all you do!

[1]: https://tildegit.org/acdw/define-repeat-map.el/

-- 
~ acdw (Case Duckworth)
https://www.acdw.net | https://breadpunk.club/~breadw

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Philip Kaludercic]

acdw <acdw@acdw.net> writes:

> I wrote the macro `define-repeat-map' to alleviate this large amount
> of configuration.  Using this macro, the above turns into this:
>
> ~~~
> (define-repeat-map case
>   ("c" capitalize-word
>    "u" upcase-word
>    "l" downcase-word)
>   (:continue "f" forward-word
>              "b" backward-word)
>   (:enter downcase-dwim
>           upcase-dwim
>           capitalize-dwim))
> ~~~

I haven't taken a detailed look at the source, but I have two
superficial questions:

1. Why is the name argument required? Shouldn't the macro be able to
   gensym a new symbol to use for the map?
2. Could the argument structure be flattened, so that you could write
   something like

        (define-repeat-map
          "c" capitalize-word
          "u" upcase-word
          "l" downcase-word
          :continue
          "f" forward-word
          "b" backward-word
          :enter
          downcase-dwim
          upcase-dwim
          capitalize-dwim)

   ?

-- 
	Philip Kaludercic

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[acdw]

On 2021-09-08 (Wednesday) at 14:54, Philip Kaludercic <philipk@posteo.net> wrote:
>
> I haven't taken a detailed look at the source, but I have two
> superficial questions:
> 
> 1. Why is the name argument required? Shouldn't the macro be able to
>    gensym a new symbol to use for the map?
> 2. Could the argument structure be flattened, so that you could write
>    something like
> 
>         (define-repeat-map
>           "c" capitalize-word
>           "u" upcase-word
>           "l" downcase-word
>           :continue
>           "f" forward-word
>           "b" backward-word
>           :enter
>           downcase-dwim
>           upcase-dwim
>           capitalize-dwim)
> 
>    ?
> 
> -- 
> 	Philip Kaludercic
> 

To answer your questions:

1. I wanted the resulting keymap to be introspectable; the macro creates a keymap named "NAME-repeat-map," 
   i.e., "case-repeat-map," that can be C-h v'd and friends.  (Now that I'm thinking about it, perhaps I
   should change the map's documentation property after the fact, to include the keys in the map.)
2. There's no particular reason it couldn't be flattened; I just like sexp's structure a bit better.

In fact (regarding 2), there is also this syntax, which I've been thinking of as well:

~~~
(define-repeat-map map
  (("c" . #'capitalize-word)
   ("u" . #'upcase-word)
   ("l" . #'downcase-word))
  (:continue
   ("f" . #'forward-word)
   ("b" . #'backward-word))
  (:enter '(downcase-dwim upcase-dwim capitalize-dwim)))
~~~

Your proposed syntax could also work just fine with a slight refactor, which I should do anyway; another consideration is whether the `:enter' commands should also define the keys in the current-global-map, or possibly a customizable map.

The other question is, does this need to be a macro, or is a function enough?

-- 
~ acdw
acdw.net | breadpunk.club/~breadw

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Juri Linkov]

> I've written a package[1] for my own ease of use in defining
> repeat-maps for Emacs 28, and a few people have told me I should see
> about adding it to Emacs proper.  So here we are.

Thanks, this would be a nice addition.

> (defvar case-repeat-map
>   (let ((map (make-sparse-keymap)))
>     (define-key map "c" #'capitalize-word)
>     (define-key map "u" #'upcase-word)
>     (define-key map "l" #'downcase-word)
>     ;; movement
>     (define-key map "f" #'forward-word-with-case)
>     (define-key map "b" #'backward-word-with-case)
>     map)
>   "A map to repeat word-casing commands.  For use with `repeat-mode'.")

The reason why currently in Emacs core repeat-maps are defined this way
is because this is a standard way to define a keymap.

If normal keymaps were defined with a macro similar to the macro
that you created, it would be easier to migrate the existing repeat-maps
to your macro.  I mean if we had a macro `define-keymap' that defines
normal keymaps and that is similar to your `define-repeat-map',
then creating a repeat-map from the normal map would require just
changing the macro name `define-keymap' to `define-repeat-map'.

> I wrote the macro `define-repeat-map' to alleviate this large amount
> of configuration.  Using this macro, the above turns into this:
>
> ~~~
> (define-repeat-map case
>   ("c" capitalize-word
>    "u" upcase-word
>    "l" downcase-word)
>   (:continue "f" forward-word
>              "b" backward-word)
>   (:enter downcase-dwim
>           upcase-dwim
>           capitalize-dwim))

I'd like to hear more opinions whether the above macro is a better
way to define repeat-maps in Emacs core.  I'm sure this macro is nice
to use in a personal customization init file, but the question is
about using it in Emacs core.  If this will be preferable for Emacs core,
then it could be included in repeat.el.  Otherwise, GNU ELPA is a better place.
Then for Emacs core I'd suggest at least to add another macro
'define-repeat-key' that will remove the need of adding manually
`(put command 'repeat-map 'case-repeat-map)`, e.g.:

(defvar case-repeat-map
  (let ((map (make-sparse-keymap)))
    (define-repeat-key map "c" #'capitalize-word)
    (define-repeat-key map "u" #'upcase-word)
    (define-repeat-key map "l" #'downcase-word)
    ;; movement
    (define-repeat-key map "f" #'forward-word-with-case)
    (define-repeat-key map "b" #'backward-word-with-case)
    map)

Then it will preserve the same style already used in core.

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> If normal keymaps were defined with a macro similar to the macro
> that you created, it would be easier to migrate the existing repeat-maps
> to your macro.  I mean if we had a macro `define-keymap' that defines
> normal keymaps and that is similar to your `define-repeat-map',
> then creating a repeat-map from the normal map would require just
> changing the macro name `define-keymap' to `define-repeat-map'.

Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
29.  :-)  (So another week or so.)

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Augusto Stoffel]

On Thu,  9 Sep 2021 at 20:06, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Juri Linkov <juri@linkov.net> writes:
>
>> If normal keymaps were defined with a macro similar to the macro
>> that you created, it would be easier to migrate the existing repeat-maps
>> to your macro.  I mean if we had a macro `define-keymap' that defines
>> normal keymaps and that is similar to your `define-repeat-map',
>> then creating a repeat-map from the normal map would require just
>> changing the macro name `define-keymap' to `define-repeat-map'.
>
> Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
> 29.  :-)  (So another week or so.)

Why is it a macro, not just a function?

This is tangential, but if define-key could take an arbitrary number of
KEY DEF pairs to define (like setq for variables), it would be immensely
more convenient.

It would also be nice to allow keyword arguments like :prefix (to define
a bunch of keys with a common prefix) or :filter (to put all the DEFs in
menu-items with the provided :filter function)

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

Augusto Stoffel <arstoffel@gmail.com> writes:

>> Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
>> 29.  :-)  (So another week or so.)
>
> Why is it a macro, not just a function?

I mistyped -- it's a function.

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[acdw]

On 2021-09-09 (Thursday) at 17:50, Juri Linkov <juri@linkov.net> wrote:

> > I've written a package[1] for my own ease of use in defining
> > repeat-maps for Emacs 28, and a few people have told me I should see
> > about adding it to Emacs proper.  So here we are.
> 
> Thanks, this would be a nice addition.
> 
> > (defvar case-repeat-map
> >   (let ((map (make-sparse-keymap)))
> >     (define-key map "c" #'capitalize-word)
> >     (define-key map "u" #'upcase-word)
> >     (define-key map "l" #'downcase-word)
> >     ;; movement
> >     (define-key map "f" #'forward-word-with-case)
> >     (define-key map "b" #'backward-word-with-case)
> >     map)
> >   "A map to repeat word-casing commands.  For use with `repeat-mode'.")
> 
> The reason why currently in Emacs core repeat-maps are defined this way
> is because this is a standard way to define a keymap.
> 
> If normal keymaps were defined with a macro similar to the macro
> that you created, it would be easier to migrate the existing repeat-maps
> to your macro.  I mean if we had a macro `define-keymap' that defines
> normal keymaps and that is similar to your `define-repeat-map',
> then creating a repeat-map from the normal map would require just
> changing the macro name `define-keymap' to `define-repeat-map'.

I think this is an absolutely wonderful idea, especially to have `define-keymap' be more like `setq' (in fact, I think even more functions could be defined this way, but I digress).  I can work on a `define-keymap' this weekend, and incorporate `define-repeat-keymap' in it :D

> 
> > I wrote the macro `define-repeat-map' to alleviate this large amount
> > of configuration.  Using this macro, the above turns into this:
> >
> > ~~~
> > (define-repeat-map case
> >   ("c" capitalize-word
> >    "u" upcase-word
> >    "l" downcase-word)
> >   (:continue "f" forward-word
> >              "b" backward-word)
> >   (:enter downcase-dwim
> >           upcase-dwim
> >           capitalize-dwim))
> 
> I'd like to hear more opinions whether the above macro is a better
> way to define repeat-maps in Emacs core.  I'm sure this macro is nice
> to use in a personal customization init file, but the question is
> about using it in Emacs core.  If this will be preferable for Emacs core,
> then it could be included in repeat.el.  Otherwise, GNU ELPA is a better place.
> Then for Emacs core I'd suggest at least to add another macro
> 'define-repeat-key' that will remove the need of adding manually
> `(put command 'repeat-map 'case-repeat-map)`, e.g.:
> 
> (defvar case-repeat-map
>   (let ((map (make-sparse-keymap)))
>     (define-repeat-key map "c" #'capitalize-word)
>     (define-repeat-key map "u" #'upcase-word)
>     (define-repeat-key map "l" #'downcase-word)
>     ;; movement
>     (define-repeat-key map "f" #'forward-word-with-case)
>     (define-repeat-key map "b" #'backward-word-with-case)
>     map)
> 
> Then it will preserve the same style already used in core.

This is the biggest reason I'm asking about `define-repeat-map' here; It's definitely a user-configuration-ease type macro/function (honestly this probably should be a function, the more I think about it).  It's not very "Emacs-y", from what I've seen of the "Emacs-y" way to do things.

However, `define-repeat-key' /does/ have some functionality that's not included in even the code you've included: it automatically creates the necessary aliases for continuation commands, which you'd need to do separately to create `forward-word-with-case' and `backward-word-with-case', above.

Though now that I'm thinking of it, I'd probably rewrite your example to include

(define-repeat-key map "f" (defalias 'forward-word-with-case 'forward-word))

Though I don't think /that's/ very "Emacs-y", either.

At the very least I'd be happy to add `define-repeat-map' or something like it to ELPA.

-- 
~ acdw
acdw.net | breadpunk.club/~breadw

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[acdw]

On 2021-09-09 (Thursday) at 18:06, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
> 29.  :-)  (So another week or so.)

I would /love/ to see this!  It would greatly ease my own efforts :)

-- 
~ acdw
acdw.net | breadpunk.club/~breadw

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

acdw <acdw@acdw.net> writes:

> I would /love/ to see this!  It would greatly ease my own efforts :)

It's still a work in progress -- I'm going through various bits of Emacs
code that define keys and seeing whether it fits all the use cases (and
tweaking it a bit).  

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

acdw <acdw@acdw.net> writes:

> On 2021-09-09 (Thursday) at 18:06, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>
>> Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
>> 29.  :-)  (So another week or so.)
>
> I would /love/ to see this!  It would greatly ease my own efforts :)

That was a very long week, but it's now pushed to the trunk.

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Adam Porter]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>>> Heh.  I've got a `define-keymap' macro stashed away, waiting for Emacs
>>> 29.  :-)  (So another week or so.)
>>
>> I would /love/ to see this!  It would greatly ease my own efforts :)
>
> That was a very long week, but it's now pushed to the trunk.

Thanks, this will be very useful.

I'm confused about a small detail, though: it seems that define-keymap
allows keyword/value pairs inline with the key/binding pairs, but
defvar-keymap requires the keyword/value pairs to be in a list, and an
empty one when none are given.  The manual entry doesn't seem to cover
this difference.

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

Adam Porter <adam@alphapapa.net> writes:

> I'm confused about a small detail, though: it seems that define-keymap
> allows keyword/value pairs inline with the key/binding pairs, but
> defvar-keymap requires the keyword/value pairs to be in a list, and an
> empty one when none are given.  The manual entry doesn't seem to cover
> this difference.

Doesn't the manual document the syntax of both of these?

But I guess it's a bit confusing how the syntaxes are similar but
different?  I went back and forth a number of time on the syntax --
define-keymap is a function, so it can't do the function-line macro
syntax that defvar-keymap can (which is better).  But having the first
argument of define-keymap be a list (which would be preferable in most
ways) just looked awkward.

(define-keymap (list :full t)
  ...)

But I'm open to changing it if it's too confusing the way it is now.

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Adam Porter]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Doesn't the manual document the syntax of both of these?

I'm sorry, you're right, it does, the key being in these lines:

  @defun define-keymap &key options... &rest pairs...

  @defmac defvar-keymap name options &rest defs

That's what I get for trying to read the raw texinfo in a diff buffer.

> But I guess it's a bit confusing how the syntaxes are similar but
> different?  I went back and forth a number of time on the syntax --
> define-keymap is a function, so it can't do the function-line macro
> syntax that defvar-keymap can (which is better).  But having the first
> argument of define-keymap be a list (which would be preferable in most
> ways) just looked awkward.
>
> (define-keymap (list :full t)
>   ...)
>
> But I'm open to changing it if it's too confusing the way it is now.

If users see this function and macro as "siblings," I could imagine
their slightly different signatures being confusing.  I don't know if
that would justify changing them to be more similar.

To be honest, I was surprised to see defvar-keymap as a separate macro.
I was expecting, e.g. define-keymap to be used inside a defvar,
something like:

  (defvar foo-map
    (define-keymap ...)
    "Docstring for foo-map.")

Not to complain about having the macro, of course.  :)

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

Adam Porter <adam@alphapapa.net> writes:

> To be honest, I was surprised to see defvar-keymap as a separate macro.
> I was expecting, e.g. define-keymap to be used inside a defvar,
> something like:
>
>   (defvar foo-map
>     (define-keymap ...)
>     "Docstring for foo-map.")
>
> Not to complain about having the macro, of course.  :)

It was a late addition.  I started converting a couple keymaps to check
the ergonomics, and it became clear that >90% of the usages would look
just like that, so I added the macro version.

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Juri Linkov]

> But I guess it's a bit confusing how the syntaxes are similar but
> different?  I went back and forth a number of time on the syntax --
> define-keymap is a function, so it can't do the function-line macro
> syntax that defvar-keymap can (which is better).  But having the first
> argument of define-keymap be a list (which would be preferable in most
> ways) just looked awkward.
>
> (define-keymap (list :full t)
>   ...)
>
> But I'm open to changing it if it's too confusing the way it is now.

But why not to unify them in another direction, i.e. not to use a list
for options in defvar-keymap.  Then both syntaxes would be the same:

  (define-keymap
    :full t
    "g" #'eww-reload)

  (defvar-keymap eww-textarea-map
    :full t
    "g" #'eww-reload)

instead of

  (defvar-keymap eww-textarea-map
    (:full t)
    "g" #'eww-reload)

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> But why not to unify them in another direction, i.e. not to use a list
> for options in defvar-keymap.  Then both syntaxes would be the same:

[...]

>   (defvar-keymap eww-textarea-map
>     :full t
>     "g" #'eww-reload)

The parenthesised version is more regular -- the keywords-at-the-start
thing feels pretty hackish.  (And means that eldoc doesn't give correct
info.)

But we do use the keyword-at-the-start approach in
`define-derived-mode', for instance, so perhaps we could here, too.
Putting keywords inside a () is pretty unusual syntax, anyway.

So I'm open to unify them in this direction...

Does eldoc have support for this kind of oddball syntax, by any chance?

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Stefan Monnier]

> Does eldoc have support for this kind of oddball syntax, by any chance?

Not sure what you mean.  Regarding doc-string highlighting we don't, no,
and it would be nice to add it (for the benefit of `cl-defmethod`, at
least).


        Stefan

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

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

>> Does eldoc have support for this kind of oddball syntax, by any chance?
>
> Not sure what you mean.  Regarding doc-string highlighting we don't, no,
> and it would be nice to add it (for the benefit of `cl-defmethod`, at
> least).

It does do the right thing for &key in cl-defmethod, though?  Seems to
boldify it correctly in the echo area...  But in this case, we have some
keywords first and then pairs of stuff at the end.

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

Re: Suggestion for improving ergonomics of repeat-maps: define-repeat-map

[Lars Ingebrigtsen]

I'd forgotten how all this works over in cl-defmethod land.  So:

(cl-defmethod foo (&rest gazonk &key bar zot &allow-other-keys)
  (list bar zot gazonk))

(foo :bar 1 :zot 3 5 6 7)
=> (1 3 (:bar 1 :zot 3 5 6 7))

However, the correct parameters won't be boldified in the echo area.
But if you do this:

(foo  5 6 7 :bar 1 :zot 3)

they will.  But that's ... even less helpful:

=> (nil nil (5 6 7 :bar 1 :zot 3))

And you can't put the &rest after &key.  So it seems like we've got some
oddities in this area.

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