clearscreen 5.0.0

//! Cross-platform terminal screen clearing.
//!
//! This library provides a set of ways to clear a screen, plus a “best effort” convenience function
//! to do the right thing most of the time.
//!
//! Unlike many cross-platform libraries, this one exposes every available choice all the time, and
//! only the convenience function varies based on compilation target or environmental factors.
//!
//! 90% of the time, you’ll want to use the convenience short-hand:
//!
//! ```no_run
//! clearscreen::clear().expect("failed to clear screen");
//! ```
//!
//! For anything else, refer to the [`ClearScreen`] enum.
//!
//! On Windows, the sequence-based methods enable VT processing on the console for the duration of
//! the operation (restoring the previous console mode afterwards), with no version detection or
//! manifest required; if the console host does not support VT escapes, they fall back to the
//! legacy Windows Console clear.

#![doc(html_favicon_url = "https://watchexec.github.io/logo:clearscreen.svg")]
#![doc(html_logo_url = "https://watchexec.github.io/logo:clearscreen.svg")]
#![warn(missing_docs)]

use std::{
	borrow::Cow,
	env,
	io::{self, Write},
	process::{Command, ExitStatus},
};

use terminfo::{
	capability::{self},
	expand::{Context, Expand, Parameter},
	Capability, Database, Value,
};
use thiserror::Error;
use which::which;

