A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
//! Key combos for the `key` tool (S24.2), such as `cmd+shift+t` or `return`, parsed into
//! modifiers and one macOS virtual key code (ANSI layout).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Modifiers {
pub cmd: bool,
pub shift: bool,
pub alt: bool,
pub ctrl: bool,
pub fn_key: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KeyCombo {
pub modifiers: Modifiers,
/// Canonical key name, for messages and the risk check.
pub key: &'static str,
/// macOS virtual key code (`kVK_*`).
pub code: u16,
}
impl KeyCombo {
/// The combo as one canonical name, modifiers first (`ctrl+a`, `shift+cmd+t`), for messages.
pub fn label(&self) -> String {
let m = self.modifiers;
let held = [(m.fn_key, "fn"), (m.ctrl, "ctrl"), (m.alt, "alt"), (m.shift, "shift"), (m.cmd, "cmd")];
let mut parts: Vec<&str> = held.iter().filter(|(on, _)| *on).map(|(_, name)| *name).collect();
parts.push(self.key);
parts.join("+")
}
/// Return (or Enter) with any modifiers: the key that submits forms and sends messages.
pub fn is_return(&self) -> bool {
self.key == "return"
}
/// Space with any modifiers: it presses the focused button.
pub fn is_space(&self) -> bool {
self.key == "space"
}
}
/// Named keys and their virtual key codes. Single characters use the ANSI layout.
const KEYS: &[(&str, u16)] = &[
("a", 0), ("s", 1), ("d", 2), ("f", 3), ("h", 4), ("g", 5), ("z", 6), ("x", 7), ("c", 8), ("v", 9),
("b", 11), ("q", 12), ("w", 13), ("e", 14), ("r", 15), ("y", 16), ("t", 17), ("1", 18), ("2", 19),
("3", 20), ("4", 21), ("6", 22), ("5", 23), ("=", 24), ("9", 25), ("7", 26), ("-", 27), ("8", 28),
("0", 29), ("]", 30), ("o", 31), ("u", 32), ("[", 33), ("i", 34), ("p", 35), ("return", 36), ("l", 37),
("j", 38), ("'", 39), ("k", 40), (";", 41), ("\\", 42), (",", 43), ("/", 44), ("n", 45), ("m", 46),
(".", 47), ("tab", 48), ("space", 49), ("`", 50), ("delete", 51), ("escape", 53), ("f5", 96), ("f6", 97),
("f7", 98), ("f3", 99), ("f8", 100), ("f9", 101), ("f11", 103), ("f10", 109), ("f12", 111), ("home", 115),
("pageup", 116), ("forwarddelete", 117), ("f4", 118), ("end", 119), ("f2", 120), ("pagedown", 121),
("f1", 122), ("left", 123), ("right", 124), ("down", 125), ("up", 126),
];
/// Every key name `parse_combo` accepts, aliases aside.
#[cfg(test)]
pub(crate) fn names() -> impl Iterator<Item = &'static str> {
KEYS.iter().map(|(name, _)| *name)
}
/// Other spellings of the named keys.
const ALIASES: &[(&str, &str)] = &[
("enter", "return"), ("esc", "escape"), ("backspace", "delete"), ("del", "forwarddelete"),
("page_up", "pageup"), ("page_down", "pagedown"), ("arrowleft", "left"), ("arrowright", "right"),
("arrowup", "up"), ("arrowdown", "down"), ("minus", "-"), ("equal", "="),
("comma", ","), ("period", "."), ("slash", "/"), ("backslash", "\\"),
];
/// Parses `mod+mod+key`: case-insensitive, parts joined by `+`, any number of modifiers
/// (`cmd`, `shift`, `alt`/`option`, `ctrl`/`control`, `fn`) and exactly one key.
pub fn parse_combo(combo: &str) -> Result<KeyCombo, String> {
let mut modifiers = Modifiers::default();
let mut key = None;
for part in combo.split('+') {
let part = part.trim().to_lowercase();
let flag = match part.as_str() {
"cmd" | "command" => &mut modifiers.cmd,
"shift" => &mut modifiers.shift,
"alt" | "option" | "opt" => &mut modifiers.alt,
"ctrl" | "control" => &mut modifiers.ctrl,
"fn" => &mut modifiers.fn_key,
_ => {
if key.is_some() {
return Err(format!("`{combo}` names more than one key"));
}
let name = ALIASES.iter().find(|(alias, _)| *alias == part).map_or(part.as_str(), |(_, name)| name);
let found = KEYS.iter().find(|(known, _)| *known == name);
key = Some(*found.ok_or_else(|| format!("unknown key `{part}` in `{combo}`"))?);
continue;
}
};
*flag = true;
}
let (key, code) = key.ok_or_else(|| format!("`{combo}` names no key"))?;
Ok(KeyCombo { modifiers, key, code })
}
#[cfg(test)]
mod tests {
use super::*;
fn mods(cmd: bool, shift: bool, alt: bool, ctrl: bool) -> Modifiers {
Modifiers { cmd, shift, alt, ctrl, fn_key: false }
}
#[test]
fn a_plain_named_key() {
let combo = parse_combo("return").unwrap();
assert_eq!((combo.key, combo.code, combo.modifiers), ("return", 36, Modifiers::default()));
}
#[test]
fn modifiers_and_a_letter() {
let combo = parse_combo("cmd+shift+t").unwrap();
assert_eq!((combo.key, combo.code, combo.modifiers), ("t", 17, mods(true, true, false, false)));
}
#[test]
fn modifier_spellings_and_case_are_accepted() {
let combo = parse_combo(" Command + Option + Control + A ").unwrap();
assert_eq!((combo.key, combo.code, combo.modifiers), ("a", 0, mods(true, false, true, true)));
assert_eq!(parse_combo("opt+ctrl+left").unwrap().modifiers, mods(false, false, true, true));
assert!(parse_combo("fn+f1").unwrap().modifiers.fn_key);
}
#[test]
fn aliases_name_the_same_key() {
assert_eq!(parse_combo("enter").unwrap().code, 36);
assert_eq!(parse_combo("esc").unwrap().code, 53);
assert_eq!(parse_combo("backspace").unwrap().code, 51);
assert_eq!(parse_combo("cmd+minus").unwrap().code, 27);
}
#[test]
fn digits_punctuation_and_function_keys() {
assert_eq!(parse_combo("cmd+1").unwrap().code, 18);
assert_eq!(parse_combo("cmd+,").unwrap().code, 43);
assert_eq!(parse_combo("f12").unwrap().code, 111);
assert_eq!(parse_combo("space").unwrap().code, 49);
}
#[test]
fn a_combo_is_labelled_with_its_modifiers() {
assert_eq!(parse_combo("ctrl+a").unwrap().label(), "ctrl+a");
assert_eq!(parse_combo("shift+command+t").unwrap().label(), "shift+cmd+t");
assert_eq!(parse_combo("fn+option+control+cmd+shift+f1").unwrap().label(), "fn+ctrl+alt+shift+cmd+f1");
assert_eq!(parse_combo("enter").unwrap().label(), "return");
}
#[test]
fn invalid_combos_are_rejected() {
for combo in ["", "cmd+", "cmd", "cmd+shift", "cmd+a+b", "hyper+a", "f13", "cmd++a"] {
assert!(parse_combo(combo).is_err(), "{combo:?} should be rejected");
}
}
#[test]
fn return_is_recognized_with_any_modifiers() {
assert!(parse_combo("return").unwrap().is_return());
assert!(parse_combo("cmd+return").unwrap().is_return());
assert!(parse_combo("ctrl+enter").unwrap().is_return());
assert!(!parse_combo("tab").unwrap().is_return());
}
}