Struct Keymap 

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

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

Keymap is state-free: it answers “what is bound to this input?” and nothing more. Deciding whether to consume the action or pass the input through, and tracking modes or multi-key sequences, is the caller’s concern (and the job of later layers). A lookup miss is an absence (None), not an error — the caller treats it as “pass through”.

The action type A is yours. The struct itself places no bound on A; bounds appear only on the methods that need them.

Implementations

impl<A> Keymap<A>

pub fn new() -> Self

Creates an empty keymap.

Examples found in repository

examples/basic_lookup.rs (line 16)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(KeyInput::new(Key::Char('q'), Modifiers::CTRL), Action::Quit);
    keymap.bind(KeyInput::new(Key::Char('s'), Modifiers::CTRL), Action::Save);
    keymap.bind(
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        Action::SplitPane,
    );

    // In a real app these come from the terminal backend (see the `crossterm`
    // feature's `TryFrom<KeyEvent>`); here we construct them directly.
    let inputs = [
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        KeyInput::new(Key::Char('x'), Modifiers::NONE),
    ];

    for input in inputs {
        match keymap.get(&input) {
            Some(action) => println!("{input:>8}  ->  consume {action:?}"),
            None => println!("{input:>8}  ->  pass through"),
        }
    }
}

examples/discovery.rs (line 16)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        Command {
            id: "quit",
            description: "Quit the application",
        },
    );
    keymap.bind(
        KeyInput::new(Key::Char('s'), Modifiers::CTRL),
        Command {
            id: "save",
            description: "Save the current file",
        },
    );
    keymap.bind(
        KeyInput::new(Key::F(1), Modifiers::NONE),
        Command {
            id: "help",
            description: "Show the help overlay",
        },
    );

    // Listing: collect and sort by the canonical key string.
    let mut listing: Vec<(String, &Command)> = keymap
        .iter()
        .map(|(input, cmd)| (input.to_string(), cmd))
        .collect();
    listing.sort_by(|a, b| a.0.cmp(&b.0));

    println!("all bindings:");
    for (key, cmd) in &listing {
        println!("  {key:>8}  {:<6} — {}", cmd.id, cmd.description);
    }

    search(&listing, "sav");
    search(&listing, "zzz");
}

examples/modal_keymap.rs (line 39)

fn main() {
    // Base layer: shared bindings live here once.
    let mut base = Keymap::new();
    base.bind(ctrl('s'), Action::Save);
    base.bind(ctrl('q'), Action::Quit);

    // Panel layer: only the overrides for panel context.
    let mut panel = Keymap::new();
    panel.bind(ctrl('s'), Action::SplitPanel);

    // The app maps its context to an ordered layer stack. This `match` is the
    // only place "context" exists — entirely on the application side.
    let layers_for = |ctx: &Context| -> Vec<&Keymap<Action>> {
        match ctx {
            Context::Editor => vec![&base],
            Context::Panel => vec![&panel, &base],
        }
    };

    for ctx in [Context::Editor, Context::Panel] {
        let name = match ctx {
            Context::Editor => "editor",
            Context::Panel => "panel",
        };
        let layers = layers_for(&ctx);
        for key in [ctrl('s'), ctrl('q')] {
            match resolve_layered(layers.iter().copied(), &key) {
                Some(action) => println!("[{name:>6}] {key:>6}  ->  {action:?}"),
                None => println!("[{name:>6}] {key:>6}  ->  pass through"),
            }
        }
    }
}

examples/ex_command.rs (line 58)

