use std::collections::HashMap;
use std::fmt;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use crate::action::Action;
use crate::ui::sidebar::SidebarMode;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum KeyContext {
Global,
Viewport,
Sidebar,
Edit,
}
impl KeyContext {
pub fn heading(self) -> &'static str {
match self {
KeyContext::Global => "Global",
KeyContext::Viewport => "Reading",
KeyContext::Sidebar => "Sidebar (focused)",
KeyContext::Edit => "Editing",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KeyChord {
pub code: KeyCode,
pub modifiers: KeyModifiers,
}
impl KeyChord {
pub fn from_event(event: KeyEvent) -> Self {
let mut modifiers =
event.modifiers & (KeyModifiers::SHIFT | KeyModifiers::CONTROL | KeyModifiers::ALT);
let mut code = event.code;
if let KeyCode::Char(c) = code {
if modifiers.contains(KeyModifiers::CONTROL) {
code = KeyCode::Char(c.to_ascii_lowercase());
} else if c.is_alphabetic() {
modifiers.remove(KeyModifiers::SHIFT);
}
}
KeyChord { code, modifiers }
}
pub fn parse(token: &str) -> Result<Self, KeyParseError> {
if token.is_empty() {
return Err(KeyParseError::Empty);
}
let mut modifiers = KeyModifiers::NONE;
let mut rest = token;
while let Some(idx) = rest.find('+') {
let (prefix, tail) = rest.split_at(idx);
let modifier = match prefix {
"ctrl" => KeyModifiers::CONTROL,
"alt" => KeyModifiers::ALT,
"shift" => KeyModifiers::SHIFT,
_ => break,
};
if modifiers.contains(modifier) {
return Err(KeyParseError::DuplicateModifier(token.to_string()));
}
modifiers |= modifier;
rest = &tail[1..];
}
let mut code = match rest {
"enter" => KeyCode::Enter,
"esc" => KeyCode::Esc,
"tab" => KeyCode::Tab,
"backtab" => KeyCode::BackTab,
"space" => KeyCode::Char(' '),
"backspace" => KeyCode::Backspace,
"delete" => KeyCode::Delete,
"insert" => KeyCode::Insert,
"home" => KeyCode::Home,
"end" => KeyCode::End,
"pageup" => KeyCode::PageUp,
"pagedown" => KeyCode::PageDown,
"up" => KeyCode::Up,
"down" => KeyCode::Down,
"left" => KeyCode::Left,
"right" => KeyCode::Right,
other => {
if let Some(n) = other
.strip_prefix('f')
.and_then(|d| d.parse::<u8>().ok())
.filter(|n| (1..=12).contains(n))
{
KeyCode::F(n)
} else {
let mut chars = other.chars();
match (chars.next(), chars.next()) {
(Some(c), None) => KeyCode::Char(c),
_ => return Err(KeyParseError::UnknownKey(other.to_string())),
}
}
}
};
if let KeyCode::Char(c) = code {
if modifiers.contains(KeyModifiers::SHIFT)
&& !modifiers.contains(KeyModifiers::CONTROL)
&& c.is_alphabetic()
{
code = KeyCode::Char(c.to_ascii_uppercase());
modifiers.remove(KeyModifiers::SHIFT);
}
}
Ok(KeyChord::from_event(KeyEvent::new(code, modifiers)))
}
}
impl fmt::Display for KeyChord {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
if self.modifiers.contains(KeyModifiers::CONTROL) {
f.write_str("Ctrl+")?;
}
if self.modifiers.contains(KeyModifiers::ALT) {
f.write_str("Alt+")?;
}
if self.modifiers.contains(KeyModifiers::SHIFT) {
f.write_str("Shift+")?;
}
match self.code {
KeyCode::Char(' ') => f.write_str("Space"),
KeyCode::Char(c)
if self
.modifiers
.intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
{
write!(f, "{}", c.to_uppercase())
}
KeyCode::Char(c) => write!(f, "{c}"),
KeyCode::Enter => f.write_str("Enter"),
KeyCode::Esc => f.write_str("Esc"),
KeyCode::Tab => f.write_str("Tab"),
KeyCode::BackTab => f.write_str("Shift+Tab"),
KeyCode::Backspace => f.write_str("Backspace"),
KeyCode::Delete => f.write_str("Delete"),
KeyCode::Insert => f.write_str("Insert"),
KeyCode::Home => f.write_str("Home"),
KeyCode::End => f.write_str("End"),
KeyCode::PageUp => f.write_str("PageUp"),
KeyCode::PageDown => f.write_str("PageDown"),
KeyCode::Up => f.write_str("Up"),
KeyCode::Down => f.write_str("Down"),
KeyCode::Left => f.write_str("Left"),
KeyCode::Right => f.write_str("Right"),
KeyCode::F(n) => write!(f, "F{n}"),
other => write!(f, "{other:?}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct KeySequence(pub Vec<KeyChord>);
impl KeySequence {
pub fn parse(s: &str) -> Result<Self, KeyParseError> {
let chords = s
.split_whitespace()
.map(KeyChord::parse)
.collect::<Result<Vec<_>, _>>()?;
if chords.is_empty() {
return Err(KeyParseError::Empty);
}
Ok(KeySequence(chords))
}
}
impl fmt::Display for KeySequence {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
for (i, chord) in self.0.iter().enumerate() {
if i > 0 {
f.write_str(" ")?;
}
write!(f, "{chord}")?;
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum KeyParseError {
#[error("a key binding cannot be empty")]
Empty,
#[error("`{0}` is not a key; write a sequence as space-separated tokens, e.g. \"g t\"")]
UnknownKey(String),
#[error("`{0}` repeats a modifier")]
DuplicateModifier(String),
}
pub struct BindingSpec {
pub action: Action,
pub context: KeyContext,
pub keys: &'static [&'static str],
pub description: &'static str,
}
const fn b(
action: Action,
context: KeyContext,
keys: &'static [&'static str],
description: &'static str,
) -> BindingSpec {
BindingSpec {
action,
context,
keys,
description,
}
}
pub fn default_bindings() -> Vec<BindingSpec> {
use Action as A;
use KeyContext::{Edit, Global, Sidebar, Viewport};
vec![
b(A::Quit, Global, &["q", "ctrl+q"], "Quit"),
b(A::ToggleHelp, Global, &["?"], "Help overlay"),
b(
A::ToggleSidebar,
Global,
&["ctrl+b", "ctrl+e"],
"Toggle the sidebar (Ctrl+E for tmux users)",
),
b(A::FocusNext, Global, &["tab"], "Focus the next pane"),
b(
A::FocusPrev,
Global,
&["backtab"],
"Focus the previous pane",
),
b(
A::SetSidebarMode(SidebarMode::Files),
Global,
&["m 1", "alt+1"],
"Sidebar mode: files",
),
b(
A::SetSidebarMode(SidebarMode::Search),
Global,
&["m 2", "alt+2"],
"Sidebar mode: search",
),
b(
A::SetSidebarMode(SidebarMode::Outline),
Global,
&["m 3", "alt+3"],
"Sidebar mode: outline",
),
b(
A::SetSidebarMode(SidebarMode::Links),
Global,
&["m 4", "alt+4"],
"Sidebar mode: links",
),
b(A::ToggleMouse, Global, &["m m"], "Toggle mouse capture"),
b(A::CycleTheme, Global, &["m t"], "Next theme"),
b(A::NewFile, Global, &["ctrl+n"], "New file"),
b(A::OpenQuickSwitcher, Global, &["ctrl+o"], "Quick switcher"),
b(
A::OpenFindInDocument,
Global,
&["ctrl+f"],
"Find in document",
),
b(
A::OpenProjectSearch,
Global,
&["ctrl+shift+f", "ctrl+g"],
"Search the project",
),
b(A::NewTab, Global, &["ctrl+t"], "New tab"),
b(A::CloseTab, Global, &["ctrl+w"], "Close tab"),
b(A::NextTab, Global, &["g t", "ctrl+pagedown"], "Next tab"),
b(A::PrevTab, Global, &["g T", "ctrl+pageup"], "Previous tab"),
b(
A::Escape,
Global,
&["esc"],
"Close the overlay, or leave edit mode",
),
b(
A::Suspend,
Global,
&["ctrl+z"],
"Suspend perga (resume with `fg`)",
),
b(
A::ScrollLineDown,
Viewport,
&["j", "down"],
"Scroll down one line",
),
b(
A::ScrollLineUp,
Viewport,
&["k", "up"],
"Scroll up one line",
),
b(
A::ScrollHalfPageDown,
Viewport,
&["ctrl+d"],
"Scroll down half a page",
),
b(
A::ScrollHalfPageUp,
Viewport,
&["ctrl+u"],
"Scroll up half a page",
),
b(
A::ScrollPageDown,
Viewport,
&["space", "pagedown"],
"Scroll down a page",
),
b(
A::ScrollPageUp,
Viewport,
&["b", "pageup"],
"Scroll up a page",
),
b(A::ScrollTop, Viewport, &["g g"], "Top of the document"),
b(A::ScrollBottom, Viewport, &["G"], "Bottom of the document"),
b(A::ScrollLeft, Viewport, &["h"], "Scroll left"),
b(A::ScrollRight, Viewport, &["l"], "Scroll right"),
b(A::PrevHeading, Viewport, &["{"], "Previous heading"),
b(A::NextHeading, Viewport, &["}"], "Next heading"),
b(A::NextLink, Viewport, &["n"], "Focus the next link"),
b(A::PrevLink, Viewport, &["N"], "Focus the previous link"),
b(
A::FollowLink,
Viewport,
&["enter"],
"Follow the focused link",
),
b(
A::FollowLinkInNewTab,
Viewport,
&["ctrl+enter", "t enter"],
"Follow the focused link in a new tab",
),
b(A::HintMode, Viewport, &["f"], "Label and jump to a link"),
b(A::HistoryBack, Viewport, &["H", "alt+left"], "Back"),
b(A::HistoryForward, Viewport, &["L", "alt+right"], "Forward"),
b(
A::RenameDocument,
Viewport,
&["R"],
"Rename the active document",
),
b(A::EnterEditMode, Viewport, &["e", "i"], "Enter edit mode"),
b(A::OpenInExternalEditor, Viewport, &["o"], "Open in $EDITOR"),
b(
A::CopyDocumentPath,
Viewport,
&["y"],
"Copy the document path",
),
b(
A::ReloadDocument,
Viewport,
&["r"],
"Reload the active document",
),
b(
A::SidebarDown,
Sidebar,
&["j", "down"],
"Move the selection down",
),
b(A::SidebarUp, Sidebar, &["k", "up"], "Move the selection up"),
b(
A::SidebarActivate,
Sidebar,
&["l", "right", "enter"],
"Open the selection",
),
b(
A::SidebarBack,
Sidebar,
&["h", "left"],
"Collapse a directory, or go to its parent",
),
b(
A::SetSidebarMode(SidebarMode::Files),
Sidebar,
&["1"],
"Sidebar mode: files",
),
b(
A::SetSidebarMode(SidebarMode::Search),
Sidebar,
&["2"],
"Sidebar mode: search",
),
b(
A::SetSidebarMode(SidebarMode::Outline),
Sidebar,
&["3"],
"Sidebar mode: outline",
),
b(
A::SetSidebarMode(SidebarMode::Links),
Sidebar,
&["4"],
"Sidebar mode: links",
),
b(A::TreeToggleHidden, Sidebar, &["."], "Toggle hidden files"),
b(
A::TreeToggleAllFiles,
Sidebar,
&["a"],
"Toggle non-Markdown files",
),
b(
A::TreeFilter,
Sidebar,
&["/"],
"Filter the tree, or edit the last search query",
),
b(A::TreeRename, Sidebar, &["r"], "Rename the selected entry"),
b(A::SidebarWiden, Sidebar, &[">"], "Widen the sidebar"),
b(A::SidebarNarrow, Sidebar, &["<"], "Narrow the sidebar"),
b(A::Save, Edit, &["ctrl+s"], "Save"),
b(A::Escape, Edit, &["esc"], "Leave edit mode"),
b(A::Undo, Edit, &["ctrl+z"], "Undo"),
b(A::Redo, Edit, &["ctrl+y"], "Redo"),
]
}
fn inherits_global(context: KeyContext) -> bool {
context != KeyContext::Edit
}
pub fn action_name(action: &Action) -> String {
if let Action::SetSidebarMode(mode) = action {
return format!("sidebar_mode_{mode}");
}
let debug = format!("{action:?}");
let variant = debug.split('(').next().unwrap_or(&debug);
let mut out = String::with_capacity(variant.len() + 4);
for (at, c) in variant.char_indices() {
if c.is_uppercase() && at > 0 {
out.push('_');
}
out.extend(c.to_lowercase());
}
out
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Resolution {
Action(Action),
Pending(String),
Unbound,
}
#[derive(Debug, Clone)]
pub struct ResolvedBinding {
pub action: Action,
pub context: KeyContext,
pub sequences: Vec<KeySequence>,
pub description: &'static str,
}
#[derive(Debug, Clone, Default)]
pub struct Keymap {
bindings: HashMap<(KeyContext, KeySequence), Action>,
prefixes: HashMap<(KeyContext, KeySequence), ()>,
entries: Vec<ResolvedBinding>,
pending: Vec<KeyChord>,
warnings: Vec<String>,
}
impl Keymap {
pub fn defaults() -> Self {
let mut keymap = Keymap::default();
for spec in default_bindings() {
let sequences = spec
.keys
.iter()
.map(|key| {
KeySequence::parse(key).unwrap_or_else(|e| {
panic!(
"default binding `{key}` for {:?} must parse: {e}",
spec.action
)
})
})
.collect::<Vec<_>>();
keymap.entries.push(ResolvedBinding {
action: spec.action.clone(),
context: spec.context,
sequences: sequences.clone(),
description: spec.description,
});
for sequence in sequences {
keymap.insert(spec.context, sequence, spec.action.clone());
}
}
keymap
}
pub fn with_overrides(remaps: &toml::Table) -> Self {
let mut keymap = Keymap::default();
let mut overrides: HashMap<String, Vec<KeySequence>> = HashMap::new();
let mut warnings = Vec::new();
for (name, value) in remaps {
let written = match value {
toml::Value::String(one) => vec![one.clone()],
toml::Value::Array(many) => many
.iter()
.filter_map(|v| v.as_str().map(str::to_string))
.collect(),
_ => {
warnings.push(format!(
"`keys.{name}` must be a binding or a list of bindings"
));
continue;
}
};
if !default_bindings()
.iter()
.any(|spec| action_name(&spec.action) == *name)
{
warnings.push(format!("`keys.{name}` is not an action"));
continue;
}
let mut sequences = Vec::new();
for key in written {
match KeySequence::parse(&key) {
Ok(sequence) => sequences.push(sequence),
Err(e) => warnings.push(format!("`keys.{name} = \"{key}\"` ignored: {e}")),
}
}
if !sequences.is_empty() {
overrides.insert(name.clone(), sequences);
}
}
for spec in default_bindings() {
let name = action_name(&spec.action);
let sequences = match overrides.get(&name) {
Some(remapped) => remapped.clone(),
None => spec
.keys
.iter()
.map(|key| {
KeySequence::parse(key)
.unwrap_or_else(|e| panic!("default binding `{key}` must parse: {e}"))
})
.collect(),
};
keymap.entries.push(ResolvedBinding {
action: spec.action.clone(),
context: spec.context,
sequences: sequences.clone(),
description: spec.description,
});
for sequence in sequences {
if let Some(shadowed) = keymap.bindings.get(&(spec.context, sequence.clone())) {
if *shadowed != spec.action {
warnings.push(format!(
"`{sequence}` is bound to both `{}` and `{name}`; `{name}` wins",
action_name(shadowed)
));
}
}
keymap.insert(spec.context, sequence, spec.action.clone());
}
}
keymap.warnings = warnings;
keymap
}
fn insert(&mut self, context: KeyContext, sequence: KeySequence, action: Action) {
for len in 1..sequence.0.len() {
let prefix = KeySequence(sequence.0[..len].to_vec());
self.prefixes.insert((context, prefix), ());
}
self.bindings.insert((context, sequence), action);
}
pub fn warnings(&self) -> &[String] {
&self.warnings
}
pub fn entries(&self) -> &[ResolvedBinding] {
&self.entries
}
pub fn binding_for(&self, action: &Action) -> Option<String> {
self.entries
.iter()
.find(|e| &e.action == action)
.and_then(|e| e.sequences.first())
.map(|s| s.to_string())
}
pub fn pending(&self) -> &[KeyChord] {
&self.pending
}
pub fn clear_pending(&mut self) {
self.pending.clear();
}
fn lookup(&self, context: KeyContext, sequence: &KeySequence) -> Option<&Action> {
let own = self.bindings.get(&(context, sequence.clone()));
if !inherits_global(context) {
return own;
}
own.or_else(|| self.bindings.get(&(KeyContext::Global, sequence.clone())))
}
fn is_prefix(&self, context: KeyContext, sequence: &KeySequence) -> bool {
if self.prefixes.contains_key(&(context, sequence.clone())) {
return true;
}
inherits_global(context)
&& self
.prefixes
.contains_key(&(KeyContext::Global, sequence.clone()))
}
pub fn resolve(&mut self, context: KeyContext, chord: KeyChord) -> Resolution {
self.pending.push(chord);
let candidate = KeySequence(self.pending.clone());
if let Some(action) = self.lookup(context, &candidate) {
let action = action.clone();
self.pending.clear();
return Resolution::Action(action);
}
if self.is_prefix(context, &candidate) {
return Resolution::Pending(format!("{candidate}…"));
}
let restart = self.pending.len() > 1;
self.pending.clear();
if restart {
return self.resolve(context, chord);
}
Resolution::Unbound
}
}
#[cfg(test)]
mod tests {
use super::*;
fn chord(s: &str) -> KeyChord {
KeyChord::parse(s).unwrap()
}
#[test]
fn parses_plain_characters() {
assert_eq!(
chord("q"),
KeyChord {
code: KeyCode::Char('q'),
modifiers: KeyModifiers::NONE
}
);
assert_eq!(
chord("?"),
KeyChord {
code: KeyCode::Char('?'),
modifiers: KeyModifiers::NONE
}
);
assert_eq!(
chord("/"),
KeyChord {
code: KeyCode::Char('/'),
modifiers: KeyModifiers::NONE
}
);
}
#[test]
fn parses_modifiers_in_any_supported_order() {
assert_eq!(
chord("ctrl+shift+f"),
KeyChord {
code: KeyCode::Char('f'),
modifiers: KeyModifiers::CONTROL | KeyModifiers::SHIFT,
}
);
assert_eq!(
chord("alt+left"),
KeyChord {
code: KeyCode::Left,
modifiers: KeyModifiers::ALT,
}
);
}
#[test]
fn parses_named_and_function_keys() {
assert_eq!(chord("enter").code, KeyCode::Enter);
assert_eq!(chord("backtab").code, KeyCode::BackTab);
assert_eq!(chord("space").code, KeyCode::Char(' '));
assert_eq!(chord("pagedown").code, KeyCode::PageDown);
assert_eq!(chord("f12").code, KeyCode::F(12));
}
#[test]
fn plus_is_bindable_as_a_character() {
assert_eq!(
chord("+"),
KeyChord {
code: KeyCode::Char('+'),
modifiers: KeyModifiers::NONE
}
);
assert_eq!(
chord("ctrl++"),
KeyChord {
code: KeyCode::Char('+'),
modifiers: KeyModifiers::CONTROL
}
);
}
#[test]
fn uppercase_and_shift_spellings_agree() {
assert_eq!(chord("G"), chord("shift+g"));
assert_eq!(chord("G").modifiers, KeyModifiers::NONE);
}
#[test]
fn rejects_a_run_together_sequence() {
assert_eq!(
KeySequence::parse("gt"),
Err(KeyParseError::UnknownKey("gt".to_string()))
);
}
#[test]
fn rejects_empty_and_unknown_keys() {
assert_eq!(KeySequence::parse(" "), Err(KeyParseError::Empty));
assert_eq!(
KeySequence::parse("hyper+q"),
Err(KeyParseError::UnknownKey("hyper+q".to_string()))
);
assert_eq!(
KeyChord::parse("ctrl+ctrl+a"),
Err(KeyParseError::DuplicateModifier("ctrl+ctrl+a".to_string()))
);
}
#[test]
fn parses_sequences() {
let seq = KeySequence::parse("g t").unwrap();
assert_eq!(seq.0, vec![chord("g"), chord("t")]);
assert_eq!(seq.to_string(), "g t");
}
#[test]
fn normalises_shift_on_plain_characters() {
let from_terminal =
KeyChord::from_event(KeyEvent::new(KeyCode::Char('G'), KeyModifiers::SHIFT));
assert_eq!(from_terminal, chord("G"));
}
#[test]
fn keeps_shift_on_control_characters() {
let from_terminal = KeyChord::from_event(KeyEvent::new(
KeyCode::Char('F'),
KeyModifiers::CONTROL | KeyModifiers::SHIFT,
));
assert_eq!(from_terminal, chord("ctrl+shift+f"));
assert_ne!(from_terminal, chord("ctrl+f"));
}
#[test]
fn every_default_binding_parses() {
let keymap = Keymap::defaults();
assert!(keymap.warnings().is_empty());
assert!(!keymap.entries().is_empty());
}
#[test]
fn binding_for_returns_the_primary_spelling() {
let keymap = Keymap::defaults();
assert_eq!(
keymap.binding_for(&Action::ToggleSidebar).as_deref(),
Some("Ctrl+B")
);
assert_eq!(
keymap.binding_for(&Action::ScrollTop).as_deref(),
Some("g g")
);
}
#[test]
fn resolves_a_single_chord() {
let mut keymap = Keymap::defaults();
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("q")),
Resolution::Action(Action::Quit)
);
}
#[test]
fn context_shadows_global() {
let mut keymap = Keymap::defaults();
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("j")),
Resolution::Action(Action::ScrollLineDown)
);
assert_eq!(
keymap.resolve(KeyContext::Sidebar, chord("j")),
Resolution::Action(Action::SidebarDown)
);
}
#[test]
fn global_applies_where_no_context_binding_exists() {
let mut keymap = Keymap::defaults();
assert_eq!(
keymap.resolve(KeyContext::Sidebar, chord("ctrl+t")),
Resolution::Action(Action::NewTab)
);
}
#[test]
fn resolves_a_sequence_through_a_pending_state() {
let mut keymap = Keymap::defaults();
assert!(matches!(
keymap.resolve(KeyContext::Viewport, chord("g")),
Resolution::Pending(_)
));
assert_eq!(keymap.pending().len(), 1);
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("g")),
Resolution::Action(Action::ScrollTop)
);
assert!(keymap.pending().is_empty());
}
#[test]
fn a_prefix_key_has_no_standalone_meaning() {
let mut keymap = Keymap::defaults();
assert!(matches!(
keymap.resolve(KeyContext::Viewport, chord("g")),
Resolution::Pending(_)
));
}
#[test]
fn an_abandoning_key_is_processed_on_its_own() {
let mut keymap = Keymap::defaults();
assert!(matches!(
keymap.resolve(KeyContext::Viewport, chord("g")),
Resolution::Pending(_)
));
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("q")),
Resolution::Action(Action::Quit)
);
assert!(keymap.pending().is_empty());
}
#[test]
fn an_abandoning_key_that_means_nothing_is_unbound() {
let mut keymap = Keymap::defaults();
keymap.resolve(KeyContext::Viewport, chord("g"));
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("Z")),
Resolution::Unbound
);
assert!(keymap.pending().is_empty());
}
#[test]
fn sequence_case_is_significant() {
let mut keymap = Keymap::defaults();
keymap.resolve(KeyContext::Viewport, chord("g"));
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("t")),
Resolution::Action(Action::NextTab)
);
keymap.resolve(KeyContext::Viewport, chord("g"));
assert_eq!(
keymap.resolve(KeyContext::Viewport, chord("T")),
Resolution::Action(Action::PrevTab)
);
}
#[test]
fn every_enhanced_binding_has_a_plain_fallback() {
fn needs_enhancement(seq: &KeySequence) -> bool {
seq.0.iter().any(|c| {
let ctrl = c.modifiers.contains(KeyModifiers::CONTROL);
let alt = c.modifiers.contains(KeyModifiers::ALT);
let shift = c.modifiers.contains(KeyModifiers::SHIFT);
match c.code {
KeyCode::Enter => ctrl || shift,
KeyCode::PageUp | KeyCode::PageDown => ctrl,
KeyCode::Left | KeyCode::Right | KeyCode::Up | KeyCode::Down => alt,
KeyCode::Char(ch) => (ctrl && shift) || (alt && ch.is_ascii_digit()),
_ => false,
}
})
}
for entry in Keymap::defaults().entries() {
if entry.sequences.iter().any(needs_enhancement) {
assert!(
entry.sequences.iter().any(|s| !needs_enhancement(s)),
"{:?} is only reachable through the kitty keyboard protocol",
entry.action
);
}
}
}
fn remapped(toml_text: &str) -> Keymap {
Keymap::with_overrides(&toml::from_str(toml_text).unwrap())
}
#[test]
fn an_action_name_is_its_snake_cased_variant() {
assert_eq!(action_name(&Action::ToggleSidebar), "toggle_sidebar");
assert_eq!(action_name(&Action::Quit), "quit");
assert_eq!(action_name(&Action::ScrollTop), "scroll_top");
assert_eq!(
action_name(&Action::SetSidebarMode(SidebarMode::Outline)),
"sidebar_mode_outline"
);
}
#[test]
fn no_two_actions_share_a_name() {
let mut pairs: Vec<(String, String)> = default_bindings()
.iter()
.map(|spec| (action_name(&spec.action), format!("{:?}", spec.action)))
.collect();
pairs.sort();
pairs.dedup();
let mut names: Vec<&String> = pairs.iter().map(|(name, _)| name).collect();
let count = names.len();
names.dedup();
assert_eq!(names.len(), count, "two actions share a name in `[keys]`");
}
#[test]
fn no_overrides_is_the_default_keymap() {
let mut remapped = remapped("");
let mut defaults = Keymap::defaults();
assert!(remapped.warnings().is_empty());
assert_eq!(
remapped.resolve(KeyContext::Global, KeyChord::parse("q").unwrap()),
defaults.resolve(KeyContext::Global, KeyChord::parse("q").unwrap())
);
}
#[test]
fn a_remap_replaces_the_default_rather_than_adding_to_it() {
let mut keymap = remapped(r#""quit" = "ctrl+q""#);
assert_eq!(
keymap.resolve(KeyContext::Global, KeyChord::parse("ctrl+q").unwrap()),
Resolution::Action(Action::Quit)
);
assert_eq!(
keymap.resolve(KeyContext::Global, KeyChord::parse("q").unwrap()),
Resolution::Unbound,
"a remap must be able to free a key"
);
}
#[test]
fn a_remap_may_be_a_list() {
let mut keymap = remapped(r#""quit" = ["x", "ctrl+q"]"#);
for key in ["x", "ctrl+q"] {
assert_eq!(
keymap.resolve(KeyContext::Global, KeyChord::parse(key).unwrap()),
Resolution::Action(Action::Quit)
);
}
}
#[test]
fn a_remap_may_be_a_sequence() {
let mut keymap = remapped(r#""scroll_top" = "g h""#);
assert!(matches!(
keymap.resolve(KeyContext::Viewport, KeyChord::parse("g").unwrap()),
Resolution::Pending(_)
));
assert_eq!(
keymap.resolve(KeyContext::Viewport, KeyChord::parse("h").unwrap()),
Resolution::Action(Action::ScrollTop)
);
}
#[test]
fn the_help_overlay_follows_a_remap() {
let keymap = remapped(r#""toggle_sidebar" = "ctrl+space""#);
assert_eq!(
keymap.binding_for(&Action::ToggleSidebar).as_deref(),
Some("Ctrl+Space")
);
}
#[test]
fn an_unparseable_binding_is_a_warning_and_the_default_survives() {
let mut keymap = remapped(r#""quit" = "gt""#);
assert_eq!(keymap.warnings().len(), 1);
assert!(
keymap.warnings()[0].contains("keys.quit"),
"{:?}",
keymap.warnings()
);
assert_eq!(
keymap.resolve(KeyContext::Global, KeyChord::parse("q").unwrap()),
Resolution::Action(Action::Quit)
);
}
#[test]
fn an_unknown_action_is_a_warning() {
let keymap = remapped(r#""fly_to_the_moon" = "f""#);
assert_eq!(keymap.warnings().len(), 1);
assert!(keymap.warnings()[0].contains("not an action"));
}
#[test]
fn a_remap_of_the_wrong_shape_is_a_warning() {
let keymap = remapped(r#""quit" = 3"#);
assert_eq!(keymap.warnings().len(), 1);
assert!(keymap.warnings()[0].contains("keys.quit"));
}
#[test]
fn a_conflict_names_the_action_it_shadowed() {
let keymap = remapped(r#""quit" = "?""#);
assert!(
keymap
.warnings()
.iter()
.any(|w| w.contains("toggle_help") && w.contains('?')),
"{:?}",
keymap.warnings()
);
}
#[test]
fn ten_remapped_actions_all_take_effect() {
let mut keymap = remapped(
r#"
"quit" = "Q"
"toggle_help" = "f1"
"toggle_sidebar" = "ctrl+space"
"new_tab" = "ctrl+shift+t"
"close_tab" = "ctrl+shift+w"
"scroll_top" = "home"
"scroll_bottom" = "end"
"next_link" = "ctrl+j"
"prev_link" = "ctrl+k"
"open_quick_switcher" = "ctrl+p"
"#,
);
assert!(keymap.warnings().is_empty(), "{:?}", keymap.warnings());
for (key, context, action) in [
("Q", KeyContext::Global, Action::Quit),
("f1", KeyContext::Global, Action::ToggleHelp),
("ctrl+space", KeyContext::Global, Action::ToggleSidebar),
("ctrl+p", KeyContext::Global, Action::OpenQuickSwitcher),
("home", KeyContext::Viewport, Action::ScrollTop),
("end", KeyContext::Viewport, Action::ScrollBottom),
("ctrl+j", KeyContext::Viewport, Action::NextLink),
] {
assert_eq!(
keymap.resolve(context, KeyChord::parse(key).unwrap()),
Resolution::Action(action),
"`{key}` did not remap"
);
}
}
#[test]
fn the_keybindings_page_lists_every_action_and_binding() {
let page = include_str!("../../docs/keybindings.md");
for spec in default_bindings() {
let name = action_name(&spec.action);
assert!(
page.contains(&format!("`{name}`")),
"docs/keybindings.md does not mention the action `{name}`"
);
for key in spec.keys {
let sequence = KeySequence::parse(key).expect("a default binding parses");
assert!(
page.contains(&format!("`{sequence}`")),
"docs/keybindings.md does not mention `{sequence}`, bound to `{name}`"
);
}
}
}
#[test]
fn the_keybindings_page_invents_no_actions() {
let page = include_str!("../../docs/keybindings.md");
let known: Vec<String> = default_bindings()
.iter()
.map(|spec| action_name(&spec.action))
.collect();
for line in page.lines().filter(|l| l.starts_with('|')) {
let Some(last) = line.trim_end_matches('|').rsplit('|').next() else {
continue;
};
let cell = last.trim().trim_matches('`');
if cell.is_empty() || cell.contains(' ') || !cell.contains('_') {
continue;
}
assert!(
known.contains(&cell.to_string()),
"docs/keybindings.md lists `{cell}`, which is not an action"
);
}
}
}