Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

> If we want to write it in pseudo-Lisp, this is much
> more Lisp-like yet with much less nesting.
>
>    (or (FIND-IN special-event-map)
>         (if overriding-terminal-local-map
>             (FIND-IN overriding-terminal-local-map)
>           (if overriding-local-map
>               (FIND-IN overriding-local-map)
>             (or (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
>                 (FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
>                 (FIND-IN-ANY minor-mode-overriding-map-alist)
>                 (FIND-IN-ANY minor-mode-map-alist)
>                 (FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
>                 (FIND-IN (current-local-map)))))
>        (FIND-IN (current-global-map)))
>
>  
I have taken your and Stefan´s suggestions and merged it with what I had 
previously. It looks better than I expected. I have in this case left 
out the examples that Kim wanted because I think they will clutter the 
pseudo-Lisp structure. Maybe these examples fit better in the longer 
descriptions of the functions and variables in Info?

We have slightly different ideas of what this subnode should be for. I 
believe it serves its main purpose of finding the keymap with a little 
bit broader picture so I have written a suggestion along that line. I 
renamed the header to "Finding the keymap and its entry to use" to 
reflect this a bit.

I have attached a the new version. Please try to answer the two 
questions in there that I do not know the answer of myself!

@subsection Finding the keymap and its entry to use

First the keyboard input events must be translated (@pxref{Translating
Input}).  This is done in two steps, first character translation and
then key sequence translation:

@itemize @bullet
@item
The character translation is done in three sequential steps using
@code{extra-keyboard-modifiers}, @code{keyboard-translate-table} and
@code{meta-prefix-char}.

@item
Key sequence translation: Keyboard event at this stage that has not
yet been mapped to a keymap are kept in a queue.  The subsequences in
this queue are checked and may be transformed by the tables in
@code{function-key-map} and @code{key-translation-map}.  Note that
this requires a look ahead in the keymaps in the order described
below.
@end itemize

(@strong{special-even-map is missing above yet!!!})

After the translations above Emacs looks in the active keymaps for a
match.  As soon as a match is found (see @pxref{Key Lookup}) then if
the keymap entry is a function the search is over.  However if the
keymap entry is a variable symbol or a string then Emacs replaces the
input key sequences with the variable symbol value or the string and
restarts searching in the active keymaps.

The keymap entry could also be a keymap.  In that case the next event
is looked up in that keymap.  

(@strong{But what happens if there is no hit there, I can not find any
documentation on this???})

Here is a Pseudo-Lisp description of the order in which the active keymaps are 
searched:

@lisp
(or (if overriding-terminal-local-map
        (FIND-IN overriding-terminal-local-map)
      (if overriding-local-map
          (FIND-IN overriding-local-map)
        (or (FIND-IN (get-text-property (point) 'keymap))
            (FIND-IN-ANY emulation-mode-map-alists)
            (FIND-IN-ANY minor-mode-overriding-map-alist)
            (FIND-IN-ANY minor-mode-map-alist)
            (FIND-IN (get-text-property (point) 'local-map))
            (FIND-IN (current-local-map)))))
    (FIND-IN (current-global-map)))
@end lisp

@noindent
The FIND-IN and FIND-IN-ANY are pseudo functions that searches in one
keymap respectively an alist of keymaps.

@noindent
@strong{Remark 1:} When Emacs finally find a function symbol through
this process it also checks for command remapping (@pxref{Remapping
Commands}).  This just replaces the function symbol with another.  It
is not recursive.

@noindent
@strong{Remark 2:} Characters that are bound to
@code{self-insert-command} are translated according to
@code{translation-table-for-input} before insertion.

@noindent
@strong{Remark 3:} You may find the function
@code{current-active-maps} useful when looking into this.