fn main() {
    let mut map = Keymap::new();
    map.bind(plain(':'), Action::EnterCommandMode);

    // Stage 3's resolver: command name -> action. Same shape as
    // `keymap_config`'s `FnMut(&str) -> Option<A>`, intentionally a plain
    // closure rather than that crate's type.
    let resolve = |name: &str| -> Option<Action> {
        match name {
            "w" => Some(Action::Write),
            "q" => Some(Action::Quit),
            "wq" => Some(Action::WriteQuit),
            _ => None,
        }
    };

    // A simulated keystroke stream: `:wq⏎`, then `:q⏎`, then an unknown `:zz⏎`.
    let stream = [
        plain(':'),
        plain('w'),
        plain('q'),
        enter(),
        plain(':'),
        plain('q'),
        enter(),
        plain(':'),
        plain('z'),
        plain('z'),
        enter(),
    ];

    let mut mode = Mode::Normal;
    for key in stream {
        match &mut mode {
            Mode::Normal => {
                if map.get(&key) == Some(&Action::EnterCommandMode) {
                    println!(": -> enter command mode");
                    mode = Mode::Command(String::new());
                } else {
                    // Any other normal-mode key would run its own binding; this
                    // demo only cares about the `:` entry point.
                }
            }
            Mode::Command(buf) => match key.key() {
                Key::Char(c) => {
                    buf.push(c);
                    println!("  :{buf}");
                }
                Key::Enter => {
                    // Take the buffer out and drop back to Normal in one move.
                    let name = std::mem::take(buf);
                    match resolve(&name) {
                        Some(action) => println!("  :{name} -> fire {action:?}"),
                        None => println!("  :{name} -> unknown command, no-op"),
                    }
                    mode = Mode::Normal;
                }
                Key::Esc => {
                    println!("  esc -> abandon command line");
                    mode = Mode::Normal;
                }
                // `Key` is #[non_exhaustive]; other editing keys are ignored here.
                _ => {}
            },
        }
    }
}

pub fn bind(&mut self, input: KeyInput, action: A) -> Option<A>

Binds input to action, returning the action previously bound to that input, if any.

Examples found in repository

examples/basic_lookup.rs (line 17)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(KeyInput::new(Key::Char('q'), Modifiers::CTRL), Action::Quit);
    keymap.bind(KeyInput::new(Key::Char('s'), Modifiers::CTRL), Action::Save);
    keymap.bind(
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        Action::SplitPane,
    );

    // In a real app these come from the terminal backend (see the `crossterm`
    // feature's `TryFrom<KeyEvent>`); here we construct them directly.
    let inputs = [
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        KeyInput::new(Key::Char('x'), Modifiers::NONE),
    ];

    for input in inputs {
        match keymap.get(&input) {
            Some(action) => println!("{input:>8}  ->  consume {action:?}"),
            None => println!("{input:>8}  ->  pass through"),
        }
    }
}

examples/discovery.rs (lines 17-23)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        Command {
            id: "quit",
            description: "Quit the application",
        },
    );
    keymap.bind(
        KeyInput::new(Key::Char('s'), Modifiers::CTRL),
        Command {
            id: "save",
            description: "Save the current file",
        },
    );
    keymap.bind(
        KeyInput::new(Key::F(1), Modifiers::NONE),
        Command {
            id: "help",
            description: "Show the help overlay",
        },
    );

    // Listing: collect and sort by the canonical key string.
    let mut listing: Vec<(String, &Command)> = keymap
        .iter()
        .map(|(input, cmd)| (input.to_string(), cmd))
        .collect();
    listing.sort_by(|a, b| a.0.cmp(&b.0));

    println!("all bindings:");
    for (key, cmd) in &listing {
        println!("  {key:>8}  {:<6} — {}", cmd.id, cmd.description);
    }

    search(&listing, "sav");
    search(&listing, "zzz");
}

examples/modal_keymap.rs (line 40)

