1mod binding;
2mod context;
3
4pub use binding::*;
5pub use context::*;
6
7use crate::{Action, Keystroke, is_no_action};
8use collections::HashMap;
9use smallvec::SmallVec;
10use std::any::TypeId;
11
12/// An opaque identifier of which version of the keymap is currently active.
13/// The keymap's version is changed whenever bindings are added or removed.
14#[derive(Copy, Clone, Eq, PartialEq, Default)]
15pub struct KeymapVersion(usize);
16
17/// A collection of key bindings for the user's application.
18#[derive(Default)]
19pub struct Keymap {
20 bindings: Vec<KeyBinding>,
21 binding_indices_by_action_id: HashMap<TypeId, SmallVec<[usize; 3]>>,
22 no_action_binding_indices: Vec<usize>,
23 version: KeymapVersion,
24}
25
26impl Keymap {
27 /// Create a new keymap with the given bindings.
28 pub fn new(bindings: Vec<KeyBinding>) -> Self {
29 let mut this = Self::default();
30 this.add_bindings(bindings);
31 this
32 }
33
34 /// Get the current version of the keymap.
35 pub fn version(&self) -> KeymapVersion {
36 self.version
37 }
38
39 /// Add more bindings to the keymap.
40 pub fn add_bindings<T: IntoIterator<Item = KeyBinding>>(&mut self, bindings: T) {
41 for binding in bindings {
42 let action_id = binding.action().as_any().type_id();
43 if is_no_action(&*binding.action) {
44 self.no_action_binding_indices.push(self.bindings.len());
45 } else {
46 self.binding_indices_by_action_id
47 .entry(action_id)
48 .or_default()
49 .push(self.bindings.len());
50 }
51 self.bindings.push(binding);
52 }
53
54 self.version.0 += 1;
55 }
56
57 /// Reset this keymap to its initial state.
58 pub fn clear(&mut self) {
59 self.bindings.clear();
60 self.binding_indices_by_action_id.clear();
61 self.no_action_binding_indices.clear();
62 self.version.0 += 1;
63 }
64
65 /// Iterate over all bindings, in the order they were added.
66 pub fn bindings(&self) -> impl DoubleEndedIterator<Item = &KeyBinding> {
67 self.bindings.iter()
68 }
69
70 /// Iterate over all bindings for the given action, in the order they were added. For display,
71 /// the last binding should take precedence.
72 pub fn bindings_for_action<'a>(
73 &'a self,
74 action: &'a dyn Action,
75 ) -> impl 'a + DoubleEndedIterator<Item = &'a KeyBinding> {
76 let action_id = action.type_id();
77 let binding_indices = self
78 .binding_indices_by_action_id
79 .get(&action_id)
80 .map_or(&[] as _, SmallVec::as_slice)
81 .iter();
82
83 binding_indices.filter_map(|ix| {
84 let binding = &self.bindings[*ix];
85 if !binding.action().partial_eq(action) {
86 return None;
87 }
88
89 for null_ix in &self.no_action_binding_indices {
90 if null_ix > ix {
91 let null_binding = &self.bindings[*null_ix];
92 if null_binding.keystrokes == binding.keystrokes {
93 let null_binding_matches =
94 match (&null_binding.context_predicate, &binding.context_predicate) {
95 (None, _) => true,
96 (Some(_), None) => false,
97 (Some(null_predicate), Some(predicate)) => {
98 null_predicate.is_superset(predicate)
99 }
100 };
101 if null_binding_matches {
102 return None;
103 }
104 }
105 }
106 }
107
108 Some(binding)
109 })
110 }
111
112 /// Returns all bindings that might match the input without checking context. The bindings
113 /// returned in precedence order (reverse of the order they were added to the keymap).
114 pub fn all_bindings_for_input(&self, input: &[Keystroke]) -> Vec<KeyBinding> {
115 self.bindings()
116 .rev()
117 .filter_map(|binding| {
118 binding.match_keystrokes(input).filter(|pending| !pending)?;
119 Some(binding.clone())
120 })
121 .collect()
122 }
123
124 /// Returns a list of bindings that match the given input, and a boolean indicating whether or
125 /// not more bindings might match if the input was longer. Bindings are returned in precedence
126 /// order.
127 ///
128 /// Precedence is defined by the depth in the tree (matches on the Editor take precedence over
129 /// matches on the Pane, then the Workspace, etc.). Bindings with no context are treated as the
130 /// same as the deepest context.
131 ///
132 /// In the case of multiple bindings at the same depth, the ones added to the keymap later take
133 /// precedence. User bindings are added after built-in bindings so that they take precedence.
134 ///
135 /// If a user has disabled a binding with `"x": null` it will not be returned. Disabled bindings
136 /// are evaluated with the same precedence rules so you can disable a rule in a given context
137 /// only.
138 pub fn bindings_for_input(
139 &self,
140 input: &[Keystroke],
141 context_stack: &[KeyContext],
142 ) -> (SmallVec<[KeyBinding; 1]>, bool) {
143 let possibilities = self.bindings().rev().filter_map(|binding| {
144 binding
145 .match_keystrokes(input)
146 .map(|pending| (binding, pending))
147 });
148
149 let mut bindings: SmallVec<[(KeyBinding, usize); 1]> = SmallVec::new();
150
151 // (pending, is_no_action, depth, keystrokes)
152 let mut pending_info_opt: Option<(bool, bool, usize, &[Keystroke])> = None;
153
154 'outer: for (binding, pending) in possibilities {
155 for depth in (0..=context_stack.len()).rev() {
156 if self.binding_enabled(binding, &context_stack[0..depth]) {
157 let is_no_action = is_no_action(&*binding.action);
158 // We only want to consider a binding pending if it has an action
159 // This, however, means that if we have both a NoAction binding and a binding
160 // with an action at the same depth, we should still set is_pending to true.
161 if let Some(pending_info) = pending_info_opt.as_mut() {
162 let (
163 already_pending,
164 pending_is_no_action,
165 pending_depth,
166 pending_keystrokes,
167 ) = *pending_info;
168
169 // We only want to change the pending status if it's not already pending AND if
170 // the existing pending status was set by a NoAction binding. This avoids a NoAction
171 // binding erroneously setting the pending status to true when a binding with an action
172 // already set it to false
173 //
174 // We also want to change the pending status if the keystrokes don't match,
175 // meaning it's different keystrokes than the NoAction that set pending to false
176 if pending
177 && !already_pending
178 && pending_is_no_action
179 && (pending_depth == depth
180 || pending_keystrokes != binding.keystrokes())
181 {
182 pending_info.0 = !is_no_action;
183 }
184 } else {
185 pending_info_opt = Some((
186 pending && !is_no_action,
187 is_no_action,
188 depth,
189 binding.keystrokes(),
190 ));
191 }
192
193 if !pending {
194 bindings.push((binding.clone(), depth));
195 continue 'outer;
196 }
197 }
198 }
199 }
200 bindings.sort_by(|a, b| a.1.cmp(&b.1).reverse());
201 let bindings = bindings
202 .into_iter()
203 .map_while(|(binding, _)| {
204 if is_no_action(&*binding.action) {
205 None
206 } else {
207 Some(binding)
208 }
209 })
210 .collect();
211
212 (bindings, pending_info_opt.unwrap_or_default().0)
213 }
214
215 /// Check if the given binding is enabled, given a certain key context.
216 fn binding_enabled(&self, binding: &KeyBinding, context: &[KeyContext]) -> bool {
217 // If binding has a context predicate, it must match the current context,
218 if let Some(predicate) = &binding.context_predicate {
219 if !predicate.eval(context) {
220 return false;
221 }
222 }
223
224 true
225 }
226
227 /// WARN: Assumes the bindings are in the order they were added to the keymap
228 /// returns the last binding for the given bindings, which
229 /// should be the user's binding in their keymap.json if they've set one,
230 /// otherwise, the last declared binding for this action in the base keymaps
231 /// (with Vim mode bindings being considered as declared later if Vim mode
232 /// is enabled)
233 ///
234 /// If you are considering changing the behavior of this function
235 /// (especially to fix a user reported issue) see issues #23621, #24931,
236 /// and possibly others as evidence that it has swapped back and forth a
237 /// couple times. The decision as of now is to pick a side and leave it
238 /// as is, until we have a better way to decide which binding to display
239 /// that is consistent and not confusing.
240 pub fn binding_to_display_from_bindings(mut bindings: Vec<KeyBinding>) -> Option<KeyBinding> {
241 bindings.pop()
242 }
243
244 /// Returns the first binding present in the iterator, which tends to be the
245 /// default binding without any key context. This is useful for cases where no
246 /// key context is available on binding display. Otherwise, bindings with a
247 /// more specific key context would take precedence and result in a
248 /// potentially invalid keybind being returned.
249 pub fn default_binding_from_bindings_iterator<'a>(
250 mut bindings: impl Iterator<Item = &'a KeyBinding>,
251 ) -> Option<&'a KeyBinding> {
252 bindings.next()
253 }
254}
255
256#[cfg(test)]
257mod tests {
258 use super::*;
259 use crate as gpui;
260 use gpui::{NoAction, actions};
261
262 actions!(
263 keymap_test,
264 [ActionAlpha, ActionBeta, ActionGamma, ActionDelta,]
265 );
266
267 #[test]
268 fn test_keymap() {
269 let bindings = [
270 KeyBinding::new("ctrl-a", ActionAlpha {}, None),
271 KeyBinding::new("ctrl-a", ActionBeta {}, Some("pane")),
272 KeyBinding::new("ctrl-a", ActionGamma {}, Some("editor && mode==full")),
273 ];
274
275 let mut keymap = Keymap::default();
276 keymap.add_bindings(bindings.clone());
277
278 // global bindings are enabled in all contexts
279 assert!(keymap.binding_enabled(&bindings[0], &[]));
280 assert!(keymap.binding_enabled(&bindings[0], &[KeyContext::parse("terminal").unwrap()]));
281
282 // contextual bindings are enabled in contexts that match their predicate
283 assert!(!keymap.binding_enabled(&bindings[1], &[KeyContext::parse("barf x=y").unwrap()]));
284 assert!(keymap.binding_enabled(&bindings[1], &[KeyContext::parse("pane x=y").unwrap()]));
285
286 assert!(!keymap.binding_enabled(&bindings[2], &[KeyContext::parse("editor").unwrap()]));
287 assert!(keymap.binding_enabled(
288 &bindings[2],
289 &[KeyContext::parse("editor mode=full").unwrap()]
290 ));
291 }
292
293 #[test]
294 fn test_keymap_disabled() {
295 let bindings = [
296 KeyBinding::new("ctrl-a", ActionAlpha {}, Some("editor")),
297 KeyBinding::new("ctrl-b", ActionAlpha {}, Some("editor")),
298 KeyBinding::new("ctrl-a", NoAction {}, Some("editor && mode==full")),
299 KeyBinding::new("ctrl-b", NoAction {}, None),
300 ];
301
302 let mut keymap = Keymap::default();
303 keymap.add_bindings(bindings.clone());
304
305 // binding is only enabled in a specific context
306 assert!(
307 keymap
308 .bindings_for_input(
309 &[Keystroke::parse("ctrl-a").unwrap()],
310 &[KeyContext::parse("barf").unwrap()],
311 )
312 .0
313 .is_empty()
314 );
315 assert!(
316 !keymap
317 .bindings_for_input(
318 &[Keystroke::parse("ctrl-a").unwrap()],
319 &[KeyContext::parse("editor").unwrap()],
320 )
321 .0
322 .is_empty()
323 );
324
325 // binding is disabled in a more specific context
326 assert!(
327 keymap
328 .bindings_for_input(
329 &[Keystroke::parse("ctrl-a").unwrap()],
330 &[KeyContext::parse("editor mode=full").unwrap()],
331 )
332 .0
333 .is_empty()
334 );
335
336 // binding is globally disabled
337 assert!(
338 keymap
339 .bindings_for_input(
340 &[Keystroke::parse("ctrl-b").unwrap()],
341 &[KeyContext::parse("barf").unwrap()],
342 )
343 .0
344 .is_empty()
345 );
346 }
347
348 #[test]
349 /// Tests for https://github.com/zed-industries/zed/issues/30259
350 fn test_multiple_keystroke_binding_disabled() {
351 let bindings = [
352 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
353 KeyBinding::new("space w w", NoAction {}, Some("editor")),
354 ];
355
356 let mut keymap = Keymap::default();
357 keymap.add_bindings(bindings.clone());
358
359 let space = || Keystroke::parse("space").unwrap();
360 let w = || Keystroke::parse("w").unwrap();
361
362 let space_w = [space(), w()];
363 let space_w_w = [space(), w(), w()];
364
365 let workspace_context = || [KeyContext::parse("workspace").unwrap()];
366
367 let editor_workspace_context = || {
368 [
369 KeyContext::parse("workspace").unwrap(),
370 KeyContext::parse("editor").unwrap(),
371 ]
372 };
373
374 // Ensure `space` results in pending input on the workspace, but not editor
375 let space_workspace = keymap.bindings_for_input(&[space()], &workspace_context());
376 assert!(space_workspace.0.is_empty());
377 assert_eq!(space_workspace.1, true);
378
379 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
380 assert!(space_editor.0.is_empty());
381 assert_eq!(space_editor.1, false);
382
383 // Ensure `space w` results in pending input on the workspace, but not editor
384 let space_w_workspace = keymap.bindings_for_input(&space_w, &workspace_context());
385 assert!(space_w_workspace.0.is_empty());
386 assert_eq!(space_w_workspace.1, true);
387
388 let space_w_editor = keymap.bindings_for_input(&space_w, &editor_workspace_context());
389 assert!(space_w_editor.0.is_empty());
390 assert_eq!(space_w_editor.1, false);
391
392 // Ensure `space w w` results in the binding in the workspace, but not in the editor
393 let space_w_w_workspace = keymap.bindings_for_input(&space_w_w, &workspace_context());
394 assert!(!space_w_w_workspace.0.is_empty());
395 assert_eq!(space_w_w_workspace.1, false);
396
397 let space_w_w_editor = keymap.bindings_for_input(&space_w_w, &editor_workspace_context());
398 assert!(space_w_w_editor.0.is_empty());
399 assert_eq!(space_w_w_editor.1, false);
400
401 // Now test what happens if we have another binding defined AFTER the NoAction
402 // that should result in pending
403 let bindings = [
404 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
405 KeyBinding::new("space w w", NoAction {}, Some("editor")),
406 KeyBinding::new("space w x", ActionAlpha {}, Some("editor")),
407 ];
408 let mut keymap = Keymap::default();
409 keymap.add_bindings(bindings.clone());
410
411 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
412 assert!(space_editor.0.is_empty());
413 assert_eq!(space_editor.1, true);
414
415 // Now test what happens if we have another binding defined BEFORE the NoAction
416 // that should result in pending
417 let bindings = [
418 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
419 KeyBinding::new("space w x", ActionAlpha {}, Some("editor")),
420 KeyBinding::new("space w w", NoAction {}, Some("editor")),
421 ];
422 let mut keymap = Keymap::default();
423 keymap.add_bindings(bindings.clone());
424
425 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
426 assert!(space_editor.0.is_empty());
427 assert_eq!(space_editor.1, true);
428
429 // Now test what happens if we have another binding defined at a higher context
430 // that should result in pending
431 let bindings = [
432 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
433 KeyBinding::new("space w x", ActionAlpha {}, Some("workspace")),
434 KeyBinding::new("space w w", NoAction {}, Some("editor")),
435 ];
436 let mut keymap = Keymap::default();
437 keymap.add_bindings(bindings.clone());
438
439 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
440 assert!(space_editor.0.is_empty());
441 assert_eq!(space_editor.1, true);
442 }
443
444 #[test]
445 fn test_bindings_for_action() {
446 let bindings = [
447 KeyBinding::new("ctrl-a", ActionAlpha {}, Some("pane")),
448 KeyBinding::new("ctrl-b", ActionBeta {}, Some("editor && mode == full")),
449 KeyBinding::new("ctrl-c", ActionGamma {}, Some("workspace")),
450 KeyBinding::new("ctrl-a", NoAction {}, Some("pane && active")),
451 KeyBinding::new("ctrl-b", NoAction {}, Some("editor")),
452 ];
453
454 let mut keymap = Keymap::default();
455 keymap.add_bindings(bindings.clone());
456
457 assert_bindings(&keymap, &ActionAlpha {}, &["ctrl-a"]);
458 assert_bindings(&keymap, &ActionBeta {}, &[]);
459 assert_bindings(&keymap, &ActionGamma {}, &["ctrl-c"]);
460
461 #[track_caller]
462 fn assert_bindings(keymap: &Keymap, action: &dyn Action, expected: &[&str]) {
463 let actual = keymap
464 .bindings_for_action(action)
465 .map(|binding| binding.keystrokes[0].unparse())
466 .collect::<Vec<_>>();
467 assert_eq!(actual, expected, "{:?}", action);
468 }
469 }
470}