use std::io::{self, Write};
use std::sync::{Arc, Mutex, Once, OnceLock, Weak};
use std::time::{Duration, Instant};
use crossterm::cursor::{Hide, Show};
use crossterm::event::{
DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
EnableFocusChange, EnableMouseCapture, KeyboardEnhancementFlags, PopKeyboardEnhancementFlags,
PushKeyboardEnhancementFlags,
};
use crossterm::terminal::{
BeginSynchronizedUpdate, EndSynchronizedUpdate, EnterAlternateScreen, LeaveAlternateScreen,
};
use crossterm::{ExecutableCommand as _, QueueableCommand as _};
use super::hyperlink::write_close;
const MAX_TERMINAL_TITLE_BYTES: usize = 64;
const SAVE_WINDOW_TITLE: &[u8] = b"\x1b[22;2t";
const SET_WINDOW_TITLE_PREFIX: &[u8] = b"\x1b]2;";
const SET_WINDOW_TITLE_SUFFIX: &[u8] = b"\x07";
const RESTORE_WINDOW_TITLE: &[u8] = b"\x1b[23;2t";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ColorCapability {
None,
Ansi16,
Ansi256,
TrueColor,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TerminalCapabilities {
color: ColorCapability,
reduced_motion: bool,
interactive: bool,
hyperlinks: bool,
}
impl TerminalCapabilities {
#[must_use]
pub fn detect(reduced_motion: bool) -> Self {
let terminal = std::env::var("TERM").ok();
let color_terminal = std::env::var("COLORTERM").ok();
Self::from_environment(
terminal.as_deref(),
color_terminal.as_deref(),
std::env::var_os("NO_COLOR").is_some(),
reduced_motion,
)
}
#[must_use]
pub fn from_environment(
terminal: Option<&str>,
color_terminal: Option<&str>,
no_color: bool,
reduced_motion: bool,
) -> Self {
let dumb = terminal.is_some_and(|value| value.eq_ignore_ascii_case("dumb"));
let color = if no_color || dumb {
ColorCapability::None
} else if color_terminal.is_some_and(|value| {
let value = value.to_ascii_lowercase();
value.contains("truecolor") || value.contains("24bit")
}) {
ColorCapability::TrueColor
} else if terminal.is_some_and(|value| value.contains("256color")) {
ColorCapability::Ansi256
} else {
ColorCapability::Ansi16
};
let hyperlinks = terminal.is_some_and(supports_osc8_terminal);
Self {
color,
reduced_motion: reduced_motion || dumb,
interactive: !dumb,
hyperlinks,
}
}
#[must_use]
pub const fn color(self) -> ColorCapability {
self.color
}
#[must_use]
pub const fn reduced_motion(self) -> bool {
self.reduced_motion
}
#[must_use]
pub const fn supports_synchronized_output(self) -> bool {
self.interactive
}
#[must_use]
pub const fn supports_focus_events(self) -> bool {
self.interactive
}
#[must_use]
pub const fn supports_title(self) -> bool {
self.interactive
}
#[must_use]
pub const fn supports_hyperlinks(self) -> bool {
self.hyperlinks
}
}
fn supports_osc8_terminal(terminal: &str) -> bool {
let terminal = terminal.to_ascii_lowercase();
if terminal == "dumb" || terminal.starts_with("screen") || terminal.starts_with("tmux") {
return false;
}
[
"xterm",
"rxvt",
"kitty",
"wezterm",
"alacritty",
"foot",
"ghostty",
]
.iter()
.any(|family| terminal.contains(family))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ViewportMode {
Fullscreen,
Inline,
}
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct TerminalTitle {
bytes: [u8; MAX_TERMINAL_TITLE_BYTES],
len: u8,
}
impl TerminalTitle {
#[must_use]
pub fn new(value: &str) -> Self {
let mut bytes = [0; MAX_TERMINAL_TITLE_BYTES];
let mut len = 0usize;
let mut pending_space = false;
for character in value.chars() {
if character.is_control() {
continue;
}
if character.is_whitespace() {
pending_space = len > 0;
continue;
}
if pending_space && len < MAX_TERMINAL_TITLE_BYTES {
bytes[len] = b' ';
len += 1;
}
pending_space = false;
let mut encoded = [0; 4];
let encoded = character.encode_utf8(&mut encoded).as_bytes();
if len.saturating_add(encoded.len()) > MAX_TERMINAL_TITLE_BYTES {
break;
}
bytes[len..len + encoded.len()].copy_from_slice(encoded);
len += encoded.len();
}
if len > 0 && bytes[len - 1] == b' ' {
len -= 1;
}
if len == 0 {
bytes[..3].copy_from_slice(b"Tea");
len = 3;
}
Self {
bytes,
len: u8::try_from(len).unwrap_or(64),
}
}
#[must_use]
pub fn as_str(&self) -> &str {
self.bytes
.get(..usize::from(self.len))
.and_then(|bytes| std::str::from_utf8(bytes).ok())
.unwrap_or("Tea")
}
}
impl Default for TerminalTitle {
fn default() -> Self {
Self::new("Tea")
}
}
impl std::fmt::Debug for TerminalTitle {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_tuple("TerminalTitle")
.field(&self.as_str())
.finish()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TerminalMode {
Title(TerminalTitle),
Raw,
AlternateScreen,
BracketedPaste,
FocusEvents,
MouseCapture,
KeyboardEnhancement,
CursorHidden,
SynchronizedOutput,
HyperlinkOutput,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[allow(clippy::struct_excessive_bools)] pub struct TerminalOptions {
pub title: Option<TerminalTitle>,
pub viewport: ViewportMode,
pub synchronized_output: bool,
pub focus_events: bool,
pub mouse_capture: bool,
pub keyboard_enhancement: bool,
pub cursor_visible: bool,
pub hyperlinks: bool,
}
impl Default for TerminalOptions {
fn default() -> Self {
Self {
title: None,
viewport: ViewportMode::Fullscreen,
synchronized_output: true,
focus_events: true,
mouse_capture: false,
keyboard_enhancement: false,
cursor_visible: false,
hyperlinks: false,
}
}
}
#[allow(clippy::missing_errors_doc)] pub trait TerminalDriver: Send {
fn enable(&mut self, mode: TerminalMode) -> io::Result<()>;
fn disable(&mut self, mode: TerminalMode) -> io::Result<()>;
fn drain(&mut self, deadline: Instant) -> io::Result<()>;
}
#[derive(Debug)]
pub struct CrosstermDriver<W> {
writer: W,
}
impl<W> CrosstermDriver<W> {
#[must_use]
pub const fn new(writer: W) -> Self {
Self { writer }
}
}
impl<W: Write + Send> TerminalDriver for CrosstermDriver<W> {
fn enable(&mut self, mode: TerminalMode) -> io::Result<()> {
match mode {
TerminalMode::Title(title) => self.enable_title(title),
TerminalMode::Raw => crossterm::terminal::enable_raw_mode(),
TerminalMode::AlternateScreen => self.writer.execute(EnterAlternateScreen).map(drop),
TerminalMode::BracketedPaste => self.writer.execute(EnableBracketedPaste).map(drop),
TerminalMode::FocusEvents => self.writer.execute(EnableFocusChange).map(drop),
TerminalMode::MouseCapture => self.writer.execute(EnableMouseCapture).map(drop),
TerminalMode::KeyboardEnhancement => self
.writer
.execute(PushKeyboardEnhancementFlags(
KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES,
))
.map(drop),
TerminalMode::CursorHidden => self.writer.execute(Hide).map(drop),
TerminalMode::SynchronizedOutput => {
self.writer.queue(BeginSynchronizedUpdate).map(drop)
}
TerminalMode::HyperlinkOutput => Ok(()),
}
}
fn disable(&mut self, mode: TerminalMode) -> io::Result<()> {
match mode {
TerminalMode::Title(_) => self.restore_title(),
TerminalMode::Raw => crossterm::terminal::disable_raw_mode(),
TerminalMode::AlternateScreen => self.writer.execute(LeaveAlternateScreen).map(drop),
TerminalMode::BracketedPaste => self.writer.execute(DisableBracketedPaste).map(drop),
TerminalMode::FocusEvents => self.writer.execute(DisableFocusChange).map(drop),
TerminalMode::MouseCapture => self.writer.execute(DisableMouseCapture).map(drop),
TerminalMode::KeyboardEnhancement => {
self.writer.execute(PopKeyboardEnhancementFlags).map(drop)
}
TerminalMode::CursorHidden => self.writer.execute(Show).map(drop),
TerminalMode::SynchronizedOutput => {
self.writer.execute(EndSynchronizedUpdate).map(drop)
}
TerminalMode::HyperlinkOutput => {
write_close(&mut self.writer)?;
self.writer.flush()
}
}
}
fn drain(&mut self, deadline: Instant) -> io::Result<()> {
if Instant::now() >= deadline {
return Err(io::Error::new(
io::ErrorKind::TimedOut,
"terminal frame drain deadline expired",
));
}
self.writer.flush()?;
if Instant::now() > deadline {
return Err(io::Error::new(
io::ErrorKind::TimedOut,
"terminal frame drain exceeded its deadline",
));
}
Ok(())
}
}
impl<W: Write> CrosstermDriver<W> {
fn enable_title(&mut self, title: TerminalTitle) -> io::Result<()> {
let result = (|| {
self.writer.write_all(SAVE_WINDOW_TITLE)?;
self.writer.write_all(SET_WINDOW_TITLE_PREFIX)?;
self.writer.write_all(title.as_str().as_bytes())?;
self.writer.write_all(SET_WINDOW_TITLE_SUFFIX)?;
self.writer.flush()
})();
if let Err(error) = result {
let _ = self.restore_title();
return Err(error);
}
Ok(())
}
fn restore_title(&mut self) -> io::Result<()> {
self.writer.write_all(RESTORE_WINDOW_TITLE)?;
self.writer.flush()
}
}
struct GuardState {
driver: Box<dyn TerminalDriver>,
enabled: Vec<TerminalMode>,
options: TerminalOptions,
input_parked: bool,
}
impl std::fmt::Debug for GuardState {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("GuardState")
.field("enabled", &self.enabled)
.field("options", &self.options)
.field("input_parked", &self.input_parked)
.finish_non_exhaustive()
}
}
impl GuardState {
fn enter(&mut self) -> io::Result<()> {
if let Some(title) = self.options.title {
self.enable(TerminalMode::Title(title))?;
}
self.enable(TerminalMode::Raw)?;
if self.options.viewport == ViewportMode::Fullscreen {
self.enable(TerminalMode::AlternateScreen)?;
}
self.enable(TerminalMode::BracketedPaste)?;
if self.options.focus_events {
self.enable(TerminalMode::FocusEvents)?;
}
if self.options.mouse_capture {
self.enable(TerminalMode::MouseCapture)?;
}
if self.options.keyboard_enhancement {
let _ = self.enable(TerminalMode::KeyboardEnhancement);
}
if !self.options.cursor_visible {
self.enable(TerminalMode::CursorHidden)?;
}
if self.options.hyperlinks {
self.enable(TerminalMode::HyperlinkOutput)?;
}
Ok(())
}
fn enable(&mut self, mode: TerminalMode) -> io::Result<()> {
if self.enabled.contains(&mode) {
return Ok(());
}
self.driver.enable(mode)?;
self.enabled.push(mode);
Ok(())
}
fn disable(&mut self, mode: TerminalMode) -> io::Result<()> {
if let Some(index) = self.enabled.iter().position(|enabled| *enabled == mode) {
self.driver.disable(mode)?;
self.enabled.remove(index);
}
Ok(())
}
fn restore(&mut self) -> io::Result<()> {
let mut first_error = None;
while let Some(mode) = self.enabled.pop() {
if let Err(error) = self.driver.disable(mode) {
first_error.get_or_insert(error);
}
}
first_error.map_or(Ok(()), Err)
}
}
static PANIC_HOOK_ONCE: Once = Once::new();
static ACTIVE_TERMINAL: OnceLock<Mutex<Option<Weak<Mutex<GuardState>>>>> = OnceLock::new();
fn install_panic_hook() {
PANIC_HOOK_ONCE.call_once(|| {
let previous = std::panic::take_hook();
std::panic::set_hook(Box::new(move |information| {
let active = ACTIVE_TERMINAL.get().and_then(|slot| {
slot.try_lock()
.map_or_else(
|error| match error {
std::sync::TryLockError::Poisoned(error) => Some(error.into_inner()),
std::sync::TryLockError::WouldBlock => None,
},
Some,
)
.and_then(|slot| slot.as_ref().and_then(Weak::upgrade))
});
if let Some(active) = active {
match active.try_lock() {
Ok(mut state) => {
let _ = state.restore();
}
Err(std::sync::TryLockError::Poisoned(error)) => {
let _ = error.into_inner().restore();
}
Err(std::sync::TryLockError::WouldBlock) => {}
}
}
previous(information);
}));
});
}
#[derive(Debug)]
pub struct TerminalGuard {
state: Arc<Mutex<GuardState>>,
}
#[allow(clippy::missing_errors_doc)] impl TerminalGuard {
pub fn enter(
driver: impl TerminalDriver + 'static,
options: TerminalOptions,
) -> io::Result<Self> {
install_panic_hook();
let state = Arc::new(Mutex::new(GuardState {
driver: Box::new(driver),
enabled: Vec::new(),
options,
input_parked: false,
}));
let guard = Self { state };
let slot = ACTIVE_TERMINAL.get_or_init(|| Mutex::new(None));
{
let mut active = slot
.lock()
.map_err(|_| io::Error::other("active terminal registry is poisoned"))?;
if active.as_ref().and_then(Weak::upgrade).is_some() {
return Err(io::Error::new(
io::ErrorKind::AlreadyExists,
"another terminal guard is already active",
));
}
*active = Some(Arc::downgrade(&guard.state));
}
{
let mut locked = guard
.state
.lock()
.map_err(|_| io::Error::other("terminal mode ledger is poisoned"))?;
if let Err(error) = locked.enter() {
let _ = locked.restore();
return Err(error);
}
}
Ok(guard)
}
pub fn begin_frame(&self) -> io::Result<()> {
let mut state = self.lock()?;
if state.options.synchronized_output {
state.enable(TerminalMode::SynchronizedOutput)?;
}
Ok(())
}
pub fn end_frame(&self, timeout: Duration) -> io::Result<()> {
let mut state = self.lock()?;
let end_result = state.disable(TerminalMode::SynchronizedOutput);
let drain_result = state.driver.drain(Instant::now() + timeout);
end_result.and(drain_result)
}
pub fn suspend(&self, timeout: Duration) -> io::Result<()> {
let mut state = self.lock()?;
state.input_parked = true;
let sync_result = state.disable(TerminalMode::SynchronizedOutput);
let drain_result = state.driver.drain(Instant::now() + timeout);
let restore_result = state.restore();
sync_result.and(drain_result).and(restore_result)
}
pub fn resume(&self) -> io::Result<()> {
let mut state = self.lock()?;
if let Err(error) = state.enter() {
let _ = state.restore();
return Err(error);
}
state.input_parked = false;
Ok(())
}
pub fn handoff<T>(
&self,
timeout: Duration,
child: impl FnOnce() -> io::Result<T>,
) -> io::Result<T> {
self.suspend(timeout)?;
let child_result = child();
let resume_result = self.resume();
match (child_result, resume_result) {
(Ok(value), Ok(())) => Ok(value),
(Err(error), _) | (Ok(_), Err(error)) => Err(error),
}
}
pub fn enabled_modes(&self) -> io::Result<Vec<TerminalMode>> {
Ok(self.lock()?.enabled.clone())
}
pub fn input_is_parked(&self) -> io::Result<bool> {
Ok(self.lock()?.input_parked)
}
fn lock(&self) -> io::Result<std::sync::MutexGuard<'_, GuardState>> {
self.state
.lock()
.map_err(|_| io::Error::other("terminal mode ledger is poisoned"))
}
}
impl Drop for TerminalGuard {
fn drop(&mut self) {
match self.state.lock() {
Ok(mut state) => {
let _ = state.restore();
}
Err(error) => {
let _ = error.into_inner().restore();
}
}
if let Some(slot) = ACTIVE_TERMINAL.get()
&& let Ok(mut active) = slot.lock()
&& active
.as_ref()
.and_then(Weak::upgrade)
.is_some_and(|value| Arc::ptr_eq(&value, &self.state))
{
*active = None;
}
}
}
#[cfg(test)]
mod tests {
use super::{
ColorCapability, CrosstermDriver, TerminalCapabilities, TerminalDriver, TerminalMode,
TerminalTitle,
};
#[test]
fn environment_capabilities_are_conservative_for_dumb_and_no_color_terminals() {
let dumb = TerminalCapabilities::from_environment(Some("dumb"), None, false, false);
assert_eq!(dumb.color(), ColorCapability::None);
assert!(dumb.reduced_motion());
assert!(!dumb.supports_synchronized_output());
assert!(!dumb.supports_focus_events());
assert!(!dumb.supports_title());
assert!(!dumb.supports_hyperlinks());
let no_color =
TerminalCapabilities::from_environment(Some("xterm-256color"), None, true, false);
assert_eq!(no_color.color(), ColorCapability::None);
assert!(no_color.supports_synchronized_output());
assert!(no_color.supports_title());
assert!(no_color.supports_hyperlinks());
for terminal in [None, Some("screen-256color"), Some("tmux-256color")] {
assert!(
!TerminalCapabilities::from_environment(terminal, None, false, false)
.supports_hyperlinks()
);
}
let true_color = TerminalCapabilities::from_environment(
Some("xterm-256color"),
Some("truecolor"),
false,
true,
);
assert_eq!(true_color.color(), ColorCapability::TrueColor);
assert!(true_color.reduced_motion());
}
#[test]
fn crossterm_driver_saves_sets_and_restores_the_exact_window_title() {
let title = TerminalTitle::default();
let mode = TerminalMode::Title(title);
let mut driver = CrosstermDriver::new(Vec::new());
driver.enable(mode).unwrap();
driver.disable(mode).unwrap();
assert_eq!(driver.writer, b"\x1b[22;2t\x1b]2;Tea\x07\x1b[23;2t");
}
#[test]
fn crossterm_driver_closes_guarded_hyperlink_output() {
let mut driver = CrosstermDriver::new(Vec::new());
driver.enable(TerminalMode::HyperlinkOutput).unwrap();
driver.disable(TerminalMode::HyperlinkOutput).unwrap();
assert_eq!(driver.writer, b"\x1b]8;;\x1b\\");
}
}