fn main() {
    // Base layer: shared bindings live here once.
    let mut base = Keymap::new();
    base.bind(ctrl('s'), Action::Save);
    base.bind(ctrl('q'), Action::Quit);

    // Panel layer: only the overrides for panel context.
    let mut panel = Keymap::new();
    panel.bind(ctrl('s'), Action::SplitPanel);

    // The app maps its context to an ordered layer stack. This `match` is the
    // only place "context" exists — entirely on the application side.
    let layers_for = |ctx: &Context| -> Vec<&Keymap<Action>> {
        match ctx {
            Context::Editor => vec![&base],
            Context::Panel => vec![&panel, &base],
        }
    };

    for ctx in [Context::Editor, Context::Panel] {
        let name = match ctx {
            Context::Editor => "editor",
            Context::Panel => "panel",
        };
        let layers = layers_for(&ctx);
        for key in [ctrl('s'), ctrl('q')] {
            match resolve_layered(layers.iter().copied(), &key) {
                Some(action) => println!("[{name:>6}] {key:>6}  ->  {action:?}"),
                None => println!("[{name:>6}] {key:>6}  ->  pass through"),
            }
        }
    }
}

examples/ex_command.rs (line 59)

fn main() {
    let mut map = Keymap::new();
    map.bind(plain(':'), Action::EnterCommandMode);

    // Stage 3's resolver: command name -> action. Same shape as
    // `keymap_config`'s `FnMut(&str) -> Option<A>`, intentionally a plain
    // closure rather than that crate's type.
    let resolve = |name: &str| -> Option<Action> {
        match name {
            "w" => Some(Action::Write),
            "q" => Some(Action::Quit),
            "wq" => Some(Action::WriteQuit),
            _ => None,
        }
    };

    // A simulated keystroke stream: `:wq⏎`, then `:q⏎`, then an unknown `:zz⏎`.
    let stream = [
        plain(':'),
        plain('w'),
        plain('q'),
        enter(),
        plain(':'),
        plain('q'),
        enter(),
        plain(':'),
        plain('z'),
        plain('z'),
        enter(),
    ];

    let mut mode = Mode::Normal;
    for key in stream {
        match &mut mode {
            Mode::Normal => {
                if map.get(&key) == Some(&Action::EnterCommandMode) {
                    println!(": -> enter command mode");
                    mode = Mode::Command(String::new());
                } else {
                    // Any other normal-mode key would run its own binding; this
                    // demo only cares about the `:` entry point.
                }
            }
            Mode::Command(buf) => match key.key() {
                Key::Char(c) => {
                    buf.push(c);
                    println!("  :{buf}");
                }
                Key::Enter => {
                    // Take the buffer out and drop back to Normal in one move.
                    let name = std::mem::take(buf);
                    match resolve(&name) {
                        Some(action) => println!("  :{name} -> fire {action:?}"),
                        None => println!("  :{name} -> unknown command, no-op"),
                    }
                    mode = Mode::Normal;
                }
                Key::Esc => {
                    println!("  esc -> abandon command line");
                    mode = Mode::Normal;
                }
                // `Key` is #[non_exhaustive]; other editing keys are ignored here.
                _ => {}
            },
        }
    }
}

pub fn unbind(&mut self, input: &KeyInput) -> Option<A>

Removes any binding for input, returning the action that was bound.

pub fn get(&self, input: &KeyInput) -> Option<&A>

Returns the action bound to input, or None if the input is unbound.

Examples found in repository

examples/basic_lookup.rs (line 33)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(KeyInput::new(Key::Char('q'), Modifiers::CTRL), Action::Quit);
    keymap.bind(KeyInput::new(Key::Char('s'), Modifiers::CTRL), Action::Save);
    keymap.bind(
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        Action::SplitPane,
    );

    // In a real app these come from the terminal backend (see the `crossterm`
    // feature's `TryFrom<KeyEvent>`); here we construct them directly.
    let inputs = [
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        KeyInput::new(Key::Char('1'), Modifiers::SUPER),
        KeyInput::new(Key::Char('x'), Modifiers::NONE),
    ];

    for input in inputs {
        match keymap.get(&input) {
            Some(action) => println!("{input:>8}  ->  consume {action:?}"),
            None => println!("{input:>8}  ->  pass through"),
        }
    }
}

