Struct SequenceKeymap 

#[non_exhaustive]
pub struct SequenceKeymap<A> { /* private fields */ }

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

This is the sequence-level analogue of keymap_core::Keymap: state-free, with the action type A brought by the caller. It is prefix-free by construction — see SequenceKeymap::bind and the crate-level docs — so lookup never needs a timeout to disambiguate.

Implementations

impl<A> SequenceKeymap<A>

pub fn new() -> Self

Creates an empty sequence map.

Examples found in repository

examples/leader_sequence.rs (line 40)

fn untimed() {
    println!("== untimed ==");
    let mut map = SequenceKeymap::new();
    map.bind([ctrl('x'), ctrl('s')], Action::Save).unwrap();
    map.bind([ctrl('x'), ctrl('c')], Action::Quit).unwrap();
    map.bind([plain('g'), plain('g')], Action::GotoTop).unwrap();

    // A stream a terminal might deliver: a completed save, an abandoned prefix
    // (`ctrl+x` then an unrelated key), then `g g`.
    let stream = [
        ctrl('x'),
        ctrl('s'),
        ctrl('x'),
        plain('z'),
        plain('g'),
        plain('g'),
    ];

    let mut pending: Vec<KeyInput> = Vec::new();
    for key in stream {
        pending.push(key);
        match map.lookup(&pending) {
            Match::Exact(action) => {
                println!("{} -> fire {action:?}", render(&pending));
                pending.clear();
            }
            Match::Prefix => {
                println!("{} -> prefix, waiting", render(&pending));
            }
            Match::NoMatch => {
                println!("{} -> no binding, passing through", render(&pending));
                pending.clear();
            }
        }
    }
}

/// `jj`-style time window using [`TimedPending`].
///
/// [`TimedPending`] bundles the expiry check, flush, and new-key processing
/// into a single `feed` call. The library still holds no clock — `now` is
/// caller-supplied data (a `base + offset` pair here, so the demo is
/// deterministic and never flaky).
///
/// Note what this demo does *not* do: real vim `jj` also binds `j` on its own
/// (a literal cursor move). That needs both `j` *and* `[j, j]` bound — which
/// the prefix-free invariant forbids (`bind` rejects it with `PrefixShadow`).
/// Here `j` alone is unbound, so the timeout is the *only* caller policy needed.
fn timed() {
    const WINDOW: Duration = Duration::from_millis(500);

    println!("== timed (jj, via TimedPending) ==");
    let mut map = SequenceKeymap::new();
    map.bind([plain('j'), plain('j')], Action::NormalMode)
        .unwrap();

    // Deterministic timestamps: base + offset (no real sleep / Instant::now).
    let base = Instant::now();
    let stream = [
        (plain('j'), 0u64),
        (plain('j'), 120), // 120ms gap: quick, completes `jj`
        (plain('j'), 900),
        (plain('j'), 1700), // 800ms gap: too slow, expiry fires
    ];

    let mut pending = TimedPending::new();
    for (key, ms) in stream {
        let now = base + Duration::from_millis(ms);
        let result = pending.feed(&map, key, now, WINDOW);

        // If a previous prefix expired, report its keys as literals first.
        if let Some(expired) = result.expired {
            println!(
                "{} @ +{ms}ms -> idle timeout, flushed as literals",
                render(&expired),
            );
        }

        match result.step {
            Step::Fired(action) => println!("{key} @ +{ms}ms -> fire {action:?}"),
            Step::Pending => println!("{key} @ +{ms}ms -> prefix, waiting (window {WINDOW:?})"),
            Step::PassThrough(keys) => {
                println!("{} @ +{ms}ms -> no binding, passing through", render(&keys));
            }
        }
    }

    // The stream ended mid-prefix. Drain as literals (what an idle timer does).
    let dangling = pending.flush();
    if !dangling.is_empty() {
        println!(
            "{} -> pending at end; flushed as literals",
            render(&dangling)
        );
    }
}

pub fn is_empty(&self) -> bool

Returns true if no sequences are bound.

pub fn bind( &mut self, sequence: impl IntoIterator<Item = KeyInput>, action: A, ) -> Result<Option<A>, SeqBindError>

