nkeymaps
2023-02-15
General-purpose keymap management à-la Emacs.
NKeymaps
This keymap library is inspired by Emacsy (keymap.scm
), which in turn is
inspired by Emacs.
The main types are:
- A
key
structure has a hardwarecode
, a symbolicvalue
, an ordered set ofmodifiers (the order is to avoid inequality on permutation) and possibly morein the future.Whitespaces are the only reserved characters. Anything else can be stored in the
key
value. - A
keyspec
is a string representation of akey
. Akeyspec
is aspace-separated string representation of a sequence of =key=s. - A
keymap
contains a hash-table where the keys are akeyspec
and the valuesare either a keymap or anything else. As a special case, anil
valueunbinds the key.
0.1Goals
- Support prefix keys to other keymaps. For instance, prefixing my-mode-mapwith
C-c
makes all bindings for my-mode accessible after pressingC-c
. - List all bindings matching a given prefix. (Also known as
which-key
inEmacs.) - List the bindings associated to a command.
- Support multiple inheritance.
- Support keycode.
- Validate keyspec at compile time.
define-key
can set multiple bindings in a single call.- Support multiple keyschemes to make it easy to switch between, say, Emacs-styleand VI-style bindings. This orthogonality to keymaps composes better thanhaving multiple keymaps: changing keyscheme applies to the entire program, whichis easier than looping through all keymaps to change them.
- Translate keyspecs as a fallback. For instance if
shift-a
is unbound, checkA
. - Customizable behaviour with global parameters such as
*print-shortcut*
. - The
compose
function can merge multiple keymaps together. - Support multiple arguments when that makes sense (e.g. multiple keymaps for
lookup-key
). - Key remapping à-la Emacs.
- Typed keymaps, i.e. keymaps where bound values can only be of a given type.This is convenient to catch typos, for instance when binding ='FOO= instead of
#'FOO
.
0.2Non-goals
- Customizable modifiers: the input system must decide how to map
meta
,control
, etc. - Dead key support: the input system must handle it.
- Fallback function when binding is not found: the caller of
lookup-key
getsnil
when unbound, thus it can decide of a default behaviour. - Provide a self-insert function: the caller must handle it.
- Global or local bindings: it's up to the calling application to manage thelocality of their keymaps.
0.3Example
(let* ((parent-keymap (nkeymaps:make-keymap "parent-keymap"))
(my-keymap (nkeymaps:make-keymap "my-keymap" parent-keymap)))
(nkeymaps:define-key parent-keymap
"C-c" 'copy
"C-v" 'paste)
(nkeymaps:define-key my-keymap
"C-x" 'cut)
(values
(nkeymaps:lookup-key "C-x" parent-keymap)
(nkeymaps:lookup-key "C-x" my-keymap)
(nkeymaps:lookup-key "C-c" my-keymap)))
;; => NIL, CUT, COPY
See the package documentation for a usage guide and more examples.
0.4History
NKeymaps was originally developed for keymap management in Nyxt, so the "N" may stand for it, or "New", or whatever poetic meaning you may find behind it!
0.5Road-map
- Lookup order (for instance parent-first or next-keymap-first) should be customizable.
- For now
*translator*
is a global, but ideally it would be part of thekeyscheme and keymap. But this would impact the lookup order, sincetranslations come after all the keymaps and their parents have been searched for.
0.6Change log
0.6.11.0.0
- Renamed
scheme-name
tokeyscheme
andscheme
tokeyscheme-map
.It's more consistent and intuitive. The previous naming was really confusing. - All warnings have now their own conditions, see the
nkeymaps/conditions
package. define-keyscheme-map
has a different syntax, it's now(define-keyscheme-map "NAME-PREFIX" (:import OPTIONAL-KEYSCHEME-MAP-TO-IMPORT) KEYSCHEME BINDINGS...)
- The predefined
keyscheme=s are now accessible from the =nkeymaps
package. - New
default
=keyscheme= which is the new parent of other keyschemes(includingcua
), instead ofcua
. *modifier-list*
is no longer exported. Instead, bothkeyscheme
andkeymap
have amodifiers
slot for the modifiers they accept.- Switched testing framework from
Prove
toLisp-Unit2
. - Removed the
cl-str
dependency.