`global-set-key' vs `keymap-global-set' `key-valid-p' syntax

`global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

In the docstring to `global-set-key' they say it is a legacy
function and one should use `keymap-global-set' instead.

This note is hardcoded in the docstring so the byte-compiler
don't tell you about it.

What is the difference between obsolete, legacy, and
deprecated source code? We learn from gpt4 that

  - obsolete code is outdated and no longer used;
  
  - legacy code is still in use but outdated; and
  
  - deprecated code is discouraged from being used but still functional.

Since `global-set-key' and `keymap-global-set' superficially
have identical interfaces, it would seem it would be easy to
do a search and replace. However, this is not so because one
syntax to denote keys, if I just take one example from my own
Elisp - which, BTW, has 78 instances of global-set-key - isn't
allowed with keymap-global-set.

;; disable keys
(global-set-key "\C-h\C-p" #'ignore) ; view-emacs-problems
(global-set-key "\C-hr"    #'ignore) ; info-emacs-manual
(global-set-key "\C-ht"    #'ignore) ; help-with-tutorial
(global-set-key "\C-x\C-c" #'ignore) ; save-buffers-kill-terminal
(global-set-key "\C-x\C-n" #'ignore) ; set-goal-column

The reason is they are not valid by `key-valid-p'.

I don't know what the reasoning behind this was? One gets the
feeling that Emacs is obsolete but still in use, and left in
the repos only to avoid conflicts with legacy programmers.

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

> (global-set-key "\C-h\C-p" #'ignore) ; view-emacs-problems
> (global-set-key "\C-hr"    #'ignore) ; info-emacs-manual [...]
>
> The reason is they are not valid by `key-valid-p'.

It is easy to transform most strings, this is described in the
docstring to `key-valid-p'.

So in the cases of "\C-h\C-p" and "\C-hr" above, they will be
"C-h C-p" and "C-h r" which one can argue is more clear.

"\r" and such cases will be "RET" and other shorthand syntax
which is also more clear.

However there is one use case I don't know how to translate to
the new format, it looks, for example, like this:

  (define-key input-decode-map [?\u1000] [M-S-RET-a])
  (global-set-key [M-S-RET-a] (lambda () (interactive) (message "hit M-S-RET")))

Also, this is not just for `global-set-key'!

Also `define-key' and the corresponding functions for
unsetting keys globally and locally should be replaced.

So it is a lot of work ;)

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

> However there is one use case I don't know how to translate
> to the new format, it looks, for example, like this:
>
>   (define-key input-decode-map [?\u1000] [M-S-RET-a])
>   (global-set-key [M-S-RET-a] (lambda () (interactive) (message "hit M-S-RET")))

Here is another example of the same thing, almost.

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/signal.el
;;
;; test from Emacs:
;;   (signal-process (emacs-pid) 'sigusr1)
;;
;; test from zsh:
;;   $ kill -s usr1 $(pidof emacs)

(defun signal-usr1-f ()
  (interactive)
  (message "USR1 signal") )

(define-key special-event-map [sigusr1] #'signal-usr1-f)

(provide 'signal)

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

> However there is one use case I don't know how to translate to
> the new format, it looks, for example, like this:
>
>   (define-key input-decode-map [?\u1000] [M-S-RET-a])
>   (global-set-key [M-S-RET-a] (lambda () (interactive) (message "hit M-S-RET")))

A third use case with the same [use case]:

(defun no-confirm-w3m-quit ()
  (interactive)
  (w3m-quit t) ) ; FORCE

(define-key (current-global-map) [remap w3m-quit] #'no-confirm-w3m-quit)

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Andreas Schwab]

On Mai 07 2024, Emanuel Berg wrote:

> (define-key (current-global-map) [remap w3m-quit] #'no-confirm-w3m-quit)

(key-parse "<remap> <w3m-quit>") => [remap w3m-quit]

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

Andreas Schwab wrote:

>> (define-key (current-global-map) [remap w3m-quit] #'no-confirm-w3m-quit)
>
> (key-parse "<remap> <w3m-quit>") => [remap w3m-quit]

Thanks, that's right, so you can do

  (keymap-global-set "<remap> <w3m-quit>" #'no-confirm-w3m-quit)

That syntax is perhaps confusing, `w3m-quit' is a function and
"remap" is perhaps a special keyword that makes sense to
keymap functions? Well, maybe people shouldn't rely too much
on remaping anyway.

For the other use case previously mentioned, you can use the
same syntax:

  (keymap-set special-event-map "<sigusr1>" #'signal-usr1-f)

That leaves only this unsolved at the moment:

  (define-key input-decode-map [?\u1000] [M-S-RET-a])
  (global-set-key [M-S-RET-a] (lambda () (interactive) (message "hit M-S-RET")))

Instead of writing the the docstring it is legacy one should
use `make-obsolete', if one considers there to be a difference
between obsolete and legacy I guess we need a make-legacy on
as well.

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

> That leaves only this unsolved at the moment:
> 
> (define-key input-decode-map [?\u1000] [M-S-RET-a])
> (global-set-key [M-S-RET-a] (lambda () (interactive) (message "hit M-S-RET")))

You can do that like this:

(keymap-set input-decode-map (char-to-string ?\u1000) "<msret>")
(keymap-global-set "<msret>" (lambda () (interactive) (message "A state of trance")))

See, simple. No reason whatsoever to rely on legacy code.

-- 
underground experts united
https://dataswamp.org/~incal

Re: `global-set-key' vs `keymap-global-set' `key-valid-p' syntax

[Emanuel Berg]

Warning, don't set "C-[" as a key or use it as a definition,
that breaks M-x as C-[, or ^[, is also ESC.

$ ascii '^['
ASCII 1/11 is decimal 027, hex 1b, octal 033, bits 00011011: called ^[, ESC
Official name: Escape

Yes, making a new (?) definition with the same name also does
not help. You can however rewire the terminal emulator to
insert another char on that keystroke and then give that key
another definition name, e.g. like this for the character
inserted being 1005 in hex:

(keymap-set input-decode-map (char-to-string ?\u1005) "C-<left-square-bracket>")

For some reason tho, this logic does not seem to apply to C-;
or ^;, which is also 027:

ascii '^;'
ASCII 1/11 is decimal 027, hex 1b, octal 033, bits 00011011: called ^[, ESC
Official name: Escape

It can be set and used in a definition with that name, "C-;",
I have no idea why but I guess just to be safe/consistent one
can call it "C-<semicolon>".

Using de facto key notation on a US QWERTY, C-[ is somewhat
ergonomic, whereas C-; is really nice! So recommended.

-- 
underground experts united
https://dataswamp.org/~incal