Skip to main content

cellix_term/
probe.rs

1/// How frames reach the terminal. See the tier table in `docs/DESIGN.md`.
2#[derive(Clone, Copy, Debug, PartialEq, Eq)]
3pub enum Tier {
4    PixelsDirect,
5    PixelsPlaceholder,
6    Cells,
7}
8
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum Multiplexer {
11    None,
12    Tmux,
13    Zellij,
14}
15
16/// What detection found about the environment.
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub struct Env {
19    pub multiplexer: Multiplexer,
20    /// The terminal answered a Kitty graphics query.
21    pub kitty_graphics: bool,
22    /// tmux reports `allow-passthrough on`.
23    pub tmux_passthrough: bool,
24    /// Cell size in pixels, when the terminal answered. `TIOCGWINSZ` is the fallback.
25    pub cell: Option<(usize, usize)>,
26    /// The terminal can report the mouse in pixels (mode 1016).
27    pub pixel_mouse: bool,
28    /// The terminal sends paste events (mode 5522), so a picture can be pasted. Only with no
29    /// multiplexer between, which wouldn't pass them on.
30    pub paste_events: bool,
31    /// Whether the terminal's background is light, if it said.
32    pub light: Option<bool>,
33    /// The terminal's background colour, if it said.
34    pub background: Option<(u8, u8, u8)>,
35}
36
37impl Multiplexer {
38    /// Reads `$TMUX` and `$ZELLIJ` through `var`, so it can be tested without the
39    /// process environment.
40    pub fn detect(var: impl Fn(&str) -> Option<String>) -> Self {
41        if var("TMUX").is_some_and(|v| !v.is_empty()) {
42            Self::Tmux
43        } else if var("ZELLIJ").is_some() {
44            Self::Zellij
45        } else {
46            Self::None
47        }
48    }
49}
50
51impl std::str::FromStr for Tier {
52    type Err = String;
53
54    fn from_str(s: &str) -> Result<Self, String> {
55        match s {
56            "direct" => Ok(Self::PixelsDirect),
57            "placeholder" => Ok(Self::PixelsPlaceholder),
58            "cells" => Ok(Self::Cells),
59            _ => Err(format!(
60                "unknown tier {s}: use direct, placeholder or cells"
61            )),
62        }
63    }
64}
65
66/// Picks a tier. A user setting wins. Otherwise this is the design's table: tmux needs
67/// placeholders, and anything else that speaks Kitty graphics gets direct placement.
68pub fn select_tier(env: Env, forced: Option<Tier>) -> Tier {
69    if let Some(tier) = forced {
70        return tier;
71    }
72    match env.multiplexer {
73        Multiplexer::Tmux if env.tmux_passthrough && env.kitty_graphics => Tier::PixelsPlaceholder,
74        Multiplexer::Tmux => Tier::Cells,
75        Multiplexer::Zellij | Multiplexer::None if env.kitty_graphics => Tier::PixelsDirect,
76        Multiplexer::Zellij | Multiplexer::None => Tier::Cells,
77    }
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83
84    fn env(multiplexer: Multiplexer, kitty_graphics: bool, tmux_passthrough: bool) -> Env {
85        Env {
86            multiplexer,
87            kitty_graphics,
88            tmux_passthrough,
89            cell: None,
90            pixel_mouse: false,
91            paste_events: false,
92            light: None,
93            background: None,
94        }
95    }
96
97    #[test]
98    fn tier_selection_matches_design_table() {
99        use Multiplexer::*;
100        assert_eq!(
101            select_tier(env(None, true, false), Option::None),
102            Tier::PixelsDirect
103        );
104        assert_eq!(
105            select_tier(env(None, false, false), Option::None),
106            Tier::Cells
107        );
108        assert_eq!(
109            select_tier(env(Tmux, true, true), Option::None),
110            Tier::PixelsPlaceholder
111        );
112        assert_eq!(
113            select_tier(env(Tmux, true, false), Option::None),
114            Tier::Cells
115        );
116        assert_eq!(
117            select_tier(env(Tmux, false, true), Option::None),
118            Tier::Cells
119        );
120        assert_eq!(
121            select_tier(env(Zellij, true, false), Option::None),
122            Tier::PixelsDirect
123        );
124        assert_eq!(
125            select_tier(env(Zellij, false, false), Option::None),
126            Tier::Cells
127        );
128    }
129
130    #[test]
131    fn a_setting_forces_the_tier() {
132        let e = env(Multiplexer::None, true, false);
133        assert_eq!(select_tier(e, Some(Tier::Cells)), Tier::Cells);
134        assert_eq!("cells".parse(), Ok(Tier::Cells));
135        assert!("nope".parse::<Tier>().is_err());
136    }
137
138    #[test]
139    fn multiplexer_comes_from_the_environment() {
140        let tmux = |k: &str| (k == "TMUX").then(|| "/tmp/tmux-501/default,1,0".to_string());
141        assert_eq!(Multiplexer::detect(tmux), Multiplexer::Tmux);
142        let zellij = |k: &str| (k == "ZELLIJ").then(|| "0".to_string());
143        assert_eq!(Multiplexer::detect(zellij), Multiplexer::Zellij);
144        assert_eq!(Multiplexer::detect(|_| None), Multiplexer::None);
145    }
146}