NKeymaps

This keymap library is inspired by Emacsy (keymap.scm), which in turn is inspired by Emacs.

The main types are:

• A key structure that holds:

  a numeric code

  a hardware keycode;

  a string value

  a character (except for whitespaces);

  • an ordered set of modifiers (to ensure equality on permutation).
• A keyspec is a string representation of a key (e.g. “control-a”). A keyspecs is the string concatenation of two or more =keyspec=s (e.g. “control-a control-b control-c”).
• A keymap contains a hash-table that maps keyspecs to either keymaps, function designators or nil (to unbind the keyspecs).

Goals

• Define keymaps with a prefix key (commonly known as prefix keymaps). For instance, my-mode-map can be defined as a prefix keymap that makes all of its bindings accessible after pressing C-c.
• List all bindings matching a given prefix.
• List the bindings associated to a command.
• Multiple inheritance.
• Keycode support.
• Validate keyspec at compile time.
• Set multiple bindings in a single call to define-key.
• Multiple keyschemes to make it easy to switch between, say, Emacs-style and VI-style bindings. This orthogonality to keymaps composes better than having multiple keymaps: changing keyscheme applies to the entire program, which is easier than looping through all keymaps to change them.
• Translate keyspecs as a fallback. For instance if shift-a is unbound, check A.
• Customizable behaviour with global parameters such as *print-shortcut*.
• Merge multiple keymaps via compose.
• Handle gracefully multiple arguments when sensible (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.

Non-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 gets nil 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 the locality of their keymaps.

Example

(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)
   (nkeymaps:binding-keys 'cut parent-keymap)
   (nkeymaps:binding-keys 'copy my-keymap)
   (nkeymaps:binding-keys 'paste my-keymap)))

;; => NIL, CUT, COPY, NIL, ("C-c"), ("C-v")

See the package documentation for a usage guide and more examples.

History

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!

Road-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 the keyscheme and keymap. But this would impact the lookup order, since translations come after all the keymaps and their parents have been searched for.

Change log

1.1.1

• Remove NASDF as a dependency.
• Minor fix relative to pretty-binding-keys.

1.1.0

• New pretty-binding-keys function that prints keybindings using OS-dependent modifier terminology.
• Improve documentation.
• Add NASDF as a dependency.
• Add cl-str as a dependency.

1.0.0

• Renamed scheme-name to keyscheme and scheme to keyscheme-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 (including cua), instead of cua.
• *modifier-list* is no longer exported. Instead, both keyscheme and keymap have a modifiers slot for the modifiers they accept.
• Switched testing framework from Prove to Lisp-Unit2.
• Removed the cl-str dependency.