Crate keymap_config 

keymap-config

Builds a Keymap from a TOML [keys] table, resolving action names with a caller-supplied function and reporting problems that should not silently pass.

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

let toml = r#"
[keys]
"ctrl+q" = "quit"
"ctrl+s" = "save"
"#;

let out = keymap_config::from_str(toml, |name| match name {
    "quit" => Some(Action::Quit),
    "save" => Some(Action::Save),
    _ => None,
})
.unwrap();

assert!(out.warnings.is_empty());

Named layers

Bindings live in layers. The bare top-level [keys] table is the GLOBAL_LAYER layer; additional [layers.<name>] tables each build a layer of that name, holding chord→action entries directly:

[keys]               # the implicit "global" layer
"ctrl+q" = "quit"

[layers.panel]       # a caller-named layer
"ctrl+s" = "split"

from_str returns these as BuildOutput::layers, a name→Keymap map always containing "global". Which layers are active, and in what order, is not this crate’s concern: the caller picks them per event and resolves with keymap_core::resolve_layered (first layer to bind a chord wins, misses fall through). The same chord in two layers is therefore an override, not a conflict — this crate only ever reports conflicts within a single layer. Layer names are opaque labels; the library attaches meaning to none of them.

What is an error versus a warning

Structural problems — malformed TOML, or a key string that does not parse — are BuildError: there is no usable map to return. Survivable problems — two keys resolving to the same chord, or an action name the resolver does not recognize — are collected into BuildOutput::warnings so the rest of the bindings still work and the user can be told what to fix.

Legacy-terminal survivability (opt-in, separate from warnings)

“This binding won’t survive a legacy terminal” (e.g. a cmd+… chord a legacy terminal cannot deliver, or ctrl+i which is indistinguishable from tab) is deliberately not a Warning: it depends on the deployment terminal, not the config’s correctness, and folding it into BuildOutput::warnings would make a perfectly good config report warnings. It is exposed instead as the opt-in keymap_core::legacy_lints, which you call on a built keymap when you want it: keymap_core::legacy_lints(out.global()) (or on any one layer). Callers gating on warnings.is_empty() are unaffected.

Multi-key sequences

Alongside the single-chord [keys] table, an [[sequences]] array of tables binds sequences of chords (leader trees, ctrl+x ctrl+s) into a SequenceKeymap, returned as BuildOutput::sequences:

[keys]
"ctrl+q" = "quit"

[[sequences]]
keys = ["ctrl+x", "ctrl+s"]
action = "save"

Each element of keys reuses the single-chord grammar, so no new key syntax is introduced. Two sequence bindings that share a prefix cannot coexist without a timeout (see keymap-seq); such a pair is reported as Warning::PrefixShadow and the later one is dropped. A single-key binding that shadows a sequence (e.g. "j" in [keys] versus a sequence starting with j) is reported as the advisory Warning::SequenceShadow — both bindings are kept (they live in separate maps), so it only flags that the caller composing the two maps must resolve the overlap with a timeout.

Runnable examples

Under examples/: cargo run -p keymap-config --example load_config walks the TOML-to-keymap pipeline end to end, and --example rebind shows the runtime-rebind flow on top of keymap_term::decode.

Structs

BuildOutput

The result of a successful build: the named layers plus any non-fatal warnings.

Merged

The result of a merge operation: the merged output plus advisory notes.

Enums

BuildError

A fatal problem that prevents building a Keymap.

MergeNote

An advisory note emitted by merge.

Warning

A non-fatal problem found while building a Keymap.

WarningKind

A category tag for a Warning, without the field data.

Constants

GLOBAL_LAYER

The name of the layer built from the top-level [keys] table.

Functions

from_str

Builds a Keymap from a TOML string.

merge

Merges a base (defaults) BuildOutput with an overlay (user config) BuildOutput, returning the combined result with advisory notes.

to_toml

Serializes a Keymap and SequenceKeymap back into a TOML config string — the inverse of from_str.

to_toml_layered

Serializes a named-layer set and the global SequenceKeymap back into a TOML config string — the inverse of from_str for a multi-layer config.

to_toml_layered_with_unbinds

Serializes a named-layer set, the global SequenceKeymap, and any unbind declarations ("chord" = false) back into a TOML config string.