uncurses/ansi/ctrl.rs
1//! Terminal reset, device-attribute, and version requests.
2//!
3//! ## Category
4//!
5//! This module contains terminal-wide control sequences: RIS (`ESC c`), primary,
6//! secondary, and tertiary Device Attributes, and the XTVERSION query.
7//!
8//! ## CSI conventions
9//!
10//! Device-attribute requests are 7-bit CSI sequences. Private prefixes (`>` and
11//! `=`) distinguish secondary and tertiary forms from primary DA.
12//!
13//! ## Mode interaction
14//!
15//! These requests do not require a mode. RIS is destructive: it asks the terminal
16//! to reset state such as modes, colors, tabs, and character sets.
17
18use std::io::{self, Write};
19
20/// Reset to Initial State: exact bytes `ESC c` (`b"\x1bc"`).
21///
22/// This is a terminal-wide hard reset, not just an SGR or screen clear.
23pub const RIS: &[u8] = b"\x1bc";
24
25/// Write [`RIS`], the `ESC c` Reset to Initial State control.
26///
27/// Use only when the terminal should discard broad state such as modes, tabs, character sets, and visual attributes.
28pub fn write_ris<W: Write>(w: &mut W) -> io::Result<()> {
29 w.write_all(RIS)
30}
31
32/// Primary Device Attributes request: exact bytes `ESC [ c` (`b"\x1b[c"`).
33///
34/// The omitted parameter is the standard DA1 request.
35pub const REQUEST_PRIMARY_DA: &[u8] = b"\x1b[c";
36
37/// Secondary Device Attributes request: exact bytes `ESC [ > c` (`b"\x1b[>c"`).
38pub const REQUEST_SECONDARY_DA: &[u8] = b"\x1b[>c";
39
40/// Tertiary Device Attributes request: exact bytes `ESC [ = c` (`b"\x1b[=c"`).
41pub const REQUEST_TERTIARY_DA: &[u8] = b"\x1b[=c";
42
43/// Terminal name/version request: exact bytes `ESC [ > q` (`b"\x1b[>q"`).
44pub const REQUEST_XTVERSION: &[u8] = b"\x1b[>q";
45
46/// Write the primary Device Attributes request `ESC [ c`.
47pub fn write_request_primary_da<W: Write>(w: &mut W) -> io::Result<()> {
48 w.write_all(REQUEST_PRIMARY_DA)
49}
50
51/// Write the secondary Device Attributes request `ESC [ > c`.
52pub fn write_request_secondary_da<W: Write>(w: &mut W) -> io::Result<()> {
53 w.write_all(REQUEST_SECONDARY_DA)
54}
55
56/// Write the tertiary Device Attributes request `ESC [ = c`.
57pub fn write_request_tertiary_da<W: Write>(w: &mut W) -> io::Result<()> {
58 w.write_all(REQUEST_TERTIARY_DA)
59}
60
61/// Write the terminal version request `ESC [ > q`.
62pub fn write_request_xtversion<W: Write>(w: &mut W) -> io::Result<()> {
63 w.write_all(REQUEST_XTVERSION)
64}