Struct Terminal 

pub struct Terminal<I, O> { /* private fields */ }

Owned terminal handle pairing input, output, environment, and raw-mode state.

Terminal implements Read from I and Write to O. The handle is generic so callers can use inherited stdio, the controlling terminal, or test doubles, while sharing one raw-mode and window-size API on supported platforms.

Implementations

impl Terminal<Stdin, Stdout>

pub fn stdio() -> Self

Create a terminal over inherited standard input and output.

The returned handle uses stdin for input, stdout for output, and Env::from_process for its environment snapshot. Use this when the process is expected to be connected directly to the terminal.

Returns

A Terminal<Stdin, Stdout> with no saved raw-mode state.

Errors and panics

This constructor does not fail or intentionally panic.

Usage note

If stdin or stdout may be redirected, prefer Terminal::open to open the controlling terminal directly.

impl Terminal<TtyInput, TtyOutput>

pub fn open() -> Result<Self>

Open the controlling terminal directly.

On Unix this opens /dev/tty for both input and output. On Windows it opens CONIN$ for input and CONOUT$ for output. The returned Terminal snapshots the process environment with Env::from_process.

Returns

A Terminal<TtyInput, TtyOutput> backed by the controlling terminal.

Errors

Returns the error from open_tty if the process has no controlling terminal or if the platform device cannot be opened.

Panics

This function does not intentionally panic.

impl<I, O> Terminal<I, O>

pub fn env(&self) -> &Env

Return the captured environment snapshot.

The snapshot is taken by the constructor and is not updated if the process environment later changes.

Returns

A shared reference to the terminal’s Env.

Errors and panics

This method does not fail or intentionally panic.

pub fn get_env(&self, key: &str) -> Option<String>

Look up an environment variable in the captured snapshot.

Parameters

• key — environment variable name.

Returns

The last captured value for key, or None if it is absent.

Errors and panics

This method does not fail or intentionally panic.

pub fn has_env(&self, key: &str) -> bool

Return whether an environment variable is present and non-empty.

Parameters

• key — environment variable name.

Returns

true when the captured snapshot contains key with a non-empty value.

Errors and panics

This method does not fail or intentionally panic.

pub fn input(&self) -> I

where I: Copy,

Return a copy of the input half.

This is available only when I: Copy, which is true for the standard and controlling-terminal handle types provided by this module. Use it to pass input to EventSource::new while retaining the Terminal for raw-mode restoration.

Returns

A copy of the input handle.

Errors and panics

This method does not fail or intentionally panic.

pub fn output(&self) -> O

where O: Copy,

Return a copy of the output half.

This is available only when O: Copy, which is true for the standard and controlling-terminal output types provided by this module. Use it to pass output to a renderer such as TextBuffer while retaining the Terminal for raw-mode restoration.

Returns

A copy of the output handle.

Errors and panics

This method does not fail or intentionally panic.

pub fn into_halves(self) -> (I, O)

Consume the terminal and return its input and output halves.

Any cached raw-mode state is dropped without being applied. Restore before calling this method if the terminal is in raw mode.

Returns

(input, output).

Errors and panics

This method does not fail or intentionally panic.

impl<I: AsFd, O: AsFd> Terminal<I, O>

pub fn new(input: I, output: O, env: Env) -> Self

Build a terminal from input and output descriptors plus an Env.

The environment is stored exactly as provided and is not required to describe the given descriptors. Use Terminal::stdio or Terminal::open to snapshot the process environment automatically.

Parameters

• input — readable terminal descriptor.
• output — writable terminal descriptor.
• env — environment snapshot associated with this terminal.

Returns

A Terminal with no saved raw-mode state.

Errors and panics

This constructor does not fail or intentionally panic.

pub fn make_raw(&mut self) -> Result<State>

Put the terminal into raw mode and save the previous state.

This calls make_raw_mode with the terminal’s input and output descriptors. The returned pre-raw State is cloned into the terminal so restore can later apply it without an argument.

Returns

The state that was active before raw mode was applied.

Errors

Returns any error from reading the current state or applying the raw state.

Panics

This method does not intentionally panic.

pub fn restore(&mut self) -> Result<()>

Restore the state cached by the most recent make_raw.

If a state is cached, it is applied with set_state and then cleared. If no state is cached, this is a no-op.

Returns

Ok(()) when no state was cached or restoration succeeded.

Errors

Returns any error from applying the cached state.

Panics

This method does not intentionally panic.

pub fn get_state(&self) -> Result<State>

Snapshot the current terminal mode.

This reads the terminal state without modifying the cached state used by restore.

Returns

The current State.

Errors

Returns any error from get_state.

Panics

This method does not intentionally panic.

pub fn set_state(&self, state: &State) -> Result<()>

Apply a previously snapshotted terminal mode.

This does not update or clear the state cached by make_raw. Use it for manual state management; use restore for the terminal-owned raw-mode lifecycle.

Parameters

• state — state to apply to the terminal.

Returns

Ok(()) when the state was applied.

Errors

Returns any error from set_state.

Panics

This method does not intentionally panic.

pub fn is_terminal(&self) -> (bool, bool)

Report whether the input and output halves are terminals.

Returns

(input_is_terminal, output_is_terminal).

Errors and panics

This method does not fail or intentionally panic.

pub fn get_window_size(&self) -> Result<Winsize>

Query the current terminal window size.

On Unix this tries the output descriptor first and falls back to the input descriptor if the output query fails. If both fail, the output descriptor’s error is returned.

Returns

The current window size in cells and, when reported by the platform, pixels.

Errors

Returns an OS error if the size cannot be queried from either half.

Panics

This method does not intentionally panic.

Trait Implementations

impl<I: AsFd, O> AsFd for Terminal<I, O>

Available on Unix only.

fn as_fd(&self) -> BorrowedFd<'_>

Borrow the input descriptor.

This exposes the input half, not the output half. Use output and borrow that handle when an output descriptor is required.

impl<I: Read, O> Read for Terminal<I, O>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

impl<I, O: Write> Write for Terminal<I, O>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.