From e9e62319e8967e113f01e7fc29d2ab55d193191e Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Fri, 30 Oct 2026 20:45:57 -0700 Subject: [PATCH] refactor(ring): make the macOS ring.rs identical to the documented one macOS ring.rs becomes the KDE copy (doc comments, unit tests, std path in the macro; pastey was already used). After this the three ring.rs and lockable_sequence.rs files are byte-identical (cmp). Verified: fast-check macOS fake-CC cargo check --workspace --all-targets: PASS. Not run: tests (macOS cannot run). --- komorebi-for-mac/komorebi/src/ring.rs | 131 +++++++++++++++++++++++++- 1 file changed, 129 insertions(+), 2 deletions(-) diff --git a/komorebi-for-mac/komorebi/src/ring.rs b/komorebi-for-mac/komorebi/src/ring.rs index 147f8da7..ae8b2f25 100644 --- a/komorebi-for-mac/komorebi/src/ring.rs +++ b/komorebi-for-mac/komorebi/src/ring.rs @@ -1,8 +1,33 @@ +//! [`Ring`], a list of elements with one of them focused. +//! +//! Monitors, workspaces and containers each keep their children in a ring, so that "the focused +//! one" is the same thing everywhere, and `impl_ring_elements!` gives each of them the same +//! accessors for it. + use std::collections::VecDeque; use serde::Deserialize; use serde::Serialize; +/// A list of elements, one of which is focused. +/// +/// The focused index is not guaranteed to be in range: [`Ring::focus`] stores what it is given, and +/// [`Ring::focused`] and [`Ring::focused_mut`] return `None` when it is out of range, as it is for +/// an empty ring. +/// +/// # Example +/// +/// ```rust +/// use komorebi::ring::Ring; +/// +/// let mut ring = Ring::default(); +/// ring.elements_mut().push_back("a"); +/// ring.elements_mut().push_back("b"); +/// ring.focus(1); +/// +/// assert_eq!(ring.focused(), Some(&"b")); +/// assert_eq!(ring.focused_idx(), 1); +/// ``` #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] pub struct Ring { @@ -20,31 +45,44 @@ impl Default for Ring { } impl Ring { + /// The elements, in order. pub const fn elements(&self) -> &VecDeque { &self.elements } + /// The elements, in order, to add to or remove from. pub fn elements_mut(&mut self) -> &mut VecDeque { &mut self.elements } + /// Focuses the element at `idx`. pub fn focus(&mut self, idx: usize) { self.focused = idx; } + /// The focused element, if the focused index is in range. pub fn focused(&self) -> Option<&T> { self.elements.get(self.focused) } + /// The index that is focused, in range or not. pub const fn focused_idx(&self) -> usize { self.focused } + /// The focused element, to change, if the focused index is in range. pub fn focused_mut(&mut self) -> Option<&mut T> { self.elements.get_mut(self.focused) } } +/// Gives a type that keeps its children in a [`Ring`] the accessors every such type has. +/// +/// `impl_ring_elements!(Workspace, Container)` reads the field `containers: Ring` and +/// gives `Workspace` the methods `containers()`, `containers_mut()`, `focused_container()`, +/// `focused_container_idx()` and `focused_container_mut()`. The field is named after the element +/// type in lower case with an `s` appended, and the methods after the field, so that "the focused +/// container" is spelled the same way on every type that has one. macro_rules! impl_ring_elements { ($name:ty, $element:ident) => { pastey::paste! { @@ -71,8 +109,7 @@ macro_rules! impl_ring_elements { } } } - }; - // This allows passing a different name to be used for the functions. For instance, the + }; // This allows passing a different name to be used for the functions. For instance, the // `floating_windows` ring calls this as: // ```rust // impl_ring_elements!(Workspace, Window, "floating_window"); @@ -105,3 +142,93 @@ macro_rules! impl_ring_elements { } }; } + +#[cfg(test)] +mod tests { + use super::*; + + #[derive(Debug, PartialEq)] + struct Book(&'static str); + + struct Shelf { + books: Ring, + } + + impl_ring_elements!(Shelf, Book); + + #[test] + fn impl_ring_elements_names_the_accessors_after_the_element() { + let mut shelf = Shelf { + books: Ring::default(), + }; + shelf.books_mut().extend([Book("a"), Book("b")]); + shelf.books.focus(1); + + assert_eq!(shelf.books().len(), 2); + assert_eq!(shelf.focused_book(), Some(&Book("b"))); + assert_eq!(shelf.focused_book_idx(), 1); + + if let Some(book) = shelf.focused_book_mut() { + *book = Book("c"); + } + + assert_eq!(shelf.books()[1], Book("c")); + } + + #[test] + fn an_empty_ring_focuses_nothing() { + let mut ring: Ring = Ring::default(); + + assert_eq!(ring.focused(), None); + assert_eq!(ring.focused_mut(), None); + assert_eq!(ring.focused_idx(), 0); + } + + #[test] + fn focus_selects_the_element_at_that_index() { + let mut ring = Ring::default(); + ring.elements_mut().extend([10, 20, 30]); + + ring.focus(2); + + assert_eq!(ring.focused(), Some(&30)); + assert_eq!(ring.focused_idx(), 2); + } + + #[test] + fn the_focused_element_can_be_changed_in_place() { + let mut ring = Ring::default(); + ring.elements_mut().extend([1, 2]); + ring.focus(1); + + if let Some(element) = ring.focused_mut() { + *element = 5; + } + + assert_eq!(ring.elements(), &[1, 5]); + } + + #[test] + fn a_focused_index_past_the_end_focuses_nothing() { + let mut ring = Ring::default(); + ring.elements_mut().push_back('a'); + + ring.focus(3); + + assert_eq!(ring.focused(), None); + assert_eq!(ring.focused_idx(), 3); + } + + #[test] + fn a_ring_round_trips_through_json() { + let mut ring = Ring::default(); + ring.elements_mut() + .extend(["a".to_string(), "b".to_string()]); + ring.focus(1); + + let json = serde_json::to_string(&ring).expect("serializes"); + let back: Ring = serde_json::from_str(&json).expect("deserializes"); + + assert_eq!(back, ring); + } +}