Binds a key sequence to action.

Re-binding the exact same sequence overwrites and returns the previous action, mirroring keymap_core::Keymap::bind.

Errors

• SeqBindError::Empty if sequence yields no keys.
• SeqBindError::PrefixShadow if the new sequence would be a proper prefix of an existing binding, or an existing binding would be a proper prefix of it. Either case is unresolvable without a timeout (see the crate docs), so it is rejected rather than silently shadowed; the map is left unchanged.

Examples found in repository

examples/leader_sequence.rs (line 41)

fn untimed() {
    println!("== untimed ==");
    let mut map = SequenceKeymap::new();
    map.bind([ctrl('x'), ctrl('s')], Action::Save).unwrap();
    map.bind([ctrl('x'), ctrl('c')], Action::Quit).unwrap();
    map.bind([plain('g'), plain('g')], Action::GotoTop).unwrap();

    // A stream a terminal might deliver: a completed save, an abandoned prefix
    // (`ctrl+x` then an unrelated key), then `g g`.
    let stream = [
        ctrl('x'),
        ctrl('s'),
        ctrl('x'),
        plain('z'),
        plain('g'),
        plain('g'),
    ];

    let mut pending: Vec<KeyInput> = Vec::new();
    for key in stream {
        pending.push(key);
        match map.lookup(&pending) {
            Match::Exact(action) => {
                println!("{} -> fire {action:?}", render(&pending));
                pending.clear();
            }
            Match::Prefix => {
                println!("{} -> prefix, waiting", render(&pending));
            }
            Match::NoMatch => {
                println!("{} -> no binding, passing through", render(&pending));
                pending.clear();
            }
        }
    }
}

/// `jj`-style time window using [`TimedPending`].
///
/// [`TimedPending`] bundles the expiry check, flush, and new-key processing
/// into a single `feed` call. The library still holds no clock — `now` is
/// caller-supplied data (a `base + offset` pair here, so the demo is
/// deterministic and never flaky).
///
/// Note what this demo does *not* do: real vim `jj` also binds `j` on its own
/// (a literal cursor move). That needs both `j` *and* `[j, j]` bound — which
/// the prefix-free invariant forbids (`bind` rejects it with `PrefixShadow`).
/// Here `j` alone is unbound, so the timeout is the *only* caller policy needed.
fn timed() {
    const WINDOW: Duration = Duration::from_millis(500);

    println!("== timed (jj, via TimedPending) ==");
    let mut map = SequenceKeymap::new();
    map.bind([plain('j'), plain('j')], Action::NormalMode)
        .unwrap();

    // Deterministic timestamps: base + offset (no real sleep / Instant::now).
    let base = Instant::now();
    let stream = [
        (plain('j'), 0u64),
        (plain('j'), 120), // 120ms gap: quick, completes `jj`
        (plain('j'), 900),
        (plain('j'), 1700), // 800ms gap: too slow, expiry fires
    ];

    let mut pending = TimedPending::new();
    for (key, ms) in stream {
        let now = base + Duration::from_millis(ms);
        let result = pending.feed(&map, key, now, WINDOW);

        // If a previous prefix expired, report its keys as literals first.
        if let Some(expired) = result.expired {
            println!(
                "{} @ +{ms}ms -> idle timeout, flushed as literals",
                render(&expired),
            );
        }

        match result.step {
            Step::Fired(action) => println!("{key} @ +{ms}ms -> fire {action:?}"),
            Step::Pending => println!("{key} @ +{ms}ms -> prefix, waiting (window {WINDOW:?})"),
            Step::PassThrough(keys) => {
                println!("{} @ +{ms}ms -> no binding, passing through", render(&keys));
            }
        }
    }

    // The stream ended mid-prefix. Drain as literals (what an idle timer does).
    let dangling = pending.flush();
    if !dangling.is_empty() {
        println!(
            "{} -> pending at end; flushed as literals",
            render(&dangling)
        );
    }
}

pub fn lookup(&self, keys: &[KeyInput]) -> Match<'_, A>