/// Ways to clear the screen.
///
/// There isn’t a single way to clear the (terminal/console) screen. Not only are there several
/// techniques to achieve the outcome, there are differences in the way terminal emulators intepret
/// some of these techniques, as well as platform particularities.
///
/// In addition, there are other conditions a screen can be in that might be beneficial to reset,
/// such as when a TUI application crashes and leaves the terminal in a less than useful state.
///
/// Finally, a terminal may have scrollback, and this can be kept as-is or cleared as well.
///
/// Your application may need one particular clearing method, or it might offer several options to
/// the user, such as “hard” and “soft” clearing. This library makes no assumption and no judgement
/// on what is considered hard, soft, or something else: that is your responsibility to determine in
/// your context.
///
/// For most cases, you should use [`ClearScreen::default()`] to select the most appropriate method.
///
/// In any event, once a way is selected, call [`clear()`][ClearScreen::clear()] to apply it.
///
/// # Example
///
/// ```no_run
/// # use clearscreen::ClearScreen;
/// ClearScreen::default().clear().expect("failed to clear the screen");
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ClearScreen {
	/// Does both [`TerminfoScreen`][ClearScreen::TerminfoScreen] and
	/// [`TerminfoScrollback`][ClearScreen::TerminfoScrollback], in this order, but skips the
	/// scrollback reset if the capability isn’t available.
	///
	/// This is essentially what the [`clear`] command on unix does.
	/// [`clear`]: https://invisible-island.net/ncurses/man/clear.1.html
	Terminfo,

	/// Looks up the `clear` capability in the terminfo (from the TERM env var), and applies it.
	///
	/// A non-hashed terminfo database is required (this is a [terminfo crate] limitation), such as
	/// the one provided with ncurses.
	///
	/// [terminfo crate]: https://lib.rs/crates/terminfo
	TerminfoScreen,

	/// Looks up the `E3` (Erase Scrollback) capability in the terminfo (from the TERM env var), and applies it.
	///
	/// The same terminfo limitation applies as for [`TerminfoScreen`][ClearScreen::TerminfoScreen].
	TerminfoScrollback,

	/// Performs a terminfo-driven terminal reset sequence.
	///
	/// This prints whichever are available of the **rs1**, **rs2**, **rs3**, and **rf** sequences.
	/// If none of these are available, it prints whichever are available of the **is1**, **is2**,
	/// **is3**, and **if** sequences. If none are available, an error is returned.
	///
	/// This generally issues at least an `ESC c` sequence, which resets all terminal state to
	/// default values, and then may issue more sequences to reset other things or enforce a
	/// particular kind of state. See [`XtermReset`][ClearScreen::XtermReset] for a description of
	/// what XTerm does, as an example.
	///
	/// Note that this is _not_ analogous to what `tput reset` does: to emulate that, issuing first
	/// one of VtCooked/VtWellDone/WindowsCooked followed by this variant will come close.
	///
	/// The same terminfo limitation applies as for [`TerminfoScreen`][ClearScreen::TerminfoScreen].
	TerminfoReset,

	/// Prints clear screen and scrollback sequence as if TERM=xterm.
	///
	/// This does not look up the correct sequence in the terminfo database, but rather prints:
	///
	/// - `CSI H` (Cursor Position 0,0), which sets the cursor position to 0,0.
	/// - `CSI 2J` (Erase Screen), which erases the whole screen.
	/// - `CSI 3J` (Erase Scrollback), which erases the scrollback (xterm extension).
	XtermClear,

	/// Prints the terminal reset sequence as if TERM=xterm.
	///
	/// This does not look up the correct sequence in the terminfo database, but rather prints:
	///
	/// - `ESC c` (Reset to Initial State), which nominally resets all terminal state to initial
	///   values, but see the documentation for [`VtRis`][ClearScreen::VtRis].
	/// - `CSI !p` (Soft Terminal Reset), which nominally does the same thing as RIS, but without
	///   disconnecting the terminal data lines… which matters when you’re living in 1970.
	/// - `CSI ?3l` (Reset to 80 Columns), which resets the terminal width to 80 columns, or more
	///   accurately, resets the option that selects 132 column mode, to its default value of no.
	///   I don’t know, man.
	/// - `CSI ?4l` (Reset to Jump Scrolling), which sets the scrolling mode to jump. This is naught
	///   to do with what we think of as “scrolling,” but rather it’s about the speed at which the
	///   terminal will add lines to the screen. Jump mode means “give it to me as fast as it comes”
	///   and Smooth mode means to do some buffering and output lines “at a moderate, smooth rate.”
	/// - `CSI 4l` (Reset to Replace Mode), which sets the cursor writing mode to Replace, i.e.
	///   overwriting characters at cursor position, instead of Insert, which pushes characters
	///   under the cursor to the right.
	/// - `ESC >` (Set Key Pad to Normal), which sets the keyboard’s numeric keypad to send “what’s
	///   printed on the keys” i.e. numbers and the arithmetic symbols.
	/// - `CSI ?69l` (Reset Left and Right Margins to the page), which sets the horizontal margins
	///   to coincide with the page’s margins: nowadays, no margins.
	XtermReset,

	/// Calls the command `tput clear`.
	///
	/// That command most likely does what [`Terminfo`][ClearScreen::Terminfo] does internally, but
	/// may work better in some cases, such as when the terminfo database on the system is hashed or
	/// in a non-standard location that the terminfo crate does not find.
	///
	/// However, it relies on the `tput` command being available, and on being able to run commands.
	TputClear,

	/// Calls the command `tput reset`.
	///
	/// See the documentation above on [`TputClear`][ClearScreen::TputClear] for more details, save
	/// that the equivalent is [`TerminfoReset`][ClearScreen::TerminfoReset].
	TputReset,

	/// Calls the command `cls`.
	///
	/// This is the Windows command to clear the screen. It has the same caveats as
	/// [`TputClear`][ClearScreen::TputClear] does, but its internal mechanism is not known. Prefer
	/// [`WindowsConsoleClear`][ClearScreen::WindowsConsoleClear] instead to avoid relying on an
	/// external command.
	///
	/// This will always attempt to run the command, regardless of compile target, which may have
	/// unintended effects if the `cls` executable does something different on the platform.
	Cls,

	/// Uses Windows Console function to scroll the screen buffer and fill it with white space.
	///
	/// - Scrolls up one screenful
	/// - Fills the buffer with whitespace and attributes set to default.
	/// - Flushes the input buffer
	/// - Sets the cursor position to 0,0
	///
	/// This is described here: https://docs.microsoft.com/en-us/windows/console/clearing-the-screen#example-2
	/// as the equivalent to CMD.EXE's `cls` command.
	///
	/// Does nothing on non-Windows targets.
	WindowsConsoleClear,

	/// Uses Windows Console function to blank the screen state.
	///
	/// - Fills the screen buffer with ` ` (space) characters
	/// - Resets cell attributes over the entire buffer
	/// - Flushes the input buffer
	/// - Sets the cursor position to 0,0
	///
	/// This is described here: https://docs.microsoft.com/en-us/windows/console/clearing-the-screen#example-3
	///
	/// Does nothing on non-Windows targets.
	#[cfg(feature = "windows-console")]
	WindowsConsoleBlank,

	/// Uses Windows Console function to disable raw mode.
	///
	/// Does nothing on non-Windows targets.
	WindowsCooked,

	/// Prints the RIS VT100 escape code: Reset to Initial State.
	///
	/// This is the `ESC c` or `1b 63` escape, which by spec is defined to reset the terminal state
	/// to all initial values, which may be a range of things, for example as described in the VT510
	/// manual: https://vt100.net/docs/vt510-rm/RIS
	///
	/// However, the exact behaviour is highly dependent on the terminal emulator, and some modern
	/// terminal emulators do not always clear scrollback, for example Tmux and GNOME VTE.
	VtRis,

	/// Prints the CSI sequence to leave the Alternate Screen mode.
	///
	/// If the screen is in alternate screen mode, like how vim or a pager or another such rich TUI
	/// application would do, this sequence will clear the alternate screen buffer, then revert the
	/// terminal to normal mode, and restore the position of the cursor to what it was before
	/// Alternate Screen mode was entered, assuming the proper sequence was used.
	///
	/// It will not clear the normal mode buffer.
	///
	/// This is useful when recovering from a TUI application which crashed without resetting state.
	VtLeaveAlt,

	/// Sets the terminal to cooked mode.
	///
	/// This attempts to switch the terminal to “cooked” mode, which can be thought of as the
	/// opposite of “raw” mode, where the terminal does not respond to line discipline (which makes
	/// carriage return, line feed, and general typing display out to screen, and translates Ctrl-C
	/// to sending the SIGINT signal, etc) but instead passes all input to the controlling program
	/// and only displays what it outputs explicitly.
	///
	/// There’s also an intermediate “cbreak” or “rare” mode which behaves like “cooked” but sends
	/// each character one at a time immediately rather buffering and sending lines.
	///
	/// TUI applications such as editors and pagers often set raw mode to gain precise control of
	/// the terminal state. If such a program crashes, it may not reset the terminal mode back to
	/// the mode it found it in, which can leave the terminal behaving oddly or rendering it
	/// completely unusable.
	///
	/// In truth, these terminal modes are a set of configuration bits that are given to the
	/// `termios(3)` libc API, and control a variety of terminal modes. “Cooked” mode sets:
	///
	/// - Input BRKINT set: on BREAK, flush i/o queues and send a SIGINT to any running process.
	/// - Input ICRNL set: translate Carriage Returns to New Lines on input.
	/// - Input IGNPAR set: ignore framing and parity errors.
	/// - Input IXON set: enable XON/XOFF flow control on output.
	/// - Output OPOST set: enable output processing.
	/// - Control CSIZE and the baud rate: left as they were found (see below).
	/// - Local ICANON set: enable canonical mode (see below).
	/// - Local ISIG set: when Ctrl-C, Ctrl-Q, etc are received, send the appropriate signal.
	/// - Local IEXTEN set: enable implementation-defined input processing.
	/// - Local ECHO set: echo input characters back to the terminal.
	/// - Local ECHOE set: ERASE (backspace) visibly erases the previous character.
	/// - Local ECHOK set: KILL visibly erases the current line.
	/// - Local ECHOCTL set: render control characters as `^X` (not on Redox).
	/// - Local ECHOKE set: KILL erases the line as if by a sequence of ERASEs (not on Redox).
	///
	/// Canonical mode is really the core of “cooked” mode and enables:
	///
	/// - line buffering, so input is only sent to the underlying program when a line delimiter
	///   character is entered (usually a newline);
	/// - line editing, so ERASE (backspace) and KILL (remove entire line) control characters edit
	///   the line before it is sent to the program;
	/// - a maximum line length of 4096 characters (bytes).
	///
	/// When canonical mode is unset (when the bit is cleared), all input processing is disabled.
	///
	/// The character size and the line speed are the one part of the configuration that is
	/// preserved rather than written: they describe the line itself, not how the terminal
	/// behaves on it, and clearing the screen has no way to know what to put back. On Linux
	/// the baud rate is stored in the control flags, so it is carried across along with
	/// CSIZE; on other platforms it has its own fields, which are never written here.
	///
	/// Due to how the underlying [`tcsetattr`] function is defined in POSIX, this may complete
	/// without error if _any part_ of the configuration is applied, not just when all of it is set.
	///
	/// Note that you generally want [`VtWellDone`][ClearScreen::VtWellDone] instead.
	///
	/// Does nothing on non-Unix targets.
	///
	/// [`tcsetattr`]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/tcsetattr.html
	VtCooked,

	/// Sets the terminal to “well done” mode.
	///
	/// This is similar to [`VtCooked`][ClearScreen::VtCooked], but with a different, broader, mode
	/// configuration which approximates a terminal’s initial state, such as is expected by a shell,
	/// and clears many bits that should probably never be set (like the translation/mapping modes).
	///
	/// “Well done” mode is an invention of this library, inspired by several other sources such as
	/// Golang’s goterm, the termios(3) and tput(1) manual pages, but not identical to any.
	///
	/// Notably most implementations read the terminal configuration bits and only modify that set,
	/// whereas this library authoritatively writes the entire configuration from scratch.
	///
	/// It is a strict superset of [`VtCooked`][ClearScreen::VtCooked].
	///
	/// - Input BRKINT set: on BREAK, flush i/o queues and send a SIGINT to any running process.
	/// - Input ICRNL set: translate Carriage Return to New Line on input.
	/// - Input IUTF8 set: input is UTF-8 (Linux only, since 2.6.4).
	/// - Input IGNPAR set: ignore framing and parity errors.
	/// - Input IMAXBEL set: ring terminal bell when input queue is full (not implemented in Linux).
	/// - Input IXON set: enable XON/XOFF flow control on output.
	/// - Output ONLCR set: do not translate Carriage Return to CR NL.
	/// - Output OPOST set: enable output processing.
	/// - Control CREAD set: enable receiver.
	/// - Control CSIZE and the baud rate: left as they were found.
	/// - Local ICANON set: enable canonical mode (see [`VtCooked`][ClearScreen::VtCooked]).
	/// - Local ISIG set: when Ctrl-C, Ctrl-Q, etc are received, send the appropriate signal.
	/// - Local IEXTEN set: enable implementation-defined input processing.
	/// - Local ECHO, ECHOE and ECHOK set, plus ECHOCTL and ECHOKE where they exist: echo
	///   input back to the terminal (see [`VtCooked`][ClearScreen::VtCooked]).
	///
	/// ISTRIP is deliberately *not* set. It clears the eighth bit of every input byte, which
	/// no multi-byte UTF-8 sequence survives, and it contradicts IUTF8 above.
	///
	/// Does nothing on non-Unix targets.
	VtWellDone,
}

