justerm_core/
selection.rs

1//! Engine-owned selection state (see `docs/architecture.md` "Selection").
2//!
3//! Anchors are stored in **absolute buffer coordinates** — a line index into the
4//! concatenated `[scrollback ++ screen]` stream, counted from the oldest line.
5//! This coordinate is stable under a normal top-anchored scroll (the evicted
6//! line entering scrollback grows `scrollback.len()` by exactly the screen
7//! shift, so existing content keeps its absolute index); the only places it
8//! moves are cap eviction, in-screen region/RI scrolls, and reflow — each
9//! handled explicitly by `Term`. The cell-aware logic (text extraction, range
10//! clipping) lives in `term/selection.rs` — the `Term` half of this model.
11
12/// What a selection covers.
13///
14/// **Deliberately exhaustive ([#843](https://github.com/kihyun1998/justerm/issues/843)), on convergence rather than on traffic.**
15///
16/// An earlier draft of that sweep argued *"a consumer cannot fall back on a
17/// neighbour for one it does not know"* — which describes matching traffic this
18/// API does not have. Measured: this type appears in exactly one public
19/// signature, as a **parameter** to [`crate::Engine::selection_begin`], and
20/// nothing hands one outward. So the attribute would cost a consumer nothing,
21/// and that argument cannot be what keeps it off.
22///
23/// What keeps it off is that the set really is closed: **alacritty arrives at the
24/// same four modes independently**, under different names —
25/// `Simple` / `Semantic` / `Lines` / `Block`
26/// (`alacritty_terminal/src/selection.rs:93`), where its own doc glosses `simple`
27/// as tracking cells "without any expansion" ([`Char`](Self::Char)) and
28/// `semantic` as expanding "to the nearest semantic escape char"
29/// ([`Word`](Self::Word)). Two implementations landing on one partition of the
30/// space is the non-arbitrariness signal, and it is a stronger ground than the
31/// one it replaces.
32#[derive(Clone, Copy, PartialEq, Eq, Debug)]
33pub enum SelectionType {
34    /// Contiguous run, wrapping line to line.
35    Char,
36    /// Expanded to word boundaries.
37    Word,
38    /// Whole lines.
39    Line,
40    /// Rectangular column range on every line.
41    Block,
42}
43
44/// Which half of a cell an anchor sits on — the left or right edge. Lets a drag
45/// include or exclude the cell under the pointer (mouse precision).
46///
47/// **Deliberately exhaustive ([#843](https://github.com/kihyun1998/justerm/issues/843)).** Closed by geometry — there is no third side.
48/// Left exhaustive on purpose, not by omission.
49#[derive(Clone, Copy, PartialEq, Eq, Debug)]
50pub enum Side {
51    Left,
52    Right,
53}
54
55/// One highlighted run on a single **viewport** row: columns `left..=right`
56/// (both inclusive). `selection_range` returns one per visible row the selection
57/// touches — the renderer paints these. Off-screen rows are not emitted.
58///
59/// **No `#[non_exhaustive]` ([#844](https://github.com/kihyun1998/justerm/issues/844)).** 57 out-of-crate literal sites, the most of any type here —
60/// and `{row, left, right}` is closed geometry, so there is no growth cause to defend against.
61/// Declining costs nothing that can be measured.
62#[derive(Clone, Copy, PartialEq, Eq, Debug)]
63pub struct SelectionSpan {
64    pub row: usize,
65    pub left: usize,
66    pub right: usize,
67}
68
69/// A point in absolute buffer coordinates: `line` indexes `[scrollback ++ screen]`
70/// from the oldest line, `col` is the column.
71#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
72pub(crate) struct BufferPoint {
73    pub line: usize,
74    pub col: usize,
75}
76
77/// A selection endpoint: a buffer point plus which side of the cell it touches.
78#[derive(Clone, Copy, PartialEq, Eq, Debug)]
79pub(crate) struct Anchor {
80    pub point: BufferPoint,
81    pub side: Side,
82}
83
84/// The live selection: where the drag began (`anchor`) and where it currently
85/// reaches (`focus`). Either may be the earlier point — `ordered` sorts them.
86pub(crate) struct Selection {
87    pub ty: SelectionType,
88    pub anchor: Anchor,
89    pub focus: Anchor,
90}
91
92impl Selection {
93    /// The two anchors sorted so the first is the earlier buffer point.
94    pub fn ordered(&self) -> (Anchor, Anchor) {
95        if self.anchor.point <= self.focus.point {
96            (self.anchor, self.focus)
97        } else {
98            (self.focus, self.anchor)
99        }
100    }
101}
justerm_core/selection.rs

justerm_core/
selection.rs
