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    /// Whether the terminal's background is light, if it said.
29    pub light: Option<bool>,
30    /// The terminal's background colour, if it said.
31    pub background: Option<(u8, u8, u8)>,
32}
33
34impl Multiplexer {
35    /// Reads `$TMUX` and `$ZELLIJ` through `var`, so it can be tested without the
36    /// process environment.
37    pub fn detect(var: impl Fn(&str) -> Option<String>) -> Self {
38        if var("TMUX").is_some_and(|v| !v.is_empty()) {
39            Self::Tmux
40        } else if var("ZELLIJ").is_some() {
41            Self::Zellij
42        } else {
43            Self::None
44        }
45    }
46}
47
48impl std::str::FromStr for Tier {
49    type Err = String;
50
51    fn from_str(s: &str) -> Result<Self, String> {
52        match s {
53            "direct" => Ok(Self::PixelsDirect),
54            "placeholder" => Ok(Self::PixelsPlaceholder),
55            "cells" => Ok(Self::Cells),
56            _ => Err(format!(
57                "unknown tier {s}: use direct, placeholder or cells"
58            )),
59        }
60    }
61}
62
63/// Picks a tier. A user setting wins. Otherwise this is the design's table: tmux needs
64/// placeholders, and anything else that speaks Kitty graphics gets direct placement.
65pub fn select_tier(env: Env, forced: Option<Tier>) -> Tier {
66    if let Some(tier) = forced {
67        return tier;
68    }
69    match env.multiplexer {
70        Multiplexer::Tmux if env.tmux_passthrough && env.kitty_graphics => Tier::PixelsPlaceholder,
71        Multiplexer::Tmux => Tier::Cells,
72        Multiplexer::Zellij | Multiplexer::None if env.kitty_graphics => Tier::PixelsDirect,
73        Multiplexer::Zellij | Multiplexer::None => Tier::Cells,
74    }
75}
76
77#[cfg(test)]
78mod tests {
79    use super::*;
80
81    fn env(multiplexer: Multiplexer, kitty_graphics: bool, tmux_passthrough: bool) -> Env {
82        Env {
83            multiplexer,
84            kitty_graphics,
85            tmux_passthrough,
86            cell: None,
87            pixel_mouse: false,
88            light: None,
89            background: None,
90        }
91    }
92
93    #[test]
94    fn tier_selection_matches_design_table() {
95        use Multiplexer::*;
96        assert_eq!(
97            select_tier(env(None, true, false), Option::None),
98            Tier::PixelsDirect
99        );
100        assert_eq!(
101            select_tier(env(None, false, false), Option::None),
102            Tier::Cells
103        );
104        assert_eq!(
105            select_tier(env(Tmux, true, true), Option::None),
106            Tier::PixelsPlaceholder
107        );
108        assert_eq!(
109            select_tier(env(Tmux, true, false), Option::None),
110            Tier::Cells
111        );
112        assert_eq!(
113            select_tier(env(Tmux, false, true), Option::None),
114            Tier::Cells
115        );
116        assert_eq!(
117            select_tier(env(Zellij, true, false), Option::None),
118            Tier::PixelsDirect
119        );
120        assert_eq!(
121            select_tier(env(Zellij, false, false), Option::None),
122            Tier::Cells
123        );
124    }
125
126    #[test]
127    fn a_setting_forces_the_tier() {
128        let e = env(Multiplexer::None, true, false);
129        assert_eq!(select_tier(e, Some(Tier::Cells)), Tier::Cells);
130        assert_eq!("cells".parse(), Ok(Tier::Cells));
131        assert!("nope".parse::<Tier>().is_err());
132    }
133
134    #[test]
135    fn multiplexer_comes_from_the_environment() {
136        let tmux = |k: &str| (k == "TMUX").then(|| "/tmp/tmux-501/default,1,0".to_string());
137        assert_eq!(Multiplexer::detect(tmux), Multiplexer::Tmux);
138        let zellij = |k: &str| (k == "ZELLIJ").then(|| "0".to_string());
139        assert_eq!(Multiplexer::detect(zellij), Multiplexer::Zellij);
140        assert_eq!(Multiplexer::detect(|_| None), Multiplexer::None);
141    }
142}