examples/ex_command.rs (line 92)

fn main() {
    let mut map = Keymap::new();
    map.bind(plain(':'), Action::EnterCommandMode);

    // Stage 3's resolver: command name -> action. Same shape as
    // `keymap_config`'s `FnMut(&str) -> Option<A>`, intentionally a plain
    // closure rather than that crate's type.
    let resolve = |name: &str| -> Option<Action> {
        match name {
            "w" => Some(Action::Write),
            "q" => Some(Action::Quit),
            "wq" => Some(Action::WriteQuit),
            _ => None,
        }
    };

    // A simulated keystroke stream: `:wq⏎`, then `:q⏎`, then an unknown `:zz⏎`.
    let stream = [
        plain(':'),
        plain('w'),
        plain('q'),
        enter(),
        plain(':'),
        plain('q'),
        enter(),
        plain(':'),
        plain('z'),
        plain('z'),
        enter(),
    ];

    let mut mode = Mode::Normal;
    for key in stream {
        match &mut mode {
            Mode::Normal => {
                if map.get(&key) == Some(&Action::EnterCommandMode) {
                    println!(": -> enter command mode");
                    mode = Mode::Command(String::new());
                } else {
                    // Any other normal-mode key would run its own binding; this
                    // demo only cares about the `:` entry point.
                }
            }
            Mode::Command(buf) => match key.key() {
                Key::Char(c) => {
                    buf.push(c);
                    println!("  :{buf}");
                }
                Key::Enter => {
                    // Take the buffer out and drop back to Normal in one move.
                    let name = std::mem::take(buf);
                    match resolve(&name) {
                        Some(action) => println!("  :{name} -> fire {action:?}"),
                        None => println!("  :{name} -> unknown command, no-op"),
                    }
                    mode = Mode::Normal;
                }
                Key::Esc => {
                    println!("  esc -> abandon command line");
                    mode = Mode::Normal;
                }
                // `Key` is #[non_exhaustive]; other editing keys are ignored here.
                _ => {}
            },
        }
    }
}

pub fn contains(&self, input: &KeyInput) -> bool

Returns true if input has a binding.

pub fn len(&self) -> usize

The number of bindings in the table.

pub fn is_empty(&self) -> bool

Returns true if the table has no bindings.

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

Iterates over every (input, action) binding.

Order is unspecified. This is the data source for listing and search (the discovery layer) built on top of keymap-core.

Examples found in repository

examples/discovery.rs (line 41)

fn main() {
    let mut keymap = Keymap::new();
    keymap.bind(
        KeyInput::new(Key::Char('q'), Modifiers::CTRL),
        Command {
            id: "quit",
            description: "Quit the application",
        },
    );
    keymap.bind(
        KeyInput::new(Key::Char('s'), Modifiers::CTRL),
        Command {
            id: "save",
            description: "Save the current file",
        },
    );
    keymap.bind(
        KeyInput::new(Key::F(1), Modifiers::NONE),
        Command {
            id: "help",
            description: "Show the help overlay",
        },
    );

    // Listing: collect and sort by the canonical key string.
    let mut listing: Vec<(String, &Command)> = keymap
        .iter()
        .map(|(input, cmd)| (input.to_string(), cmd))
        .collect();
    listing.sort_by(|a, b| a.0.cmp(&b.0));

    println!("all bindings:");
    for (key, cmd) in &listing {
        println!("  {key:>8}  {:<6} — {}", cmd.id, cmd.description);
    }

    search(&listing, "sav");
    search(&listing, "zzz");
}

Trait Implementations

impl<A: Clone> Clone for Keymap<A>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A: Debug> Debug for Keymap<A>

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

Formats the value using the given formatter.

impl<A> Default for Keymap<A>

fn default() -> Self

Returns the “default value” for a type.