impl Default for ClearScreen {
	/// Detects the environment and makes its best guess as how to clear the screen.
	///
	/// This function’s behaviour (but not its type signature) may change without notice, as better
	/// techniques appear. However, it will always strive to provide the best method. It will also
	/// never have side-effects, and finding any such behaviour should be reported as a bug.
	///
	/// If you wish to make your own, the [`is_microsoft_terminal()`] function may be useful.
	///
	/// The [`ClearScreen`] variant selected is always in the “clear” behaviour side of things. If
	/// you wish to only clear the screen and not the scrollback, or to perform a terminal reset, or
	/// apply the other available clearing strategies, you’ll need to select what’s best yourself.
	///
	/// See the [TERMINALS.md file in the repo][TERMINALS.md] for research on many terminals as well
	/// as the current result of this function for each terminal.
	///
	/// [TERMINALS.md]: https://github.com/watchexec/clearscreen/blob/main/TERMINALS.md
	fn default() -> Self {
		use env::var;
		use std::ffi::OsStr;

		fn varfull(key: impl AsRef<OsStr>) -> bool {
			var(key).map_or(false, |s| !s.is_empty())
		}

		let term = var("TERM").ok();
		let term = term.as_ref();

		if cfg!(windows) {
			return if is_microsoft_terminal() {
				Self::XtermClear
			} else if term.is_some() && varfull("TERMINFO") {
				Self::Terminfo
			} else if term.is_some() && which("tput").is_ok() {
				Self::TputClear
			} else {
				Self::Cls
			};
		}

		if let Some(term) = term {
			// These VTE-based terminals support CSI 3J but their own terminfos don’t have E3
			if (term.starts_with("gnome")
				&& varfull("GNOME_TERMINAL_SCREEN")
				&& varfull("GNOME_TERMINAL_SERVICE"))
				|| term == "xfce"
				|| term.contains("termite")
			{
				return Self::XtermClear;
			}

			// - SyncTERM does support the XtermClear sequence but does not clear the scrollback,
			// and does not have a terminfo, so VtRis is the only option.
			// - rxvt, when using its own terminfos, erases the screen instead of clearing and
			// doesn’t clear scrollback. It supports and behave properly for the entire XtermClear
			// sequence, but it also does the right thing with VtRis, and that seems more reliable.
			// - Other variants of (u)rxvt do the same.
			// - Kitty does as rxvt does here.
			// - Tess does support the XtermClear sequence but has a weird scrollbar behaviour,
			// which does not happen with VtRis.
			// - Zutty does not support E3, and erases the buffer on clear like rxvt, but does work
			// properly with VtRis.
			// - Same behaviour with the multiplexer Zellij.
			if term == "syncterm"
				|| term.contains("rxvt")
				|| term.contains("kitty")
				|| var("CHROME_DESKTOP").map_or(false, |cd| cd == "tess.desktop")
				|| varfull("ZUTTY_VERSION")
				|| varfull("ZELLIJ")
			{
				return Self::VtRis;
			}

			// - screen supports CSI 3J only within the XtermClear sequence, without E3 capability.
			// - Konsole handles CSI 3J correctly only within the XtermClear sequence.
			// - Wezterm handles CSI 3J correctly only within the XtermClear sequence.
			// - assume tmux TERMs are only used within tmux, and avoid the requirement for a functioning terminfo then
			if term.starts_with("screen")
				|| term.starts_with("konsole")
				|| term == "wezterm"
				|| term.starts_with("tmux")
			{
				return Self::XtermClear;
			}

			// Default xterm* terminfo on macOS does not include E3, but many terminals support it.
			if cfg!(target_os = "macos")
				&& term.starts_with("xterm")
				&& Database::from_env()
					.map(|info| info.get::<ResetScrollback>().is_none())
					.unwrap_or(true)
			{
				return Self::XtermClear;
			}

			if !term.is_empty() && Database::from_env().is_ok() {
				return Self::Terminfo;
			}
		}

		Self::XtermClear
	}
}