Resolves the keys pressed so far against the table.

keys is the caller’s pending buffer. The result is one of:

• Match::Exact — keys is a complete binding; the caller should fire it and clear the buffer.
• Match::Prefix — keys is a proper prefix of one or more bindings; the caller should keep buffering (and, for timed bindings, run its timer).
• Match::NoMatch — keys is not on any binding path; the caller should clear the buffer and handle the keys itself (e.g. pass through).

Examples found in repository

examples/leader_sequence.rs (line 59)

fn untimed() {
    println!("== untimed ==");
    let mut map = SequenceKeymap::new();
    map.bind([ctrl('x'), ctrl('s')], Action::Save).unwrap();
    map.bind([ctrl('x'), ctrl('c')], Action::Quit).unwrap();
    map.bind([plain('g'), plain('g')], Action::GotoTop).unwrap();

    // A stream a terminal might deliver: a completed save, an abandoned prefix
    // (`ctrl+x` then an unrelated key), then `g g`.
    let stream = [
        ctrl('x'),
        ctrl('s'),
        ctrl('x'),
        plain('z'),
        plain('g'),
        plain('g'),
    ];

    let mut pending: Vec<KeyInput> = Vec::new();
    for key in stream {
        pending.push(key);
        match map.lookup(&pending) {
            Match::Exact(action) => {
                println!("{} -> fire {action:?}", render(&pending));
                pending.clear();
            }
            Match::Prefix => {
                println!("{} -> prefix, waiting", render(&pending));
            }
            Match::NoMatch => {
                println!("{} -> no binding, passing through", render(&pending));
                pending.clear();
            }
        }
    }
}

pub fn bindings(&self) -> impl Iterator<Item = (Vec<KeyInput>, &A)>

Enumerates every bound sequence as a (path, action) pair — the sequence-level dual of keymap_core::Keymap::iter.

Each yielded Vec<KeyInput> is a complete bound sequence (a leaf path); by the prefix-free invariant it is never a partial prefix. Unlike Keymap::iter, which can borrow its stored key, a trie path is reconstructed during traversal, so each item owns its Vec and borrows only the action.

Order is unspecified (the trie’s children live in a HashMap); collect and sort caller-side for stable output. This is the data source for listing, search, and serialization on top of keymap-seq.

pub fn continuations( &self, prefix: &[KeyInput], ) -> impl Iterator<Item = (KeyInput, Continuation<'_, A>)>

Enumerates the keys that may immediately follow prefix, for rendering a which-key-style menu of what can be pressed next.

Each item is a KeyInput that extends prefix by one, paired with what pressing it does: complete a binding (Continuation::Action, carrying the action) or open a deeper prefix (Continuation::Prefix).

The iterator is empty when prefix does not name an internal node — whether it is off the tree, already completes a binding (a leaf has no children), or the map is empty. continuations deliberately does not re-encode that distinction; call lookup to tell those apart.

Order is unspecified (the children live in a HashMap); collect and sort caller-side for a stable menu.

use keymap_core::{Key, KeyInput, Modifiers};
use keymap_seq::{Continuation, SequenceKeymap};

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

let k = |c| KeyInput::new(Key::Char(c), Modifiers::NONE);
let mut map = SequenceKeymap::new();
map.bind([k('a'), k('b')], Action::Save).unwrap();
map.bind([k('c')], Action::Quit).unwrap();

// From the root: `a` opens a deeper prefix, `c` completes a binding.
let mut next: Vec<_> = map.continuations(&[]).collect();
next.sort_by_key(|(key, _)| key.to_string());
assert_eq!(
    next,
    vec![
        (k('a'), Continuation::Prefix),
        (k('c'), Continuation::Action(&Action::Quit)),
    ],
);

// A completed binding has no continuations.
assert_eq!(map.continuations(&[k('c')]).count(), 0);

Trait Implementations

impl<A: Clone> Clone for SequenceKeymap<A>

fn clone(&self) -> SequenceKeymap<A>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Debug> Debug for SequenceKeymap<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A> Default for SequenceKeymap<A>

fn default() -> Self

Returns the “default value” for a type.