uncurses/terminal/mod.rs
1//! Terminal handles, raw-mode state, window-size queries, and tty helpers.
2//!
3//! The terminal module provides the building blocks used by renderers and
4//! event sources: [`Terminal`] for pairing input and output handles,
5//! raw-mode save/restore helpers, direct stdio handles, controlling-terminal
6//! opening, and environment snapshots.
7//!
8//! ## The `Terminal<I, O>` handle
9//!
10//! [`Terminal`] owns an input half, an output half, an [`Env`] snapshot, and an
11//! optional saved raw-mode [`State`]. It implements [`std::io::Read`] by
12//! reading from the input half and [`std::io::Write`] by writing to the output
13//! half. Use [`Terminal::stdio`] for inherited stdin/stdout, or
14//! [`Terminal::open`] to talk directly to the controlling terminal when stdio
15//! may be redirected.
16//!
17//! ## Raw-mode lifecycle
18//!
19//! Raw mode is an explicit save/apply/restore flow. [`Terminal::make_raw`]
20//! calls `make_raw_mode`, stores the returned [`State`] inside the
21//! `Terminal`, and returns a clone of that state. [`Terminal::restore`] applies
22//! the stored state with `set_state` and clears it. The free functions expose
23//! the same lifecycle for callers that manage handles and state themselves.
24//!
25//! ```text
26//! normal terminal state
27//! │
28//! │ make_raw() -> State
29//! ▼
30//! raw terminal state ────── use terminal ──────┐
31//! │ │
32//! └──────── restore()/set_state(State) ◀
33//! ```
34//!
35//! There is no paired enable/disable function in this API; keep the returned
36//! [`State`] or the [`Terminal`] that cached it, and restore explicitly.
37//!
38//! ## Window size
39//!
40//! `get_window_size` queries the operating system for cell dimensions and,
41//! where available, pixel dimensions. [`Terminal::get_window_size`] applies the
42//! platform-specific handle selection: Unix tries output first, then input;
43//! Windows queries the output console screen buffer.
44//!
45//! ## Stdio and controlling-terminal handles
46//!
47//! [`stdin`], [`stdout`], and [`stderr`] wrap the inherited process streams as
48//! cheap, copyable, unbuffered handles. `open_tty` opens the controlling
49//! terminal directly: Unix uses `/dev/tty` for both halves, and Windows uses
50//! `CONIN$` for input and `CONOUT$` for output. The direct tty path is useful
51//! for applications whose stdin or stdout may be a pipe but which still need a
52//! real terminal.
53//!
54//! ```rust,ignore
55//! use uncurses::terminal::Terminal;
56//!
57//! let mut term = Terminal::stdio();
58//! let saved = term.make_raw()?;
59//! let size = term.get_window_size()?;
60//! let _ = (saved, size.col, size.row);
61//! term.restore()?;
62//! # Ok::<(), std::io::Error>(())
63//! ```
64
65mod env;
66mod handle;
67mod raw;
68mod size;
69mod stdio;
70mod tty;
71
72pub use env::Env;
73pub use handle::Terminal;
74pub use raw::State;
75pub use size::Winsize;
76pub use stdio::{Stderr, StderrLock, Stdin, StdinLock, Stdout, StdoutLock, stderr, stdin, stdout};
77pub use tty::{TtyInput, TtyOutput};
78
79#[cfg(unix)]
80pub(crate) use size::get_window_size;