const ESC: &[u8] = b"\x1b";
const CSI: &[u8] = b"\x1b[";
const RIS: &[u8] = b"c";

impl ClearScreen {
	/// Performs the clearing action, printing to stdout.
	pub fn clear(self) -> Result<(), Error> {
		let mut stdout = io::stdout();
		self.clear_to(&mut stdout)
	}

	/// Performs the clearing action, printing to a given writer.
	///
	/// This allows to capture any escape sequences that might be printed, for example, but note
	/// that it will not prevent actions taken via system APIs, such as the Windows, VtCooked, and
	/// VtWellDone variants do.
	///
	/// For normal use, prefer [`clear()`].
	pub fn clear_to(self, mut w: &mut impl Write) -> Result<(), Error> {
		// The guard keeps VT processing enabled until this function returns.
		#[cfg(windows)]
		let (no_vt, _vt_guard) = match win::vt() {
			Ok(win::VtSupport::Enabled(guard)) => (false, Some(guard)),
			Ok(win::VtSupport::NoVt) => (true, None),
			// Not a console (redirected, captured, detached) or a hard stdio error:
			// write the sequences out as usual, there is no console mode to manage.
			_ => (false, None),
		};

		match self {
			Self::Terminfo => {
				let info = Database::from_env()?;
				let mut ctx = Context::default();

				if let Some(seq) = info.get::<capability::ClearScreen>() {
					seq.expand().with(&mut ctx).to(&mut w)?;
					w.flush()?;
				} else {
					return Err(Error::TerminfoCap("clear"));
				}

				if let Some(seq) = info.get::<ResetScrollback>() {
					seq.expand_to(&mut w, Some(&mut ctx))?;
					w.flush()?;
				}
			}
			Self::TerminfoScreen => {
				let info = Database::from_env()?;
				if let Some(seq) = info.get::<capability::ClearScreen>() {
					seq.expand().to(&mut w)?;
					w.flush()?;
				} else {
					return Err(Error::TerminfoCap("clear"));
				}
			}
			Self::TerminfoScrollback => {
				let info = Database::from_env()?;
				if let Some(seq) = info.get::<ResetScrollback>() {
					seq.expand_to(&mut w, None)?;
					w.flush()?;
				} else {
					return Err(Error::TerminfoCap("E3"));
				}
			}
			Self::TerminfoReset => {
				let info = Database::from_env()?;
				let mut ctx = Context::default();
				let mut reset = false;

				if let Some(seq) = info.get::<capability::Reset1String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::Reset2String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::Reset3String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::ResetFile>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}

				w.flush()?;

				if reset {
					return Ok(());
				}

				if let Some(seq) = info.get::<capability::Init1String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::Init2String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::Init3String>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}
				if let Some(seq) = info.get::<capability::InitFile>() {
					reset = true;
					seq.expand().with(&mut ctx).to(&mut w)?;
				}

				w.flush()?;

				if !reset {
					return Err(Error::TerminfoCap("reset"));
				}
			}
			Self::XtermClear => {
				// If the console host doesn't support VT escapes, clear the legacy way.
				#[cfg(windows)]
				if no_vt {
					return win::clear();
				}

				const CURSOR_HOME: &[u8] = b"H";
				const ERASE_SCREEN: &[u8] = b"2J";
				const ERASE_SCROLLBACK: &[u8] = b"3J";

				w.write_all(CSI)?;
				w.write_all(CURSOR_HOME)?;

				w.write_all(CSI)?;
				w.write_all(ERASE_SCREEN)?;

				w.write_all(CSI)?;
				w.write_all(ERASE_SCROLLBACK)?;

				w.flush()?;
			}
			Self::XtermReset => {
				// If the console host doesn't support VT escapes, clear the legacy way.
				#[cfg(windows)]
				if no_vt {
					return win::clear();
				}

				const STR: &[u8] = b"!p";
				const RESET_WIDTH_AND_SCROLL: &[u8] = b"?3;4l";
				const RESET_REPLACE: &[u8] = b"4l";
				const RESET_KEYPAD: &[u8] = b">";
				const RESET_MARGINS: &[u8] = b"?69l";

				w.write_all(ESC)?;
				w.write_all(RIS)?;

				w.write_all(CSI)?;
				w.write_all(STR)?;

				w.write_all(CSI)?;
				w.write_all(RESET_WIDTH_AND_SCROLL)?;

				w.write_all(CSI)?;
				w.write_all(RESET_REPLACE)?;

				w.write_all(ESC)?;
				w.write_all(RESET_KEYPAD)?;

				w.write_all(CSI)?;
				w.write_all(RESET_MARGINS)?;

				w.flush()?;
			}
			Self::TputClear => {
				let status = Command::new("tput").arg("clear").status()?;
				if !status.success() {
					return Err(Error::Command("tput clear", status));
				}
			}
			Self::TputReset => {
				let status = Command::new("tput").arg("reset").status()?;
				if !status.success() {
					return Err(Error::Command("tput reset", status));
				}
			}
			Self::Cls => {
				let status = Command::new("cmd.exe").arg("/C").arg("cls").status()?;
				if !status.success() {
					return Err(Error::Command("cls", status));
				}
			}
			Self::WindowsConsoleClear => win::clear()?,
			#[cfg(feature = "windows-console")]
			Self::WindowsConsoleBlank => win::blank()?,
			Self::WindowsCooked => win::cooked()?,
			Self::VtRis => {
				w.write_all(ESC)?;
				w.write_all(RIS)?;
				w.flush()?;
			}
			Self::VtLeaveAlt => {
				const LEAVE_ALT: &[u8] = b"?1049l";
				w.write_all(CSI)?;
				w.write_all(LEAVE_ALT)?;
				w.flush()?;
			}
			Self::VtCooked => unix::vt_cooked()?,
			Self::VtWellDone => unix::vt_well_done()?,
		}

		Ok(())
	}
}

