From ecf91f077f58a544398ee9478c4cfa260cc92512 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 12:15:45 -0700 Subject: [PATCH] feat(hotkeys): read an skhdrc komorebi for Mac's users bind komorebic in an skhdrc, so that is the first file the crate reads. `skhd::parse` reads the whole syntax into the model: bindings with every modifier skhd has, literal keys and macOS keycodes, mode declarations (with `@` and an entry command), mode switches and bindings in one or more modes, per-application lists with `~` and `*`, `.blacklist`, and skhd.zig's `.define` command templates and application groups, which are expanded where they are used. A mode may be used before it is declared, so bindings are put in their modes at the end of the file. Reading never fails. Text that is not valid skhd is an error with its span and is skipped, up to the end of the line or of the list it opened, and reading goes on. What is valid but not realized the way skhd does it has a warning that says so: side-specific modifiers are the modifier, a capturing mode lets unbound keys through, `->` does not pass the key on, and `fn`, `.load`, `.alias`, key forwarding and key sequences are left out. Comments, continued lines and the line numbers of diagnostics are shared with the readers that follow. The tests cover the modifiers, macOS keycodes and the shifted symbol rule, comments and continued lines, modes, lists, defines, spans and recovery after an error, and the corpus test now checks that every skhdrc fixture reads into the keymap of its case. The keymaps of the other cases are written down too, for the readers to be written against. --- README.md | 6 +- docs/dev/ARCHITECTURE.md | 15 +- docs/dev/DESIGN.md | 12 + komorebi-hotkeys/src/lib.rs | 46 ++ komorebi-hotkeys/src/qt.rs | 10 + komorebi-hotkeys/src/skhd.rs | 1300 ++++++++++++++++++++++++++++++ komorebi-hotkeys/src/text.rs | 190 +++++ komorebi-hotkeys/tests/corpus.rs | 234 +++++- 8 files changed, 1806 insertions(+), 7 deletions(-) create mode 100644 komorebi-hotkeys/src/skhd.rs create mode 100644 komorebi-hotkeys/src/text.rs diff --git a/README.md b/README.md index dc0db4f7..79072a95 100644 --- a/README.md +++ b/README.md @@ -91,9 +91,9 @@ without a checkout of the toolchain. - [`komorebi-client`](komorebi-client): a library that sends messages to the daemon, reads its answers, subscribes to its notifications, and re-exports the types they are made of. -- [`komorebi-hotkeys`](komorebi-hotkeys): the key bindings of skhd, whkd and - sxhkd files in one model, with the keys as KDE stores them. It does not depend - on the daemon. Its tests read the files in +- [`komorebi-hotkeys`](komorebi-hotkeys): reads the key binding file of skhd + into a model that also has room for whkd's and sxhkd's, with the keys as KDE + stores them. It does not depend on the daemon. Its tests read the files in [`komorebi-hotkeys/tests/fixtures`](komorebi-hotkeys/tests/fixtures), where each case is written in every format that can express it. - [`komorebic`](komorebic): the command line. A subcommand that asks something diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md index 54f9c37b..5b0c0e97 100644 --- a/docs/dev/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -1584,6 +1584,7 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11). - **Diagnostic**: something about a file its user should know: its span (byte offsets and line), its severity (error, warning, note) and how faithfully the construct is realized (exactly, approximated, not at all). +- **Parsed**: a file, read: the keymap and the diagnostics. ### The parts @@ -1592,6 +1593,11 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11). `Combo`, which applies the shifted symbol rule: KWin matches the character a key press produced, so Alt+Shift+1 is registered as Alt+!. - [`ir`](../../komorebi-hotkeys/src/ir.rs): the model. +- [`skhd`](../../komorebi-hotkeys/src/skhd.rs): reads an skhdrc. A mode may be used before it + is declared, so each binding waits for the end of the file to be put in its modes. skhd.zig's + `.define` templates and application groups are expanded where they are used. +- [`text`](../../komorebi-hotkeys/src/text.rs): what the readers share: line numbers, comments, + continued lines and the diagnostics' wording. - [`tests/fixtures`](../../komorebi-hotkeys/tests/fixtures): the corpus, `.skhdrc`, `.whkdrc` and `.sxhkdrc`, each case in every format that can express it. @@ -1602,7 +1608,9 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11). | A combo is in the form KWin matches (the shifted symbol rule is applied) | type system: `Combo`'s fields are private, and `Combo::new` applies the rule | `compile_fail,E0451` on `Combo`; `shift_on_a_symbol_key_is_the_symbol_it_types` | none | | A key has the same code whichever vocabulary names it | test | `the_three_vocabularies_name_the_same_keys` | none | | Positional key names (macOS keycodes, `oem_*`) are read as on a US layout | convention only | none | none | -| The files of a corpus case mean the same keymap | convention only | `the_files_of_a_case_say_what_it_is_about_in_the_same_words` checks only that they start with the same comment | none | +| Reading a file returns a keymap, whatever the text | type system: a reader returns `Parsed`, not a `Result` | none | none | +| Text that is left out has a diagnostic that points at it | test | `what_cannot_be_read_is_reported_and_left_out`, `reading_goes_on_after_an_error`, `diagnostics_point_at_the_text_they_are_about` | none | +| A fixture reads, without errors, into the keymap of its case | test, for the skhdrc files; convention only for the others | `every_file_reads_without_errors_into_the_keymap_of_its_case` | none | ## Where to look in the code @@ -1778,8 +1786,9 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11). [`nix/tests/vm/suites/kwin-contract`](../../nix/tests/vm/suites/kwin-contract/test.py), the behavior of KWin's per-output virtual desktops komorebi relies on, with two outputs and no komorebi. -- [`komorebi-hotkeys/src/lib.rs`](../../komorebi-hotkeys/src/lib.rs): the key binding model, and - [`komorebi-hotkeys/src/qt.rs`](../../komorebi-hotkeys/src/qt.rs) the keys. +- [`komorebi-hotkeys/src/lib.rs`](../../komorebi-hotkeys/src/lib.rs): the key binding model, + [`komorebi-hotkeys/src/qt.rs`](../../komorebi-hotkeys/src/qt.rs) the keys, and one module per + format, [`skhd.rs`](../../komorebi-hotkeys/src/skhd.rs). - [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module; [`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py), diff --git a/docs/dev/DESIGN.md b/docs/dev/DESIGN.md index 9995c509..edb26b29 100644 --- a/docs/dev/DESIGN.md +++ b/docs/dev/DESIGN.md @@ -708,3 +708,15 @@ derives for the enum is an object with a `Placement` or an `Index` key, which th `JsonSchema` impl of [`PlacementTarget`](../../komorebi/src/core/mod.rs) calls "not what `Serialize` and `Deserialize` read and write". The schema `schema.json` has says a name, a number, or text that is a number, which is also what the module's typed `config` takes. + +## Why are the key binding files read by parsers written for komorebi? + +All three formats, skhd's, whkd's and sxhkd's, are read by parsers written by hand in +`komorebi-hotkeys`. For whkd there is a Rust parser, `whkd-parser`, under the same license +as komorebi, but it requires a `.shell pwsh|powershell|cmd` line, panics in `Shell::from` on +any other shell, and its per-application bindings match Windows process names. For skhd and +sxhkd the reason is not recorded; this entry needs one. + +What is not plain syntax is expanded while the file is read: skhd's `.define` templates and +application groups are replaced where they are used, so the model has only expanded bindings +in it. diff --git a/komorebi-hotkeys/src/lib.rs b/komorebi-hotkeys/src/lib.rs index 298934cd..c95751fd 100644 --- a/komorebi-hotkeys/src/lib.rs +++ b/komorebi-hotkeys/src/lib.rs @@ -40,11 +40,38 @@ //! //! Key names are read as on a US keyboard layout; [the `qt` module](qt#a-us-layout-only) says //! what that means for other layouts. +//! +//! # Reading a file +//! +//! Each format has a module with a `parse` function, which reads the text of a file into a +//! [`Parsed`]: the [`Keymap`] and the [diagnostics](Diagnostic) about the file. Reading never +//! fails. What is not valid syntax is skipped with an error, and what is valid but cannot be +//! realized on KDE, or only differently, is reported with a warning that says so. Each module +//! lists what it reads and what it does not. +//! +//! - [`skhd`]: an skhdrc, with modes, per-application bindings, `.blacklist` and skhd.zig's +//! `.define`. +//! +//! ```rust +//! use komorebi_hotkeys::{ParseOptions, Severity, skhd}; +//! +//! let parsed = skhd::parse( +//! "alt - h : komorebic focus left\nlalt - l : komorebic focus right\n", +//! &ParseOptions::default(), +//! ); +//! let bindings = &parsed.keymap.modes[0].bindings; +//! assert_eq!(bindings[1].chord[0].to_string(), "Alt+L"); +//! // KDE has no left Alt, so the binding is on either Alt, and the reader says so +//! assert_eq!(parsed.diagnostics[0].severity, Severity::Warning); +//! assert_eq!(parsed.diagnostics[0].span.line, 2); +//! ``` #![deny(missing_docs)] mod ir; pub mod qt; +pub mod skhd; +mod text; pub use ir::App; pub use ir::Binding; @@ -64,6 +91,25 @@ pub use ir::Span; pub use ir::Support; pub use ir::Then; +/// Options for reading a file. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct ParseOptions { + /// The keyboard layout to read positional key names with: skhd's macOS keycodes and whkd's + /// `oem_*` keys, and the [shifted symbol rule](qt#the-shifted-symbol-rule). + /// + /// The default for this is [`Layout::Us`](qt::Layout::Us), the only layout. + pub layout: qt::Layout, +} + +/// A file, read: its keymap, and what the reader has to say about it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Parsed { + /// The bindings that could be read. + pub keymap: Keymap, + /// The diagnostics, in the order of the text they are about. + pub diagnostics: Vec, +} + /// The file formats this crate reads. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub enum Format { diff --git a/komorebi-hotkeys/src/qt.rs b/komorebi-hotkeys/src/qt.rs index 77a923f2..ec153522 100644 --- a/komorebi-hotkeys/src/qt.rs +++ b/komorebi-hotkeys/src/qt.rs @@ -51,6 +51,16 @@ use std::fmt; use std::ops::BitOr; use std::ops::BitOrAssign; +/// A keyboard layout: which key is at each position, and which symbol Shift gives each key. +/// +/// The US layout is the only one. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum Layout { + /// The US layout. + #[default] + Us, +} + /// A set of modifiers, as the flags Qt or's into a key code. /// /// The four modifiers are the ones KDE knows. Side-specific modifiers (left Alt, right Alt) do diff --git a/komorebi-hotkeys/src/skhd.rs b/komorebi-hotkeys/src/skhd.rs new file mode 100644 index 00000000..680f6196 --- /dev/null +++ b/komorebi-hotkeys/src/skhd.rs @@ -0,0 +1,1300 @@ +//! Reading an skhdrc. +//! +//! An skhdrc is the file of skhd, the hotkey daemon of macOS, and of skhd.zig, which reads the +//! same syntax and adds to it. A binding is the modifiers, a `-`, the key, and then what it does: +//! +//! ```text +//! alt - h : komorebic focus left # runs a command +//! alt + shift - 0x21 : komorebic cycle-focus previous # a key named by its macOS keycode +//! alt - r ; resize # switches to a mode +//! resize < escape ; default # a binding of the mode `resize` +//! alt - n [ # one command per application +//! "firefox" : komorebic focus-workspace 1 +//! "kitty" ~ # kitty gets the key +//! * : komorebic focus-workspace 0 # every other application +//! ] +//! ``` +//! +//! [`parse`] reads it into a [`Keymap`]: +//! +//! ```rust +//! use komorebi_hotkeys::{Body, ParseOptions, Run, skhd}; +//! +//! let parsed = skhd::parse( +//! "alt + shift - 0x21 : komorebic cycle-focus previous # 0x21 is [\n", +//! &ParseOptions::default(), +//! ); +//! assert!(parsed.diagnostics.is_empty()); +//! +//! let binding = &parsed.keymap.modes[0].bindings[0]; +//! // Shift+[ types {, which is what KWin matches +//! assert_eq!(binding.chord[0].to_string(), "Alt+{"); +//! assert_eq!(binding.body, Body::Run(Run::Command("komorebic cycle-focus previous".into()))); +//! ``` +//! +//! # What is read, and how +//! +//! - **Bindings**: `mods - key : command`. The modifiers are `alt`, `shift`, `ctrl`, `cmd` (which +//! is Meta), `hyper` (all four) and `meh` (all but `cmd`). The key is a literal (`h`, `return`, +//! `f1`, `sound_up`...) or a macOS keycode in hex (`0x21`), read as the key at that position on +//! a US keyboard. A trailing ` # comment` is not part of the command, and a line that ends in +//! `\` continues on the next. +//! - **Modes**: `:: name` declares a mode, `:: name : command` with a command to run on entering +//! it; `key ; name` switches to it, and `name < key : command` (or `a, b < key ...`) binds a key +//! in it. A mode may be used before it is declared. +//! - **Per-application bindings**: `key [ "app" : command ... ]`, with `"app" ~` for an +//! application that gets the key itself and `*` for every other application. +//! - **`.blacklist [ "app" ... ]`**: applications in which no binding is active. +//! - **`.define`** (skhd.zig): `.define name : command {{1}}` is a command template, used as +//! `@name("argument")`, and `.define name ["app", ...]` a group of applications, used as +//! `@name` in a per-application list. Both are expanded where they are used. +//! +//! # What is not, and the diagnostics about it +//! +//! - `lalt`, `ralt` and the other side-specific modifiers are the modifier itself, since KDE does +//! not tell the sides apart ([`Support::Approximated`]). +//! - A capturing mode (`:: name @`) does not swallow the keys it has no binding for: they reach +//! the application ([`Support::Approximated`]). +//! - `->` does not pass the key on to the application ([`Support::Approximated`]). +//! - `.shell` is not followed: commands run through `sh -c` (a note). +//! - `fn`, a binding on a keycode that has no KDE key, `.load`, `.alias`, skhd.zig's key +//! forwarding (`|`) and key sequences (`,`), and any other directive are left out +//! ([`Support::Unsupported`]). +//! +//! Text that is not valid skhd syntax is an error and is skipped; reading goes on at the next +//! line. +//! +//! [`Keymap`]: crate::Keymap +//! [`Support::Approximated`]: crate::Support::Approximated +//! [`Support::Unsupported`]: crate::Support::Unsupported + +use crate::App; +use crate::Binding; +use crate::Body; +use crate::DEFAULT_MODE; +use crate::Define; +use crate::DefineValue; +use crate::Diagnostic; +use crate::Edge; +use crate::Format; +use crate::Keymap; +use crate::Mode; +use crate::ParseOptions; +use crate::Parsed; +use crate::Run; +use crate::Scope; +use crate::Span; +use crate::Support; +use crate::Then; +use crate::qt::Combo; +use crate::qt::Key; +use crate::qt::Layout; +use crate::qt::Mods; +use crate::qt::key_to_qt; +use crate::text; +use crate::text::Lines; + +/// Reads an skhdrc. +/// +/// Reading never fails: what cannot be read is left out, with a [`Diagnostic`] that says why. +/// The [module documentation](self) lists what is read and what is not. +/// +/// # Example +/// +/// ```rust +/// use komorebi_hotkeys::{ParseOptions, Severity, skhd}; +/// +/// let parsed = skhd::parse( +/// "alt - h : komorebic focus left\nfn - j : komorebic focus down\n", +/// &ParseOptions::default(), +/// ); +/// assert_eq!(parsed.keymap.modes[0].bindings.len(), 1); +/// assert_eq!( +/// parsed.diagnostics[0].to_string(), +/// "line 2: warning: the fn modifier does not exist on a PC keyboard", +/// ); +/// ``` +pub fn parse(text: &str, options: &ParseOptions) -> Parsed { + let mut reader = Reader::new(text, options.layout); + reader.run(); + reader.finish() +} + +/// A binding that waits for the modes to be known. +struct Pending { + modes: Vec<(String, Span)>, + binding: Binding, +} + +/// A mode declaration. +struct Declared { + name: String, + capture: bool, + on_enter: Option, +} + +struct Reader<'a> { + src: &'a str, + pos: usize, + lines: Lines, + layout: Layout, + keymap: Keymap, + diagnostics: Vec, + declared: Vec, + pending: Vec, + /// Where the `[` of the list being read is, so that an error inside skips the rest of it. + open_list: Option, +} + +impl<'a> Reader<'a> { + fn new(src: &'a str, layout: Layout) -> Reader<'a> { + Reader { + src, + pos: 0, + lines: Lines::new(src), + layout, + keymap: Keymap::new(Format::Skhd), + diagnostics: Vec::new(), + declared: Vec::new(), + pending: Vec::new(), + open_list: None, + } + } + + fn run(&mut self) { + loop { + self.skip_blank(); + let Some(c) = self.peek() else { break }; + let start = self.pos; + let result = if c == '.' { + self.directive(start) + } else if self.rest().starts_with("::") { + self.mode_declaration() + } else { + self.binding(start) + }; + if let Err(diagnostic) = result { + self.diagnostics.push(diagnostic); + self.recover(); + } + if self.pos == start { + // nothing was consumed: never loop on the same byte + self.skip_line(); + } + } + } + + fn finish(mut self) -> Parsed { + let mut keymap = self.keymap; + for declared in self.declared { + if declared.name == DEFAULT_MODE { + keymap.modes[0].capture = declared.capture; + keymap.modes[0].on_enter = declared.on_enter; + } else { + keymap.modes.push(Mode { + name: declared.name, + capture: declared.capture, + on_enter: declared.on_enter, + bindings: Vec::new(), + }); + } + } + + for pending in self.pending { + if let Some(target) = switches_to(&pending.binding.body) + && keymap.mode(&target).is_none() + { + self.diagnostics.push(text::error( + pending.binding.span, + format!("there is no mode `{target}` to switch to"), + )); + continue; + } + for (name, span) in &pending.modes { + match keymap.modes.iter_mut().find(|mode| mode.name == *name) { + Some(mode) => mode.bindings.push(pending.binding.clone()), + None => self.diagnostics.push(text::error( + *span, + format!("the mode `{name}` is not declared"), + )), + } + } + } + + self.diagnostics.sort_by_key(|d| d.span.start); + Parsed { + keymap, + diagnostics: self.diagnostics, + } + } + + fn binding(&mut self, start: usize) -> Result<(), Diagnostic> { + let modes = self.mode_list()?; + let combo = self.keysym()?; + self.skip_spaces(); + + if self.rest().starts_with("->") { + let span = self.span_here(2); + self.pos += 2; + self.diagnostics.push(text::approximated( + span, + "`->` passes the key on in skhd; here the application does not get it", + )); + self.skip_spaces(); + } + + let body = match self.peek() { + Some(':') => { + self.pos += 1; + Body::Run(Run::Command(self.command()?)) + } + Some(';') => { + self.pos += 1; + self.skip_spaces(); + let name = self + .word() + .ok_or_else(|| self.error_here("expected the name of a mode after `;`"))?; + self.end_of_line()?; + Body::Run(Run::Mode(name.to_string())) + } + Some('[') => { + self.open_list = Some(self.pos); + self.pos += 1; + let scopes = self.application_list()?; + self.open_list = None; + Body::Scoped(scopes) + } + Some('|') => { + let span = self.span_here(1); + self.skip_line(); + self.diagnostics.push(text::unsupported( + span, + "key forwarding (`|`) is not supported: the binding is left out", + )); + return Ok(()); + } + Some(',') => { + let span = self.span_here(1); + self.recover(); + self.diagnostics.push(text::unsupported( + span, + "key sequences (`,`) are not supported: the binding is left out", + )); + return Ok(()); + } + _ => return Err(self.error_here("expected `:` and a command, `;` and a mode, or `[`")), + }; + + let Some(combo) = combo else { + // a key or modifier that cannot be realized, already reported + return Ok(()); + }; + let modes = if modes.is_empty() { + vec![(DEFAULT_MODE.to_string(), self.lines.span(start, start))] + } else { + modes + }; + let span = self.lines.span(start, self.pos); + self.pending.push(Pending { + modes, + binding: Binding { + chord: vec![combo], + edge: Edge::Press, + body, + span, + source: text::one_line(&self.src[start..self.pos]), + }, + }); + Ok(()) + } + + /// `mode, mode <` before a binding, or nothing. + fn mode_list(&mut self) -> Result, Diagnostic> { + let save = self.pos; + let Some((first, first_span)) = self.word_spanned() else { + return Ok(Vec::new()); + }; + self.skip_spaces(); + if !matches!(self.peek(), Some(',' | '<')) { + self.pos = save; + return Ok(Vec::new()); + } + + let mut modes = vec![(first.to_string(), first_span)]; + while self.peek() == Some(',') { + self.pos += 1; + self.skip_spaces(); + let (name, span) = self + .word_spanned() + .ok_or_else(|| self.error_here("expected the name of a mode after `,`"))?; + modes.push((name.to_string(), span)); + self.skip_spaces(); + } + if self.peek() != Some('<') { + return Err(self.error_here("expected `<` after the modes")); + } + self.pos += 1; + self.skip_spaces(); + Ok(modes) + } + + /// `mods - key` or `key`. `None` when the keys are valid but cannot be realized. + fn keysym(&mut self) -> Result, Diagnostic> { + let first = self + .word_spanned() + .ok_or_else(|| self.error_here("expected a key"))?; + self.skip_spaces(); + + let is_dash = self.peek() == Some('-') && !self.rest().starts_with("->"); + let (modifiers, key) = if self.peek() == Some('+') || is_dash { + let mut modifiers = vec![first]; + while self.peek() == Some('+') { + self.pos += 1; + self.skip_spaces(); + modifiers.push( + self.word_spanned() + .ok_or_else(|| self.error_here("expected a modifier after `+`"))?, + ); + self.skip_spaces(); + } + if self.peek() != Some('-') { + return Err(self.error_here("expected `-` and a key after the modifiers")); + } + self.pos += 1; + self.skip_spaces(); + let key = self + .word_spanned() + .ok_or_else(|| self.error_here("expected a key after `-`"))?; + (modifiers, key) + } else { + (Vec::new(), first) + }; + + let mut mods = Mods::NONE; + let mut realizable = true; + for (word, span) in modifiers { + let lower = word.to_ascii_lowercase(); + mods |= match lower.as_str() { + "alt" => Mods::ALT, + "shift" => Mods::SHIFT, + "ctrl" => Mods::CTRL, + "cmd" => Mods::META, + "lalt" | "ralt" => { + self.diagnostics.push(text::one_sided(span, word, "Alt")); + Mods::ALT + } + "lshift" | "rshift" => { + self.diagnostics.push(text::one_sided(span, word, "Shift")); + Mods::SHIFT + } + "lctrl" | "rctrl" => { + self.diagnostics.push(text::one_sided(span, word, "Ctrl")); + Mods::CTRL + } + "lcmd" | "rcmd" => { + self.diagnostics.push(text::one_sided(span, word, "Meta")); + Mods::META + } + "hyper" => Mods::META | Mods::CTRL | Mods::ALT | Mods::SHIFT, + "meh" => Mods::CTRL | Mods::ALT | Mods::SHIFT, + "fn" => { + self.diagnostics.push(text::unsupported( + span, + "the fn modifier does not exist on a PC keyboard", + )); + realizable = false; + Mods::NONE + } + _ if word.starts_with('$') => { + self.diagnostics.push(text::unsupported( + span, + format!("`{word}` is an alias, and `.alias` is not supported"), + )); + realizable = false; + Mods::NONE + } + _ => { + return Err(text::error(span, format!("unknown modifier `{word}`"))); + } + }; + } + + let (name, span) = key; + let key = match self.key(name) { + Some(key) => key, + None if name.to_ascii_lowercase().starts_with("0x") => { + self.diagnostics.push(text::unsupported( + span, + format!("no KDE key for the macOS keycode {name}"), + )); + return Ok(None); + } + None if name.starts_with('$') => { + self.diagnostics.push(text::unsupported( + span, + format!("`{name}` is an alias, and `.alias` is not supported"), + )); + return Ok(None); + } + None => return Err(text::error(span, format!("no KDE key for `{name}`"))), + }; + + Ok(realizable.then(|| Combo::new(mods, key))) + } + + fn key(&self, name: &str) -> Option { + match self.layout { + Layout::Us => key_to_qt(Format::Skhd, name), + } + } + + /// The command after a `:`, to the end of the line, with continued lines joined and a + /// trailing comment dropped; a template is expanded. + fn command(&mut self) -> Result { + let start = self.pos; + let raw = self.rest_of_line(); + let joined = text::join_continued(raw); + let command = text::strip_comment(&joined).trim().to_string(); + let span = self.lines.span(start, self.pos); + if command.is_empty() { + return Err(text::error(span, "the command is empty")); + } + if command.starts_with('@') { + return self.expand(&command, span); + } + Ok(command) + } + + /// `@name("a", "b")`: the command template `name`, with its placeholders replaced. + fn expand(&self, call: &str, span: Span) -> Result { + let call = &call[1..]; + let (name, arguments) = match call.split_once('(') { + Some((name, rest)) => { + let Some(inside) = rest.trim_end().strip_suffix(')') else { + return Err(text::error( + span, + "expected `)` at the end of the arguments", + )); + }; + ( + name.trim(), + template_arguments(inside).ok_or_else(|| { + text::error( + span, + "the arguments of a template are strings in double quotes", + ) + })?, + ) + } + None => (call.trim(), Vec::new()), + }; + + let template = self + .keymap + .defines + .iter() + .find_map(|define| match &define.value { + DefineValue::Command(template) if define.name == name => Some(template), + _ => None, + }); + let Some(template) = template else { + return Err(text::error( + span, + format!("there is no command template `{name}`"), + )); + }; + + let mut command = template.clone(); + for (index, argument) in arguments.iter().enumerate() { + command = command.replace(&format!("{{{{{}}}}}", index + 1), argument); + } + if let Some(at) = command.find("{{") + && command[at + 2..].starts_with(|c: char| c.is_ascii_digit()) + { + return Err(text::error( + span, + format!( + "`@{name}` needs more arguments than the {} it has", + arguments.len() + ), + )); + } + Ok(command) + } + + /// `[ "app" : command | "app" ~ | * ... | @group ... ]`, after the `[`. + fn application_list(&mut self) -> Result, Diagnostic> { + let mut scopes = Vec::new(); + loop { + self.skip_blank(); + let apps = match self.peek() { + None => return Err(self.error_here("the list is not closed with `]`")), + Some(']') => { + self.pos += 1; + break; + } + Some('"') => vec![App::Named(self.string()?)], + Some('*') => { + self.pos += 1; + vec![App::Other] + } + Some('@') => { + self.pos += 1; + let (name, span) = self + .word_spanned() + .ok_or_else(|| self.error_here("expected the name of a group after `@`"))?; + let group = self + .keymap + .defines + .iter() + .find_map(|define| match &define.value { + DefineValue::Apps(apps) if define.name == name => Some(apps), + _ => None, + }); + match group { + Some(apps) => apps.iter().cloned().map(App::Named).collect(), + None => { + return Err(text::error( + span, + format!("there is no group of applications `{name}`"), + )); + } + } + } + _ => { + return Err( + self.error_here("expected an application in double quotes, `*` or `]`") + ); + } + }; + + self.skip_spaces(); + let then = match self.peek() { + Some('~') => { + self.pos += 1; + Then::Ignore + } + Some(':') => { + self.pos += 1; + Then::Run(Run::Command(self.command()?)) + } + _ => return Err(self.error_here("expected `:` and a command, or `~`")), + }; + for app in apps { + scopes.push(Scope { + app, + then: then.clone(), + }); + } + } + if scopes.is_empty() { + return Err(text::error( + self.lines.span(self.pos - 1, self.pos), + "the list of applications is empty", + )); + } + Ok(scopes) + } + + /// `:: name`, `:: name @`, `:: name : command`. + fn mode_declaration(&mut self) -> Result<(), Diagnostic> { + self.pos += 2; + self.skip_spaces(); + let (name, name_span) = self + .word_spanned() + .ok_or_else(|| self.error_here("expected the name of a mode after `::`"))?; + let name = name.to_string(); + self.skip_spaces(); + let capture = self.peek() == Some('@'); + if capture { + self.pos += 1; + self.skip_spaces(); + } + let on_enter = if self.peek() == Some(':') { + self.pos += 1; + Some(self.command()?) + } else { + self.end_of_line()?; + None + }; + + if self.declared.iter().any(|declared| declared.name == name) { + return Err(text::error( + name_span, + format!("the mode `{name}` is declared twice"), + )); + } + if capture { + self.diagnostics.push(text::approximated( + name_span, + format!( + "`{name}` captures every key in skhd; here the keys it has no binding for \ + reach the application" + ), + )); + } + self.declared.push(Declared { + name, + capture, + on_enter, + }); + Ok(()) + } + + fn directive(&mut self, start: usize) -> Result<(), Diagnostic> { + self.pos += 1; + let (name, name_span) = self + .word_spanned() + .ok_or_else(|| self.error_here("expected a directive after `.`"))?; + self.skip_spaces(); + match name { + "blacklist" => { + if self.peek() != Some('[') { + return Err(self.error_here("expected `[` after `.blacklist`")); + } + self.open_list = Some(self.pos); + self.pos += 1; + loop { + self.skip_blank(); + match self.peek() { + Some(']') => { + self.pos += 1; + break; + } + Some('"') => { + let app = self.string()?; + self.keymap.blacklist.push(app); + } + Some(',') => self.pos += 1, + _ => { + return Err( + self.error_here("expected an application in double quotes, or `]`") + ); + } + } + } + self.open_list = None; + } + "shell" => { + let shell = self.rest_of_line().trim().trim_matches('"').to_string(); + self.diagnostics.push(text::note( + self.lines.span(start, self.pos), + Support::Approximated, + format!("commands run through `sh -c`, not `{shell}`"), + )); + } + "load" => { + let file = self.rest_of_line().trim().to_string(); + self.diagnostics.push(text::unsupported( + self.lines.span(start, self.pos), + format!("`.load` is not followed: the bindings in {file} are not read"), + )); + } + "define" => { + let (define, define_span) = self + .word_spanned() + .ok_or_else(|| self.error_here("expected a name after `.define`"))?; + let define = define.to_string(); + self.skip_spaces(); + let value = match self.peek() { + Some(':') => { + self.pos += 1; + let raw = self.rest_of_line(); + let template = text::strip_comment(&text::join_continued(raw)) + .trim() + .to_string(); + DefineValue::Command(template) + } + Some('[') => { + self.open_list = Some(self.pos); + self.pos += 1; + let mut apps = Vec::new(); + loop { + self.skip_blank(); + match self.peek() { + Some(']') => { + self.pos += 1; + break; + } + Some(',') => self.pos += 1, + Some('"') => apps.push(self.string()?), + _ => { + return Err(self.error_here( + "expected an application in double quotes, or `]`", + )); + } + } + } + self.open_list = None; + DefineValue::Apps(apps) + } + _ => { + return Err(self.error_here( + "expected `:` and a command, or a list of applications in `[ ]`", + )); + } + }; + if self.keymap.defines.iter().any(|d| d.name == define) { + return Err(text::error( + define_span, + format!("`{define}` is defined twice"), + )); + } + self.keymap.defines.push(Define { + name: define, + value, + span: self.lines.span(start, self.pos), + }); + } + other => { + let other = other.to_string(); + self.recover(); + self.diagnostics.push(text::unsupported( + name_span, + format!("the directive `.{other}` is not supported"), + )); + } + } + Ok(()) + } + + // the cursor + + fn rest(&self) -> &'a str { + &self.src[self.pos..] + } + + fn peek(&self) -> Option { + self.rest().chars().next() + } + + fn span_here(&self, len: usize) -> Span { + self.lines + .span(self.pos, (self.pos + len).min(self.src.len())) + } + + fn error_here(&self, msg: &str) -> Diagnostic { + let len = self.peek().map_or(0, char::len_utf8); + let found = match self.peek() { + None => "the end of the file".to_string(), + Some('\n' | '\r') => "the end of the line".to_string(), + Some(c) => format!("`{c}`"), + }; + text::error(self.span_here(len), format!("{msg}, found {found}")) + } + + /// Skips spaces, tabs, line ends and comments. + fn skip_blank(&mut self) { + loop { + let rest = self.rest(); + let trimmed = rest.trim_start(); + self.pos += rest.len() - trimmed.len(); + if trimmed.starts_with('#') { + self.skip_line(); + } else { + break; + } + } + } + + /// Skips spaces and tabs, and a `\` that continues the line. + fn skip_spaces(&mut self) { + loop { + let rest = self.rest(); + if rest.starts_with([' ', '\t']) { + self.pos += 1; + } else if rest.starts_with("\\\n") { + self.pos += 2; + } else if rest.starts_with("\\\r\n") { + self.pos += 3; + } else { + break; + } + } + } + + /// Moves to the end of the line (before the line break). + fn skip_line(&mut self) { + let rest = self.rest(); + self.pos += rest.find('\n').unwrap_or(rest.len()); + } + + /// The rest of the line and every line it continues on, moving past them. + fn rest_of_line(&mut self) -> &'a str { + let start = self.pos; + loop { + self.skip_line(); + let line = self.src[start..self.pos].trim_end_matches('\r'); + if line.ends_with('\\') && self.pos < self.src.len() { + self.pos += 1; + } else { + break; + } + } + &self.src[start..self.pos] + } + + /// Requires nothing but a comment until the end of the line. + fn end_of_line(&mut self) -> Result<(), Diagnostic> { + self.skip_spaces(); + match self.peek() { + None | Some('\n' | '\r' | '#') => { + self.skip_line(); + Ok(()) + } + _ => Err(self.error_here("expected the end of the line")), + } + } + + /// After an error: skips the rest of the line, and the rest of a list it opened. + fn recover(&mut self) { + self.skip_line(); + let opened = self.open_list.take().is_some() + || (self.src[..self.pos].rsplit('\n').next()) + .is_some_and(|line| text::strip_comment(line).trim_end().ends_with('[')); + if opened { + while self.pos < self.src.len() { + self.pos += 1; + let start = self.pos; + self.skip_line(); + if self.src[start..self.pos].trim_start().starts_with(']') { + break; + } + } + } + } + + fn word_spanned(&mut self) -> Option<(&'a str, Span)> { + let start = self.pos; + let len = self + .rest() + .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_' || c == '$')) + .unwrap_or(self.rest().len()); + if len == 0 { + return None; + } + self.pos += len; + Some((&self.src[start..self.pos], self.lines.span(start, self.pos))) + } + + fn word(&mut self) -> Option<&'a str> { + self.word_spanned().map(|(word, _)| word) + } + + /// A string in double quotes, without the quotes. + fn string(&mut self) -> Result { + let start = self.pos; + let rest = &self.rest()[1..]; + match rest.find(['"', '\n']) { + Some(end) if rest[end..].starts_with('"') => { + self.pos += end + 2; + Ok(rest[..end].to_string()) + } + _ => Err(text::error( + self.lines.span(start, start + 1), + "the string is not closed with `\"`", + )), + } + } +} + +/// The mode a binding switches to, if it does. +fn switches_to(body: &Body) -> Option { + match body { + Body::Run(Run::Mode(name)) => Some(name.clone()), + _ => None, + } +} + +/// `"a", "b"`: the arguments of a template. +fn template_arguments(inside: &str) -> Option> { + let inside = inside.trim(); + if inside.is_empty() { + return Some(Vec::new()); + } + inside + .split(',') + .map(|argument| { + let argument = argument.trim(); + argument + .strip_prefix('"') + .and_then(|a| a.strip_suffix('"')) + .map(str::to_string) + }) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::Severity; + + fn read(text: &str) -> Parsed { + parse(text, &ParseOptions::default()) + } + + /// The keys and the command of a one-line skhdrc, or the first diagnostic. + fn one(line: &str) -> Result<(String, String), String> { + let parsed = read(line); + if let Some(diagnostic) = parsed.diagnostics.first() { + return Err(diagnostic.msg.clone()); + } + let binding = &parsed.keymap.modes[0].bindings[0]; + let Body::Run(Run::Command(command)) = &binding.body else { + panic!("{line}: {:?}", binding.body); + }; + Ok((binding.chord[0].to_string(), command.clone())) + } + + fn errors(parsed: &Parsed) -> Vec { + parsed.diagnostics.iter().map(ToString::to_string).collect() + } + + #[test] + fn modifiers_and_letters_carry_over() { + assert_eq!( + one("alt - h : komorebic focus left").unwrap(), + ("Alt+H".into(), "komorebic focus left".into()) + ); + assert_eq!( + one("alt + shift - return : komorebic promote").unwrap().0, + "Alt+Shift+Return" + ); + assert_eq!( + one("ctrl + alt - left : komorebic stack left").unwrap().0, + "Ctrl+Alt+Left" + ); + assert_eq!( + one("alt - 1 : komorebic focus-workspace 0").unwrap().0, + "Alt+1" + ); + // no spaces, and no modifier + assert_eq!(one("alt-h:x").unwrap(), ("Alt+H".into(), "x".into())); + assert_eq!(one("f1 : x").unwrap().0, "F1"); + } + + #[test] + fn modifiers_are_written_in_the_order_qt_writes_them() { + assert_eq!( + one("shift + alt + ctrl + cmd - a : x").unwrap().0, + "Meta+Ctrl+Alt+Shift+A" + ); + assert_eq!(one("hyper - a : x").unwrap().0, "Meta+Ctrl+Alt+Shift+A"); + assert_eq!(one("meh - a : x").unwrap().0, "Ctrl+Alt+Shift+A"); + } + + #[test] + fn macos_keycodes_become_the_key_they_are() { + assert_eq!(one("alt + shift - 0x21 : x").unwrap().0, "Alt+{"); + assert_eq!(one("alt + shift - 0x1E : x").unwrap().0, "Alt+}"); + assert_eq!(one("alt - 0x29 : x").unwrap().0, "Alt+;"); + assert_eq!(one("alt - 0x18 : x").unwrap().0, "Alt+="); + assert_eq!(one("alt - 0x1B : x").unwrap().0, "Alt+-"); + assert_eq!( + one("alt - 0xFF : x").unwrap_err(), + "no KDE key for the macOS keycode 0xFF" + ); + } + + #[test] + fn shift_on_a_symbol_key_is_the_symbol_it_types() { + assert_eq!(one("alt + shift - 1 : x").unwrap().0, "Alt+!"); + assert_eq!(one("alt + shift - 0x29 : x").unwrap().0, "Alt+:"); + assert_eq!(one("alt + shift - 0x18 : x").unwrap().0, "Alt++"); + assert_eq!(one("alt + shift - 0x1B : x").unwrap().0, "Alt+_"); + assert_eq!(one("ctrl + alt + shift - 9 : x").unwrap().0, "Ctrl+Alt+("); + // letters and named keys keep their Shift + assert_eq!(one("alt + shift - h : x").unwrap().0, "Alt+Shift+H"); + assert_eq!( + one("alt + shift - return : x").unwrap().0, + "Alt+Shift+Return" + ); + assert_eq!(one("ctrl + shift - left : x").unwrap().0, "Ctrl+Shift+Left"); + } + + #[test] + fn a_trailing_comment_is_not_part_of_the_command() { + assert_eq!( + one("alt - 0x29 : komorebic unstack # 0x29 is ;").unwrap().1, + "komorebic unstack" + ); + assert_eq!( + one("alt - a : echo '# not a comment'").unwrap().1, + "echo '# not a comment'" + ); + assert_eq!(one("alt - a : echo a#b").unwrap().1, "echo a#b"); + } + + #[test] + fn a_continued_line_is_one_binding() { + let parsed = read("alt - a : komorebic focus \\\n left\n# done\n"); + assert!(parsed.diagnostics.is_empty()); + let bindings = &parsed.keymap.modes[0].bindings; + assert_eq!(bindings.len(), 1); + assert_eq!( + bindings[0].body, + Body::Run(Run::Command("komorebic focus left".into())) + ); + assert_eq!(bindings[0].span.line, 1); + assert_eq!(bindings[0].source, "alt - a : komorebic focus left"); + } + + #[test] + fn what_cannot_be_read_is_reported_and_left_out() { + for (line, message) in [ + ( + "fn - a : x", + "the fn modifier does not exist on a PC keyboard", + ), + ("alt - a ; other", "there is no mode `other` to switch to"), + ("alt - , : x", "expected a key after `-`, found `,`"), + ( + "hyper - a", + "expected `:` and a command, `;` and a mode, or `[`, found the end of the file", + ), + ("alt - a :", "the command is empty"), + ("super - a : x", "unknown modifier `super`"), + ("alt - nope : x", "no KDE key for `nope`"), + ( + "ctrl - 1 | cmd - 1", + "key forwarding (`|`) is not supported: the binding is left out", + ), + ( + "cmd - q, cmd - q : x", + "key sequences (`,`) are not supported: the binding is left out", + ), + ( + "$hyper - a : x", + "`$hyper` is an alias, and `.alias` is not supported", + ), + ( + ".alias $hyper cmd + alt", + "the directive `.alias` is not supported", + ), + ] { + let parsed = read(line); + assert_eq!( + parsed + .keymap + .modes + .iter() + .map(|m| m.bindings.len()) + .sum::(), + 0, + "{line}" + ); + assert_eq!( + parsed + .diagnostics + .iter() + .map(|d| d.msg.as_str()) + .collect::>(), + [message], + "{line}" + ); + } + } + + #[test] + fn reading_goes_on_after_an_error() { + let parsed = + read("alt - a [\n \"x\" : one\n oops\n]\nalt - b : two\nalt - c : three # done\n"); + let bindings = &parsed.keymap.modes[0].bindings; + assert_eq!( + bindings + .iter() + .map(|b| b.chord[0].to_string()) + .collect::>(), + ["Alt+B", "Alt+C"] + ); + assert_eq!( + errors(&parsed), + ["line 3: error: expected an application in double quotes, `*` or `]`, found `o`"] + ); + } + + #[test] + fn diagnostics_point_at_the_text_they_are_about() { + let text = "alt - h : x\nlalt - j : y\n"; + let parsed = read(text); + let diagnostic = &parsed.diagnostics[0]; + assert_eq!(diagnostic.severity, Severity::Warning); + assert_eq!(diagnostic.support, Support::Approximated); + assert_eq!(diagnostic.span.line, 2); + assert_eq!(&text[diagnostic.span.start..diagnostic.span.end], "lalt"); + assert_eq!( + diagnostic.msg, + "`lalt` is Alt: KDE does not tell the left and right Alt apart" + ); + // the binding is kept, with Alt + assert_eq!( + parsed.keymap.modes[0].bindings[1].chord[0].to_string(), + "Alt+J" + ); + let binding = &parsed.keymap.modes[0].bindings[1]; + assert_eq!(&text[binding.span.start..binding.span.end], "lalt - j : y"); + } + + #[test] + fn modes_are_declared_entered_and_bound() { + let parsed = read( + ":: resize @ : notify-send resize\n\ + alt - r ; resize\n\ + resize < h : komorebic resize-edge left increase\n\ + resize < escape ; default\n\ + default, resize < alt - q : komorebic close\n", + ); + let keymap = &parsed.keymap; + assert_eq!( + keymap + .modes + .iter() + .map(|m| m.name.as_str()) + .collect::>(), + ["default", "resize"] + ); + let resize = keymap.mode("resize").unwrap(); + assert!(resize.capture); + assert_eq!(resize.on_enter.as_deref(), Some("notify-send resize")); + assert_eq!(resize.bindings.len(), 3); + assert_eq!( + resize.bindings[1].body, + Body::Run(Run::Mode("default".into())) + ); + assert_eq!(resize.bindings[1].chord[0].to_string(), "Esc"); + let default = keymap.mode("default").unwrap(); + assert_eq!(default.bindings.len(), 2); + assert_eq!( + default.bindings[0].body, + Body::Run(Run::Mode("resize".into())) + ); + assert_eq!( + errors(&parsed), + [ + "line 1: warning: `resize` captures every key in skhd; here the keys it has no \ + binding for reach the application" + ] + ); + } + + #[test] + fn a_mode_may_be_used_before_it_is_declared_but_not_without() { + let parsed = read("alt - r ; resize\nresize < h : x\nother < h : y\n:: resize\n"); + assert_eq!(parsed.keymap.mode("resize").unwrap().bindings.len(), 1); + assert_eq!( + errors(&parsed), + ["line 3: error: the mode `other` is not declared"] + ); + } + + #[test] + fn the_default_mode_can_have_a_command() { + let parsed = read(":: default : echo back\nalt - h : x\n"); + assert_eq!(parsed.keymap.modes.len(), 1); + assert_eq!( + parsed.keymap.modes[0].on_enter.as_deref(), + Some("echo back") + ); + assert!(!parsed.keymap.declares_modes()); + } + + #[test] + fn a_binding_can_do_something_else_in_each_application() { + let parsed = read( + "alt - n [\n\ + \x20 \"firefox\" : komorebic focus-workspace 1 # a comment\n\ + \x20 \"kitty\" ~\n\ + \x20 * : komorebic focus-workspace 0\n\ + ]\n", + ); + assert!(parsed.diagnostics.is_empty(), "{:?}", parsed.diagnostics); + let binding = &parsed.keymap.modes[0].bindings[0]; + assert_eq!( + binding.body, + Body::Scoped(vec![ + Scope { + app: App::Named("firefox".into()), + then: Then::Run(Run::Command("komorebic focus-workspace 1".into())), + }, + Scope { + app: App::Named("kitty".into()), + then: Then::Ignore, + }, + Scope { + app: App::Other, + then: Then::Run(Run::Command("komorebic focus-workspace 0".into())), + }, + ]) + ); + assert_eq!(binding.span.line, 1); + assert_eq!( + binding.source, + "alt - n [ \"firefox\" : komorebic focus-workspace 1 # a comment \"kitty\" ~ * : \ + komorebic focus-workspace 0 ]" + ); + } + + #[test] + fn defines_are_expanded_where_they_are_used() { + let parsed = read( + ".define focus : komorebic focus {{1}} # a template\n\ + .define two : echo {{1}} {{2}}\n\ + .define browsers [\"firefox\", \"chromium\"]\n\ + alt - h : @focus(\"left\")\n\ + alt - b [\n @browsers : komorebic toggle-monocle\n]\n\ + alt - t : @two(\"a\")\n\ + alt - u : @nothing\n", + ); + let bindings = &parsed.keymap.modes[0].bindings; + assert_eq!( + bindings[0].body, + Body::Run(Run::Command("komorebic focus left".into())) + ); + let Body::Scoped(scopes) = &bindings[1].body else { + panic!("{:?}", bindings[1].body) + }; + assert_eq!( + scopes.iter().map(|s| s.app.clone()).collect::>(), + [App::Named("firefox".into()), App::Named("chromium".into())] + ); + assert_eq!(bindings.len(), 2); + assert_eq!( + parsed.keymap.defines[0].value, + DefineValue::Command("komorebic focus {{1}}".into()) + ); + assert_eq!( + errors(&parsed), + [ + "line 8: error: `@two` needs more arguments than the 1 it has", + "line 9: error: there is no command template `nothing`", + ] + ); + } + + #[test] + fn the_blacklist_and_the_other_directives() { + let parsed = read( + ".blacklist [\n \"steam\"\n \"dota2\"\n]\n\ + .shell \"/bin/dash\"\n\ + .load \"~/.config/skhd/more\"\n\ + alt - h : x\n", + ); + assert_eq!(parsed.keymap.blacklist, ["steam", "dota2"]); + assert_eq!(parsed.keymap.modes[0].bindings.len(), 1); + assert_eq!( + errors(&parsed), + [ + "line 5: note: commands run through `sh -c`, not `/bin/dash`", + "line 6: warning: `.load` is not followed: the bindings in \ + \"~/.config/skhd/more\" are not read", + ] + ); + } + + #[test] + fn passing_the_key_on_is_approximated() { + let parsed = read("cmd - p -> : echo hi\n"); + assert_eq!(parsed.keymap.modes[0].bindings.len(), 1); + assert_eq!(parsed.diagnostics[0].support, Support::Approximated); + } +} diff --git a/komorebi-hotkeys/src/text.rs b/komorebi-hotkeys/src/text.rs new file mode 100644 index 00000000..ff2b78c2 --- /dev/null +++ b/komorebi-hotkeys/src/text.rs @@ -0,0 +1,190 @@ +//! What the readers share: line numbers, diagnostics, comments and continued lines. + +use crate::Diagnostic; +use crate::Severity; +use crate::Span; +use crate::Support; + +/// The byte offset at which each line of a text starts. +pub(crate) struct Lines { + starts: Vec, +} + +impl Lines { + pub(crate) fn new(text: &str) -> Lines { + let mut starts = vec![0]; + starts.extend(text.match_indices('\n').map(|(i, _)| i + 1)); + Lines { starts } + } + + /// The span from `start` to `end`, with the line of `start`. + pub(crate) fn span(&self, start: usize, end: usize) -> Span { + let line = self.starts.partition_point(|&s| s <= start); + Span { start, end, line } + } +} + +pub(crate) fn error(span: Span, msg: impl Into) -> Diagnostic { + Diagnostic { + span, + severity: Severity::Error, + support: Support::Unsupported, + msg: msg.into(), + } +} + +pub(crate) fn approximated(span: Span, msg: impl Into) -> Diagnostic { + Diagnostic { + span, + severity: Severity::Warning, + support: Support::Approximated, + msg: msg.into(), + } +} + +pub(crate) fn unsupported(span: Span, msg: impl Into) -> Diagnostic { + Diagnostic { + span, + severity: Severity::Warning, + support: Support::Unsupported, + msg: msg.into(), + } +} + +pub(crate) fn note(span: Span, support: Support, msg: impl Into) -> Diagnostic { + Diagnostic { + span, + severity: Severity::Note, + support, + msg: msg.into(), + } +} + +/// The diagnostic for a side-specific modifier, which KDE does not have. +pub(crate) fn one_sided(span: Span, written: &str, kde: &str) -> Diagnostic { + approximated( + span, + format!("`{written}` is {kde}: KDE does not tell the left and right {kde} apart"), + ) +} + +/// Drops a trailing ` # comment` from a command, unless the `#` is quoted or part of a word. +pub(crate) fn strip_comment(command: &str) -> &str { + let mut quote: Option = None; + let mut previous = ' '; + for (index, c) in command.char_indices() { + match (quote, c) { + (Some(q), c) if c == q => quote = None, + (None, '"' | '\'') => quote = Some(c), + (None, '#') if previous.is_whitespace() => return &command[..index], + _ => {} + } + previous = c; + } + command +} + +/// Joins the lines of `text` that end in `\` with the next, with one space between the two. +pub(crate) fn join_continued(text: &str) -> String { + let mut joined = String::new(); + let mut lines = text.split('\n').peekable(); + while let Some(line) = lines.next() { + let line = line.strip_suffix('\r').unwrap_or(line); + match line.strip_suffix('\\') { + Some(continued) if lines.peek().is_some() => { + joined.push_str(continued.trim_end()); + joined.push(' '); + if let Some(next) = lines.peek_mut() { + *next = next.trim_start(); + } + } + _ => { + joined.push_str(line); + if lines.peek().is_some() { + joined.push('\n'); + } + } + } + } + joined +} + +/// The text of a binding as it was written, on one line: continued lines are joined, and the +/// lines of a block are trimmed and joined with a space. +pub(crate) fn one_line(text: &str) -> String { + let mut out = String::new(); + let mut lines = text.split('\n').peekable(); + while let Some(line) = lines.next() { + let line = line.strip_suffix('\r').unwrap_or(line); + match line.strip_suffix('\\') { + Some(continued) if lines.peek().is_some() => { + out.push_str(continued); + out.push(' '); + } + _ => { + out.push_str(line.trim_end()); + if lines.peek().is_some() { + out.push(' '); + if let Some(next) = lines.peek_mut() { + *next = next.trim_start(); + } + } + } + } + } + out.trim().to_string() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_trailing_comment_is_not_part_of_the_command() { + assert_eq!( + strip_comment("komorebic unstack # 0x29 is ;").trim(), + "komorebic unstack" + ); + assert_eq!( + strip_comment("echo '# not a comment'"), + "echo '# not a comment'" + ); + assert_eq!(strip_comment("echo a#b"), "echo a#b"); + } + + #[test] + fn lines_are_counted_from_one() { + let lines = Lines::new("a\nbc\n\nd"); + assert_eq!(lines.span(0, 1).line, 1); + assert_eq!(lines.span(2, 3).line, 2); + assert_eq!(lines.span(5, 5).line, 3); + assert_eq!(lines.span(6, 7).line, 4); + } + + #[test] + fn a_continued_line_is_joined_with_one_space() { + assert_eq!( + join_continued("komorebic focus \\\n left"), + "komorebic focus left" + ); + assert_eq!(join_continued("a\\\nb\\\n c\nd"), "a b c\nd"); + // a backslash on the last line continues nothing + assert_eq!(join_continued("a \\"), "a \\"); + } + + #[test] + fn a_binding_is_written_on_one_line() { + assert_eq!( + one_line("alt - x : komorebic \\\n flip-layout"), + "alt - x : komorebic flip-layout" + ); + assert_eq!( + one_line("alt - n [\n \"a\" : x\n * ~\n]"), + "alt - n [ \"a\" : x * ~ ]" + ); + assert_eq!( + one_line("alt - h : komorebic focus left"), + "alt - h : komorebic focus left" + ); + } +} diff --git a/komorebi-hotkeys/tests/corpus.rs b/komorebi-hotkeys/tests/corpus.rs index 00b2cdaa..6eb6c8b2 100644 --- a/komorebi-hotkeys/tests/corpus.rs +++ b/komorebi-hotkeys/tests/corpus.rs @@ -2,8 +2,20 @@ //! //! Each case is a file per format in `tests/fixtures`, `.skhdrc`, `.whkdrc` and //! `.sxhkdrc`, for the formats that can express the case. The files of a case mean the same -//! keymap, and start with the same comment, which says what the case is about. +//! keymap, and start with the same comment, which says what the case is about. [`EXPECTED`] is +//! that keymap, written out by [`render`]. +use komorebi_hotkeys::App; +use komorebi_hotkeys::Body; +use komorebi_hotkeys::DEFAULT_MODE; +use komorebi_hotkeys::Edge; +use komorebi_hotkeys::Keymap; +use komorebi_hotkeys::ParseOptions; +use komorebi_hotkeys::Parsed; +use komorebi_hotkeys::Run; +use komorebi_hotkeys::Severity; +use komorebi_hotkeys::Then; +use komorebi_hotkeys::skhd; use std::path::PathBuf; /// Every case, and the formats it is written in. @@ -23,6 +35,169 @@ const CASES: &[(&str, &[&str])] = &[ ("release", &["sxhkdrc"]), ]; +/// The keymap of each case, as [`render`] writes it. +const EXPECTED: &[(&str, &str)] = &[ + ( + "plain", + "Alt+H: komorebic focus left +Alt+J: komorebic focus down +Alt+K: komorebic focus up +Alt+L: komorebic focus right +Alt+Q: komorebic close", + ), + ( + "modifiers", + "Meta+Return: konsole +Ctrl+Alt+Left: komorebic stack left +Alt+Shift+H: komorebic move left +Ctrl+Shift+Right: komorebic resize-edge right increase +Alt+!: komorebic move-to-workspace 0 +Ctrl+Alt+(: komorebic move-to-workspace 8 +Meta+Ctrl+Alt+Shift+A: komorebic retile +Ctrl+Alt+Shift+M: komorebic toggle-monocle", + ), + ( + "keycodes", + "Alt+[: komorebic cycle-stack previous +Alt+]: komorebic cycle-stack next +Alt+;: komorebic unstack +Alt+=: komorebic resize-axis horizontal increase +Alt+-: komorebic resize-axis horizontal decrease +Alt+{: komorebic cycle-focus previous", + ), + ( + "comments", + "Alt+H: komorebic focus left +Alt+X: komorebic flip-layout horizontal", + ), + ( + "braces", + "Alt+H: komorebic focus left +Alt+J: komorebic focus down +Alt+K: komorebic focus up +Alt+L: komorebic focus right +Alt+1: komorebic focus-workspace 0 +Alt+2: komorebic focus-workspace 1 +Alt+3: komorebic focus-workspace 2 +Alt+!: komorebic move-to-workspace 0 +Alt+@: komorebic move-to-workspace 1 +Alt+#: komorebic move-to-workspace 2", + ), + ( + "scopes", + "Alt+N: firefox: komorebic focus-workspace 1 | kitty: ignore | *: komorebic focus-workspace 0 +Alt+H: komorebic focus left", + ), + ( + "define", + "Alt+B: firefox: komorebic toggle-monocle | chromium: komorebic toggle-monocle | *: ignore +Alt+H: komorebic focus left +Alt+L: komorebic focus right", + ), + ( + "blacklist", + "blacklist: steam, dota2 +Alt+H: komorebic focus left", + ), + ( + "modes", + "Alt+R: mode resize +Alt+Q: komorebic close +mode resize, captures, on enter: notify-send resize +[resize] H: komorebic resize-edge left increase +[resize] L: komorebic resize-edge right increase +[resize] Esc: mode default +[resize] Alt+Q: komorebic close", + ), + ( + "pause", + "pause Alt+Shift+P: komorebic toggle-pause +Alt+H: komorebic focus left", + ), + ( + "chords", + "Alt+W, H: komorebic move left +Alt+W, L: komorebic move right +Alt+R: mode Alt+R +mode Alt+R +[Alt+R] H: komorebic resize-edge left increase +[Alt+R] L: komorebic resize-edge right increase +[Alt+R] Esc: mode default", + ), + ("release", "release Alt+Space: komorebic toggle-float"), +]; + +/// Writes a keymap out, one line per binding, mode, blacklist and pause binding. Where each binding +/// was written, and the defines, are left out. +fn render(keymap: &Keymap) -> String { + let run = |run: &Run| match run { + Run::Command(command) => command.clone(), + Run::Mode(mode) => format!("mode {mode}"), + }; + let mut lines = Vec::new(); + if !keymap.blacklist.is_empty() { + lines.push(format!("blacklist: {}", keymap.blacklist.join(", "))); + } + if let Some(pause) = &keymap.pause { + lines.push(format!( + "pause {}: {}", + pause.combo, + pause.hook.as_deref().unwrap_or("nothing") + )); + } + for mode in &keymap.modes { + let prefix = if mode.name == DEFAULT_MODE { + String::new() + } else { + let mut header = format!("mode {}", mode.name); + if mode.capture { + header.push_str(", captures"); + } + if let Some(command) = &mode.on_enter { + header.push_str(&format!(", on enter: {command}")); + } + lines.push(header); + format!("[{}] ", mode.name) + }; + for binding in &mode.bindings { + let chord: Vec = binding.chord.iter().map(ToString::to_string).collect(); + let edge = match binding.edge { + Edge::Press => "", + Edge::Release => "release ", + }; + let body = match &binding.body { + Body::Run(action) => run(action), + Body::Scoped(scopes) => scopes + .iter() + .map(|scope| { + let app = match &scope.app { + App::Named(name) => name.as_str(), + App::Other => "*", + }; + let then = match &scope.then { + Then::Run(action) => run(action), + Then::Ignore => "ignore".to_string(), + }; + format!("{app}: {then}") + }) + .collect::>() + .join(" | "), + }; + lines.push(format!("{prefix}{edge}{}: {body}", chord.join(", "))); + } + } + lines.join("\n") +} + +/// Reads a fixture in the format its extension names. +fn parse(extension: &str, text: &str) -> Option { + let options = ParseOptions::default(); + match extension { + "skhdrc" => Some(skhd::parse(text, &options)), + _ => None, + } +} + fn fixtures() -> PathBuf { PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures") } @@ -63,3 +238,60 @@ fn the_files_of_a_case_say_what_it_is_about_in_the_same_words() { ); } } + +#[test] +fn every_file_reads_without_errors_into_the_keymap_of_its_case() { + for (case, extensions) in CASES { + for extension in *extensions { + let Some(parsed) = parse(extension, &read(case, extension)) else { + continue; + }; + let errors: Vec = parsed + .diagnostics + .iter() + .filter(|d| d.severity == Severity::Error) + .map(ToString::to_string) + .collect(); + assert!(errors.is_empty(), "{case}.{extension}: {errors:#?}"); + + if let Some((_, expected)) = EXPECTED.iter().find(|(c, _)| c == case) { + assert_eq!(render(&parsed.keymap), *expected, "{case}.{extension}"); + } + } + } +} + +#[test] +fn every_case_but_the_sample_has_an_expected_keymap() { + for (case, _) in CASES { + let expected = EXPECTED.iter().any(|(c, _)| c == case); + assert_eq!(expected, *case != "sample", "{case}"); + } +} + +#[test] +fn the_sample_reads_completely() { + for extension in ["skhdrc"] { + let parsed = parse(extension, &read("sample", extension)).unwrap(); + assert!(parsed.diagnostics.is_empty(), "{:#?}", parsed.diagnostics); + let bindings = &parsed.keymap.modes[0].bindings; + assert_eq!(bindings.len(), 50); + + let rendered = render(&parsed.keymap); + for line in [ + "Alt+L: komorebic focus right", + "Alt+{: komorebic cycle-focus previous", + "Alt+[: komorebic cycle-stack previous", + "Alt+(: komorebic move-to-workspace 8", + "Alt+=: komorebic resize-axis horizontal increase", + ] { + assert!(rendered.lines().any(|l| l == line), "{extension}: {line}"); + } + + // no two bindings share a key + let mut keys: Vec<_> = bindings.iter().map(|b| b.chord.clone()).collect(); + keys.sort(); + keys.dedup(); + assert_eq!(keys.len(), bindings.len()); + } +}