Crate keymap_core 

keymap-core

The pure, state-free core of the keymap-rs family: a normalized key-input vocabulary (Key, Modifiers, KeyInput) and a generic binding table (Keymap) that maps inputs to a caller-defined action type A.

This crate deliberately knows nothing about terminals, config files, or rendering. Those live in sibling crates (keymap-term, keymap-config, keymap-ratatui). The action type is never defined here — you bring your own A (typically an enum), so the library never pulls your domain into itself.

Phase 0 scope

Today this crate offers single-key resolution by lookup:

use keymap_core::{Key, KeyInput, Keymap, Modifiers};

#[derive(Clone, PartialEq, Debug)]
enum Action { Quit, Save }

let mut map = Keymap::new();
map.bind(KeyInput::new(Key::Char('q'), Modifiers::CTRL), Action::Quit);

let hit = KeyInput::new(Key::Char('q'), Modifiers::CTRL);
assert_eq!(map.get(&hit), Some(&Action::Quit));

// A miss is an absence, not an error: the caller passes the key through.
let miss = KeyInput::new(Key::Char('x'), Modifiers::NONE);
assert_eq!(map.get(&miss), None);

For a terminal multiplexer, resolve_passthrough is the raw-byte-carrying sibling of resolve_layered: a miss carries the original bytes out as Resolution::Passthrough for verbatim forwarding to the PTY sink, rather than collapsing to None. Terminal-capability-aware reachability diagnostics and multi-key prefix sequences arrive in sibling crates (keymap-term, keymap-seq). Resolution is deliberately exhaustive (its three dispositions are the complete set), so unlike most public types here it is not #[non_exhaustive] — see its docs.

Runnable examples

Each scenario above has a runnable counterpart under examples/: basic_lookup, modal_keymap, discovery, ex_command, command_palette. Run e.g. cargo run -p keymap-core --example modal_keymap. The examples are exercised by cargo test --workspace, so they cannot silently drift from the API.

Modules

cmd

Command name → action index with front-prefix completion.

Structs

KeyInput

A normalized key press: a Key plus the Modifiers held with it.

Keymap

A table mapping normalized KeyInputs to a caller-defined action A.

Modifiers

A set of held modifier keys.

ParseKeyInputError

Error returned when a string cannot be parsed into a KeyInput.

RawInput

The original, pre-decode bytes of a key press, borrowed from the caller’s read buffer, to be forwarded verbatim when no layer binds the input.

Enums

BreakReason

Why a proposed rebind would break a reserved key.

Key

A physical key, independent of which terminal or OS produced it.

LegacyForm

How a KeyInput survives the legacy 7-bit C0 terminal encoding, independent of any enhanced protocol. See the module docs.

LegacyLint

A bound chord that will not survive a legacy 7-bit (C0) terminal, reported by legacy_lints. The variants mirror the two lossy LegacyForm cases (a Representable chord produces no lint).

RebindVerdict

What validate_rebind concluded.

Resolution

What should happen to a key press, for a caller that forwards unbound input to a terminal sink (a PTY). The disposition counterpart to resolve_layered’s bare Option<&A>.

Functions

legacy_lints

Reports every bound chord in keymap that will not survive a legacy 7-bit (C0) terminal, derived purely from KeyInput::legacy_form — a structural fact needing no terminal measurement, so this is stable and CI-testable.

resolve_layered

Resolves input against an ordered list of keymap layers, returning the first match (earlier layers win).

resolve_passthrough

Resolves input against an ordered list of layers for a caller that forwards unbound keys to a terminal sink (a PTY), carrying the original raw bytes so a miss can be forwarded verbatim.

validate_rebind

Validates a proposed rebind of proposed into layer layers[target] without mutating the live keymap or requiring A: Clone or A: PartialEq.