/// Shorthand for `ClearScreen::default().clear()`.
pub fn clear() -> Result<(), Error> {
	ClearScreen::default().clear()
}

/// Detects whether the console host supports VT escape processing.
///
/// This is a capability probe, not a version check: it briefly enables the VT processing console
/// mode and restores the previous mode immediately, so it has no lasting side-effects. It returns
/// true for Windows Terminal, for conhost on Windows ≥10, and for any other console host that
/// supports VT processing (a few exist for Windows 8).
///
/// Note that this is only provided to write your own clearscreen logic and _should not_ be relied
/// on for other purposes, as it makes no guarantees of reliable detection, and its internal
/// behaviour may change without notice. Additionally, this will always return false if the library
/// was compiled for a non-Windows target, and if the standard output is not a console (such as
/// when it is redirected or captured).
pub fn is_microsoft_terminal() -> bool {
	win::vt_supported()
}

/// Error type.
#[derive(Debug, Error)]
pub enum Error {
	/// Any I/O error.
	#[error("io: {0}")]
	Io(#[from] io::Error),

	/// A non-success exit status from a command.
	#[error("command: {0}: {1}")]
	Command(&'static str, ExitStatus),

	/// Any nix (libc) error.
	#[cfg(unix)]
	#[error("unix: {0}")]
	Nix(#[from] NixError),

	/// Any terminfo error.
	#[error("terminfo: {0}")]
	Terminfo(#[from] TerminfoError),

	/// A missing terminfo capability.
	#[error("terminfo: capability not available: {0}")]
	TerminfoCap(&'static str),

	/// A null-pointer error.
	#[error("ffi: encountered a null pointer while reading {0}")]
	NullPtr(&'static str),
}

/// Nix error type.
///
/// This wraps a [`nix::Error`] to avoid directly exposing the type in the public API, which
/// required a breaking change every time `clearscreen` updated its `nix` version.
///
/// To obtain a nix error, convert this error to an `i32` then use [`nix::Error::from_raw`]:
///
/// Creating a [`NixError`] is explicitly not possible from the public API.
///
/// ```no_compile
/// let nix_error = nix::Error::from_raw(error.into());
/// assert_eq!(nix_error, nix::Error::EINVAL);
/// ```
#[cfg(unix)]
#[derive(Debug, Error)]
#[error(transparent)]
pub struct NixError(nix::Error);

#[cfg(unix)]
impl From<NixError> for i32 {
	fn from(err: NixError) -> Self {
		err.0 as _
	}
}

/// Terminfo error type.
///
/// This wraps a [`terminfo::Error`] to avoid directly exposing the type in the public API, which
/// required a breaking change every time `clearscreen` updated its `terminfo` version.
#[derive(Debug, Error)]
#[error("{description}")]
pub struct TerminfoError {
	inner: terminfo::Error,
	description: String,
}

impl From<terminfo::Error> for TerminfoError {
	fn from(inner: terminfo::Error) -> Self {
		Self {
			description: inner.to_string(),
			inner,
		}
	}
}

impl From<terminfo::Error> for Error {
	fn from(err: terminfo::Error) -> Self {
		Self::Terminfo(TerminfoError::from(err))
	}
}

#[cfg(unix)]
mod unix {
	use super::{Error, NixError};

	use nix::{
		sys::termios::{
			tcgetattr, tcsetattr, ControlFlags, InputFlags, LocalFlags, OutputFlags,
			SetArg::TCSANOW, Termios,
		},
		unistd::isatty,
	};

	use std::{
		fs::OpenOptions,
		io::stdin,
		os::fd::{AsFd, BorrowedFd},
	};

	pub(crate) fn vt_cooked() -> Result<(), Error> {
		write_termios(cooked_mode)
	}

	pub(crate) fn vt_well_done() -> Result<(), Error> {
		write_termios(well_done_mode)
	}

	fn cooked_mode(t: &mut Termios) {
		t.input_flags
			.insert(InputFlags::BRKINT | InputFlags::ICRNL | InputFlags::IGNPAR | InputFlags::IXON);
		t.output_flags.insert(OutputFlags::OPOST);
		t.local_flags.insert(usable_local_flags());
	}

	fn well_done_mode(t: &mut Termios) {
		#[allow(unused_mut)]
		let mut inserts = InputFlags::BRKINT | InputFlags::ICRNL | InputFlags::IGNPAR | InputFlags::IXON;

		#[cfg(any(target_os = "android", target_os = "linux", target_os = "macos"))]
		{
			inserts |= InputFlags::IUTF8;
		}

		#[cfg(not(target_os = "redox"))]
		{
			inserts |= InputFlags::IMAXBEL;
		}

		t.input_flags.insert(inserts);
		t.output_flags
			.insert(OutputFlags::ONLCR | OutputFlags::OPOST);
		t.control_flags.insert(ControlFlags::CREAD);
		t.local_flags.insert(usable_local_flags());
	}

	/// The local flags a terminal needs for a person to be able to use it.
	///
	/// Canonical mode and signal generation are what make the line editable and
	/// interruptible; echo is what makes it visible. A mode that sets the first two and
	/// not the third leaves a terminal that accepts input without showing it, which is
	/// the state people reach for `reset` to escape.
	///
	/// The echo flags are separate bits, and all of them matter: ECHOE and ECHOK are what
	/// make ERASE and KILL visibly edit the line rather than silently alter a line that
	/// stays on screen as typed, and ECHOCTL and ECHOKE are what render control
	/// characters as `^C` instead of letting them through to the terminal as escape
	/// sequences.
	fn usable_local_flags() -> LocalFlags {
		let mut flags = LocalFlags::ICANON
			| LocalFlags::ISIG
			| LocalFlags::IEXTEN
			| LocalFlags::ECHO
			| LocalFlags::ECHOE
			| LocalFlags::ECHOK;

		#[cfg(not(target_os = "redox"))]
		{
			flags |= LocalFlags::ECHOCTL | LocalFlags::ECHOKE;
		}

		flags
	}

	/// Control bits that describe the line itself rather than how the terminal behaves
	/// on it: how wide a character is, and how fast characters move.
	///
	/// Clearing the screen has no business changing these, and no way to know what to
	/// put back afterwards. Wiping them leaves CSIZE at CS5 and, on Linux where the
	/// speed lives in the control flags, the baud rate at B0 — which on a real serial
	/// line means "hang up". Elsewhere the speed has its own fields, which are not
	/// touched here.
	fn line_configuration() -> ControlFlags {
		#[allow(unused_mut)]
		let mut keep = ControlFlags::CSIZE;

		#[cfg(any(target_os = "android", target_os = "linux"))]
		{
			keep |= ControlFlags::CBAUD;
		}

		keep
	}

	fn reset_termios(t: &mut Termios) {
		t.input_flags.remove(InputFlags::all());
		t.output_flags.remove(OutputFlags::all());
		t.control_flags
			.remove(ControlFlags::all().difference(line_configuration()));
		t.local_flags.remove(LocalFlags::all());
	}

	fn write_termios(f: impl Fn(&mut Termios)) -> Result<(), Error> {
		if isatty(stdin()).map_err(NixError)? {
			write_termios_to(stdin().as_fd(), f)
		} else {
			let tty = OpenOptions::new().read(true).write(true).open("/dev/tty")?;
			write_termios_to(tty.as_fd(), f)
		}
	}

	fn write_termios_to(fd: BorrowedFd<'_>, f: impl Fn(&mut Termios)) -> Result<(), Error> {
		let mut t = tcgetattr(fd).map_err(NixError)?;
		reset_termios(&mut t);
		f(&mut t);
		tcsetattr(fd, TCSANOW, &t).map_err(NixError)?;
		Ok(())
	}

	// openpty is not available everywhere `mod unix` is.
	#[cfg(all(
		test,
		not(any(target_os = "redox", target_os = "fuchsia", target_os = "aix"))
	))]
	mod tests {
		use super::*;
		use nix::pty::openpty;

		/// A terminal as a person would find it, to apply the modes to.
		fn sane_pty() -> nix::pty::OpenptyResult {
			let pty = openpty(None, None).expect("openpty");
			let mut t = tcgetattr(&pty.slave).expect("tcgetattr");
			t.local_flags.insert(usable_local_flags());
			t.input_flags.remove(InputFlags::ISTRIP);
			t.control_flags.remove(ControlFlags::CSIZE);
			t.control_flags.insert(ControlFlags::CS8);
			tcsetattr(&pty.slave, TCSANOW, &t).expect("tcsetattr");
			pty
		}

		/// Both modes, since they share the parts under test and neither may drop echo.
		fn each_mode() -> [(&'static str, fn(&mut Termios)); 2] {
			[
				("vt_cooked", cooked_mode as fn(&mut Termios)),
				("vt_well_done", well_done_mode),
			]
		}

		#[test]
		fn echo_survives() {
			for (name, mode) in each_mode() {
				let pty = sane_pty();
				write_termios_to(pty.slave.as_fd(), mode).expect("write_termios_to");

				let after = tcgetattr(&pty.slave).expect("tcgetattr");
				for flag in [
					LocalFlags::ECHO,
					LocalFlags::ECHOE,
					LocalFlags::ECHOK,
					LocalFlags::ECHOCTL,
					LocalFlags::ECHOKE,
				] {
					assert!(
						after.local_flags.contains(flag),
						"{name} left the terminal without {flag:?}"
					);
				}
				assert!(
					after.local_flags.contains(LocalFlags::IEXTEN),
					"{name} left the terminal without IEXTEN"
				);
				assert!(after.local_flags.contains(LocalFlags::ICANON), "{name}");
				assert!(after.local_flags.contains(LocalFlags::ISIG), "{name}");
			}
		}

		#[test]
		fn the_eighth_bit_is_not_stripped() {
			for (name, mode) in each_mode() {
				let pty = sane_pty();
				write_termios_to(pty.slave.as_fd(), mode).expect("write_termios_to");

				let after = tcgetattr(&pty.slave).expect("tcgetattr");
				assert!(
					!after.input_flags.contains(InputFlags::ISTRIP),
					"{name} set ISTRIP, so UTF-8 input cannot survive"
				);
			}
		}

		/// The line's own configuration is not the screen's to rewrite. Wiping it left
		/// CS5 at B0, and B0 hangs up a real serial line.
		#[test]
		fn the_line_configuration_is_left_alone() {
			for (name, mode) in each_mode() {
				let pty = sane_pty();
				let before = tcgetattr(&pty.slave).expect("tcgetattr");
				write_termios_to(pty.slave.as_fd(), mode).expect("write_termios_to");

				let after = tcgetattr(&pty.slave).expect("tcgetattr");
				assert_eq!(
					after.control_flags & line_configuration(),
					before.control_flags & line_configuration(),
					"{name} changed the character size or line speed"
				);
				assert!(
					after.control_flags.contains(ControlFlags::CS8),
					"{name} left the terminal at fewer than 8 bits per character"
				);
			}
		}

		/// The modes are meant to be applied to a terminal that is already unusable, so
		/// starting from one with echo already off must still produce a usable terminal.
		#[test]
		fn a_terminal_already_without_echo_is_recovered() {
			for (name, mode) in each_mode() {
				let pty = sane_pty();
				let mut t = tcgetattr(&pty.slave).expect("tcgetattr");
				t.local_flags.remove(LocalFlags::all());
				tcsetattr(&pty.slave, TCSANOW, &t).expect("tcsetattr");

				write_termios_to(pty.slave.as_fd(), mode).expect("write_termios_to");

				let after = tcgetattr(&pty.slave).expect("tcgetattr");
				assert!(
					after.local_flags.contains(LocalFlags::ECHO),
					"{name} did not restore echo"
				);
			}
		}
	}
}

#[cfg(windows)]
mod win {
	use super::Error;

	use std::{io, ptr};

	use windows_sys::Win32::Foundation::{FALSE, HANDLE, INVALID_HANDLE_VALUE};
	use windows_sys::Win32::System::Console::{
		GetConsoleMode, GetConsoleScreenBufferInfo, GetStdHandle, ScrollConsoleScreenBufferW,
		SetConsoleCursorPosition, SetConsoleMode, CHAR_INFO, CHAR_INFO_0, CONSOLE_MODE,
		CONSOLE_SCREEN_BUFFER_INFO, COORD, ENABLE_ECHO_INPUT, ENABLE_LINE_INPUT,
		ENABLE_PROCESSED_INPUT, ENABLE_VIRTUAL_TERMINAL_PROCESSING, SMALL_RECT, STD_INPUT_HANDLE,
		STD_OUTPUT_HANDLE,
	};

	#[cfg(feature = "windows-console")]
	use windows_sys::Win32::System::Console::{
		FillConsoleOutputAttribute, FillConsoleOutputCharacterW,
	};

	fn console_handle() -> Result<HANDLE, Error> {
		// SAFETY: GetStdHandle takes a constant handle id and no pointers.
		// Failure is indicated by INVALID_HANDLE_VALUE, checked here; a NULL
		// return is also possible, and flows through to the later console calls,
		// which fail cleanly on it.
		match unsafe { GetStdHandle(STD_OUTPUT_HANDLE) } {
			INVALID_HANDLE_VALUE => Err(io::Error::last_os_error().into()),
			handle => Ok(handle),
		}
	}

	fn console_input_handle() -> Result<HANDLE, Error> {
		// SAFETY: GetStdHandle takes a constant handle id and no pointers.
		// Failure is indicated by INVALID_HANDLE_VALUE, checked here; a NULL
		// return is also possible, and flows through to the later console calls,
		// which fail cleanly on it.
		match unsafe { GetStdHandle(STD_INPUT_HANDLE) } {
			INVALID_HANDLE_VALUE => Err(io::Error::last_os_error().into()),
			handle => Ok(handle),
		}
	}

	fn buffer_info(console: HANDLE) -> Result<CONSOLE_SCREEN_BUFFER_INFO, Error> {
		// SAFETY: `console` is a valid handle obtained from GetStdHandle. `csbi` is
		// a stack-allocated zeroed struct and we pass a valid mutable pointer to it.
		// The return value is checked for failure.
		let mut csbi: CONSOLE_SCREEN_BUFFER_INFO = unsafe { std::mem::zeroed() };
		if unsafe { GetConsoleScreenBufferInfo(console, &mut csbi) } == FALSE {
			return Err(io::Error::last_os_error().into());
		}

		Ok(csbi)
	}

	/// The result of trying to enable VT processing on the console.
	pub(crate) enum VtSupport {
		/// stdout is not a console (redirected, captured, detached): there is no
		/// console mode to manage.
		NotAConsole,
		/// The console host rejected the VT processing mode bit.
		NoVt,
		/// VT processing is enabled; the original console mode is restored when
		/// the guard is dropped.
		Enabled(RestoreConsoleMode),
	}

	/// Restores the console mode captured before VT processing was enabled.
	pub(crate) struct RestoreConsoleMode {
		stdout: HANDLE,
		mode: CONSOLE_MODE,
	}

	impl Drop for RestoreConsoleMode {
		fn drop(&mut self) {
			// SAFETY: SetConsoleMode takes a console handle and a mode value. The
			// handle is the one vt() read the mode from (a valid console handle:
			// GetConsoleMode had succeeded on it), and the mode is the value
			// GetConsoleMode wrote then, so both are valid here. Failure is
			// reported by return value, which is ignored: there is nowhere to
			// surface an error from Drop, and the console may already be gone.
			unsafe {
				SetConsoleMode(self.stdout, self.mode);
			}
		}
	}

	pub(crate) fn vt() -> Result<VtSupport, Error> {
		let stdout = console_handle()?;

		let mut mode = 0;
		// SAFETY: `stdout` is a handle from GetStdHandle and `mode` is a valid
		// mutable reference. GetConsoleMode fails for any non-console handle,
		// which we treat as "not a console" rather than an error, so that
		// writing escape sequences to a redirected stdout keeps working.
		if unsafe { GetConsoleMode(stdout, &mut mode) } == FALSE {
			return Ok(VtSupport::NotAConsole);
		}

		// SAFETY: `stdout` is a console handle (GetConsoleMode succeeded on it),
		// and `mode` is the mode it reported with the VT bit added, so it is a
		// valid mode value. A host that does not support VT processing rejects
		// the mode here, which we report as NoVt rather than an error.
		if unsafe { SetConsoleMode(stdout, mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING) } == FALSE {
			return Ok(VtSupport::NoVt);
		}

		Ok(VtSupport::Enabled(RestoreConsoleMode { stdout, mode }))
	}

	/// Whether the console host supports VT processing.
	///
	/// Probed by briefly enabling the mode: the guard restores the original mode
	/// as soon as it is dropped, so this has no lasting side-effects.
	pub(crate) fn vt_supported() -> bool {
		matches!(vt(), Ok(VtSupport::Enabled(_)))
	}

	// Ref https://docs.microsoft.com/en-us/windows/console/clearing-the-screen#example-2
	pub(crate) fn clear() -> Result<(), Error> {
		let console = console_handle()?;
		let csbi = buffer_info(console)?;

		// Scroll the rectangle of the entire buffer.
		let rect = SMALL_RECT {
			Left: 0,
			Top: 0,
			Right: csbi.dwSize.X,
			Bottom: csbi.dwSize.Y,
		};

		// Scroll it upwards off the top of the buffer with a magnitude of the entire height.
		let target = COORD {
			X: 0,
			Y: (0 - csbi.dwSize.Y) as i16,
		};

		// Fill with empty spaces with the buffer’s default text attribute.
		let space = CHAR_INFO_0 {
			AsciiChar: b' ' as i8,
		};

		let fill = CHAR_INFO {
			Char: space,
			Attributes: csbi.wAttributes,
		};

		// Do the scroll.
		// SAFETY: `console` is a valid handle, all struct arguments are properly initialised,
		// and the null pointer is the expected way to indicate "no clipping rectangle".
		if unsafe { ScrollConsoleScreenBufferW(console, &rect, ptr::null(), target, &fill) }
			== FALSE
		{
			return Err(io::Error::last_os_error().into());
		}

		// Move the cursor to the top left corner too.
		let mut cursor = csbi.dwCursorPosition;
		cursor.X = 0;
		cursor.Y = 0;

		// SAFETY: `console` is a valid handle, `cursor` is a valid COORD.
		if unsafe { SetConsoleCursorPosition(console, cursor) } == FALSE {
			return Err(io::Error::last_os_error().into());
		}

		Ok(())
	}

	// Ref https://docs.microsoft.com/en-us/windows/console/clearing-the-screen#example-3
	#[cfg(feature = "windows-console")]
	pub(crate) fn blank() -> Result<(), Error> {
		let console = console_handle()?;

		// Fill the entire screen with blanks.
		let csbi = buffer_info(console)?;

		let buffer_size = csbi.dwSize.X * csbi.dwSize.Y;
		let home_coord = COORD { X: 0, Y: 0 };

		// SAFETY: `console` is a valid handle, arguments are properly initialised values.
		if FALSE
			== unsafe {
				FillConsoleOutputCharacterW(
					console,
					b' ' as u16,
					u32::try_from(buffer_size).unwrap_or(0),
					home_coord,
					ptr::null_mut(),
				)
			} {
			return Err(io::Error::last_os_error().into());
		}

		// Set the buffer's attributes accordingly.
		let csbi = buffer_info(console)?;
		// SAFETY: `console` is a valid handle, arguments are properly initialised values.
		if FALSE
			== unsafe {
				FillConsoleOutputAttribute(
					console,
					csbi.wAttributes,
					u32::try_from(buffer_size).unwrap_or(0),
					home_coord,
					ptr::null_mut(),
				)
			} {
			return Err(io::Error::last_os_error().into());
		}

		// Put the cursor at its home coordinates.
		// SAFETY: `console` is a valid handle, `home_coord` is a valid COORD.
		if unsafe { SetConsoleCursorPosition(console, home_coord) } == FALSE {
			return Err(io::Error::last_os_error().into());
		}

		Ok(())
	}

	const ENABLE_COOKED_MODE: CONSOLE_MODE =
		ENABLE_ECHO_INPUT | ENABLE_LINE_INPUT | ENABLE_PROCESSED_INPUT;

	pub(crate) fn cooked() -> Result<(), Error> {
		let stdin = console_input_handle()?;

		let mut mode = 0;
		// SAFETY: `stdin` is a valid console handle, `mode` is a valid mutable reference.
		if unsafe { GetConsoleMode(stdin, &mut mode) } == FALSE {
			return Err(io::Error::last_os_error().into());
		}

		mode |= ENABLE_COOKED_MODE;
		// SAFETY: `stdin` is a valid console handle, `mode` is a valid mode value.
		if unsafe { SetConsoleMode(stdin, mode) } == FALSE {
			return Err(io::Error::last_os_error().into());
		}

		Ok(())
	}
}

#[cfg(not(unix))]
#[allow(clippy::unnecessary_wraps)]
mod unix {
	use super::Error;

	pub(crate) fn vt_cooked() -> Result<(), Error> {
		Ok(())
	}

	pub(crate) fn vt_well_done() -> Result<(), Error> {
		Ok(())
	}
}

#[cfg(not(windows))]
#[allow(clippy::unnecessary_wraps)]
mod win {
	use super::Error;

	pub(crate) fn clear() -> Result<(), Error> {
		Ok(())
	}

	#[cfg(feature = "windows-console")]
	pub(crate) fn blank() -> Result<(), Error> {
		Ok(())
	}

	pub(crate) fn cooked() -> Result<(), Error> {
		Ok(())
	}

	pub(crate) fn vt_supported() -> bool {
		false
	}
}

#[derive(Eq, PartialEq, Clone, Debug)]
struct ResetScrollback<'a>(Cow<'a, [u8]>);

impl<'a> Capability<'a> for ResetScrollback<'a> {
	#[inline]
	fn name() -> &'static str {
		"E3"
	}

	#[inline]
	fn from(value: Option<&'a Value>) -> Option<Self> {
		if let Some(Value::String(value)) = value {
			Some(Self(Cow::Borrowed(value)))
		} else {
			None
		}
	}

	#[inline]
	fn into(self) -> Option<Value> {
		Some(Value::String(match self.0 {
			Cow::Borrowed(value) => value.into(),

			Cow::Owned(value) => value,
		}))
	}
}

impl<'a, T: AsRef<&'a [u8]>> From<T> for ResetScrollback<'a> {
	#[inline]
	fn from(value: T) -> Self {
		Self(Cow::Borrowed(value.as_ref()))
	}
}

impl AsRef<[u8]> for ResetScrollback<'_> {
	#[inline]
	fn as_ref(&self) -> &[u8] {
		&self.0
	}
}

impl ResetScrollback<'_> {
	#[inline]
	fn expand_to(
		&self,
		output: &mut impl Write,
		context: Option<&mut Context>,
	) -> Result<(), terminfo::Error> {
		self.as_ref().expand(
			output,
			&<[Parameter; 9]>::default(),
			context.unwrap_or(&mut Default::default()),
		)
	}
}