clearscreen

https://docs.rs/clearscreen/4.0.6/clearscreen/
Admin
Cross-platform terminal screen clearing library for Rust that provides multiple ways to clear the...
Tokens:5,572
Snippets:66
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### ClearScreen Enum Usage Example

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Demonstrates how to use the ClearScreen enum in a Rust application. It parses command-line arguments to select a specific clearing variant and then applies it. Includes error handling for unknown variants and a usage message.

```Rust
fn main() -> Result<(), Error> {
	if let Some(variant) = env::args().nth(1) {
		let cs = match variant.as_str() {
			"auto" => ClearScreen::default(),
			"Terminfo" => ClearScreen::Terminfo,
			"TerminfoScreen" => ClearScreen::TerminfoScreen,
			"TerminfoScrollback" => ClearScreen::TerminfoScrollback,
			"TerminfoReset" => ClearScreen::TerminfoReset,
			"XtermClear" => ClearScreen::XtermClear,
			"XtermReset" => ClearScreen::XtermReset,
			"TputClear" => ClearScreen::TputClear,
			"TputReset" => ClearScreen::TputReset,
			"Cls" => ClearScreen::Cls,
			"WindowsVt" => ClearScreen::WindowsVt,
			"WindowsVtClear" => ClearScreen::WindowsVtClear,
			#[cfg(feature = "windows-console")]
			"WindowsConsoleClear" => ClearScreen::WindowsConsoleClear,
			#[cfg(feature = "windows-console")]
			"WindowsConsoleBlank" => ClearScreen::WindowsConsoleBlank,
			"WindowsCooked" => ClearScreen::WindowsCooked,
			"VtRis" => ClearScreen::VtRis,
			"VtLeaveAlt" => ClearScreen::VtLeaveAlt,
			"VtCooked" => ClearScreen::VtCooked,
			"VtWellDone" => ClearScreen::VtWellDone,
			_ => return Err(Error::UnknownVariant(variant)),
		};

		println!("variant = {:?}, sleeping 1 second", cs);
		sleep(Duration::from_secs(1));
		cs.clear()?;

		Ok(())
	} else {
		println!("Usage: cargo run --example clscli -- <variant>\nWhere <variant> is one of the ClearScreen enum variants, same casing, or 'auto'.\nI recommend piping into `hexdump -C` to see what’s happening.");
		Ok(())
	}
}
```

--------------------------------

### Display Implementation for TerminfoError

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.TerminfoError.html

Implements the Display trait for TerminfoError, allowing it to be formatted as a string. This is the recommended way to get a user-friendly error message.

```rust
fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result
```

--------------------------------

### Default ClearScreen Initialization and Execution

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Demonstrates how to initialize ClearScreen with the default method and apply it to clear the screen. This is the recommended approach for most applications.

```rust
ClearScreen::default().clear().expect("failed to clear the screen");
```

--------------------------------

### VtWellDone Mode Explanation

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Describes the 'well done' terminal mode, a custom configuration that approximates a terminal's initial state. It's a superset of VtCooked and aims for broader compatibility.

```text
Sets the terminal to “well done” mode.
This is similar to `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`.
  * 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 ISTRIP set: strip off eigth bit.
  * 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.
  * Local ICANON set: enable canonical mode (see `VtCooked`).
  * Local ISIG set: when Ctrl-C, Ctrl-Q, etc are received, send the appropriate signal.

Does nothing on non-Unix targets.
```

--------------------------------

### Rust Function Signature for is_windows_10

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/fn.is_windows_10.html

This is the function signature for is_windows_10. It returns a boolean indicating whether the system is detected as Windows 10 or later.

```rust
pub fn is_windows_10() -> bool
```

--------------------------------

### Converting NixError to nix::Error

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.NixError.html

Demonstrates how to obtain a nix::Error from a NixError by converting it to an i32 and then using nix::Error::from_raw. This is useful for inspecting the underlying nix error.

```rust
let nix_error = nix::Error::from_raw(error.into());
assert_eq!(nix_error, nix::Error::EINVAL);
```

--------------------------------

### VtCooked Mode Explanation

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Explains the 'cooked' terminal mode, its characteristics, and the specific termios settings involved. This mode is contrasted with 'raw' and 'cbreak' modes.

```text
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 ISTRIP set: strip off eigth bit.
  * Input IXON set: enable XON/XOFF flow control on output.
  * Output OPOST set: enable output processing.
  * Local ICANON set: enable canonical mode (see below).
  * Local ISIG set: when Ctrl-C, Ctrl-Q, etc are received, send the appropriate signal.

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.
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` instead.
Does nothing on non-Unix targets.
```

--------------------------------

### TryFrom and TryInto Traits

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Enables fallible conversions between types. `TryFrom` attempts a conversion and returns a `Result`, while `TryInto` provides a convenient way to perform the same conversion on an existing type.

```APIDOC
## TryFrom and TryInto Traits

### Description
These traits facilitate fallible type conversions. `TryFrom` allows attempting a conversion that might fail, returning a `Result`. `TryInto` is a convenient wrapper for `TryFrom`.

### `TryFrom<U> for T`
#### Associated Type
`type Error = Infallible` - The type returned in the event of a conversion error.
#### Method
`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` - Performs the conversion.

### `TryInto<U> for T`
#### Associated Type
`type Error = <U as TryFrom<T>>::Error` - The type returned in the event of a conversion error.
#### Method
`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` - Performs the conversion.
```

--------------------------------

### clear

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/fn.clear.html

Clears the terminal screen. This function is a shorthand for `ClearScreen::default().clear()`.

```APIDOC
## clear

### Description
Clears the terminal screen. This function is a shorthand for `ClearScreen::default().clear()`.

### Function Signature
```rust
pub fn clear() -> Result<(), Error>
```

### Returns
- `Result<(), Error>`: Ok(()) if the screen was cleared successfully, or an Err containing an `Error` if an issue occurred.
```

--------------------------------

### Clear Terminal Screen (Convenience Function)

Source: https://docs.rs/clearscreen

Use this shorthand function for a cross-platform way to clear the terminal screen. It automatically selects the appropriate method based on the environment. Ensure error handling for potential clearing failures.

```rust
clearscreen::clear().expect("failed to clear screen");
```

--------------------------------

### Xterm Clear Screen and Scrollback Sequence

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

This snippet directly prints the sequences for clearing the screen and erasing scrollback, as if the TERM environment variable were set to 'xterm'. It does not consult the terminfo database.

```rust
/// 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).
pub fn xterm_clear() {
    print!("\x1B[H\x1B[2J\x1B[3J");
}
```

--------------------------------

### Rust clearscreen::clear() Function Signature

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/fn.clear.html

This is the function signature for `clear()`. It returns a Result, indicating success or failure during the screen clearing operation.

```rust
pub fn clear() -> Result<(), Error>
```

--------------------------------

### into

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Converts the enum into another type `U` by calling `U::from(self)`. The specific conversion logic is determined by the `From<T> for U` implementation.

```APIDOC
## into

### Description
Calls `U::from(self)`. That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

### Method Signature
`fn into(self) -> U`
```

--------------------------------

### Detect Microsoft Terminal

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/fn.is_microsoft_terminal.html

Use this function to conditionally execute code when running in Microsoft Terminal. Note that this detection is not guaranteed to be reliable and may change without notice.

```rust
pub fn is_microsoft_terminal() -> bool
```

--------------------------------

### ClearScreen::clear Implementation

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

The implementation of the clear function for the ClearScreen enum, which performs the screen clearing action by printing to stdout. This is the primary function for clearing the terminal screen.

```rust
pub fn clear(self) -> Result<(), Error>
```

--------------------------------

### From<Error> for TerminfoError Conversion

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.TerminfoError.html

Implements the From trait to convert a terminfo::Error into a TerminfoError. This allows for easy error conversion when handling errors from the terminfo crate.

```rust
fn from(inner: Error) -> Self
```

--------------------------------

### Rust clearscreen Error Enum Definition

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.Error.html

Defines the different types of errors that can occur when using the clearscreen crate. This enum covers I/O errors, command execution failures, nix errors, terminfo errors, missing terminfo capabilities, and null pointer errors.

```rust
pub enum Error {
    Io(Error),
    Command(&'static str, ExitStatus),
    Nix(NixError),
    Terminfo(TerminfoError),
    TerminfoCap(&'static str),
    NullPtr(&'static str),
}
```

--------------------------------

### is_microsoft_terminal

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/fn.is_microsoft_terminal.html

Detects if the current terminal is Microsoft Terminal. This function is provided to allow users to implement their own clearscreen logic and should not be used for other purposes. Its internal behavior may change without notice.

```APIDOC
## is_microsoft_terminal

### Description
Detects if the current terminal is Microsoft Terminal.

### Signature
```rust
pub fn is_microsoft_terminal() -> bool
```

### Returns
- `bool`: Returns `true` if the terminal is detected as Microsoft Terminal, `false` otherwise.

### Notes
This function is intended solely for writing custom clearscreen logic. It makes no guarantees of reliable detection, and its internal behavior may change without notice. It should not be relied upon for any other purpose.
```

--------------------------------

### From<TerminfoError> for Error Conversion

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.TerminfoError.html

Implements the From trait to convert a TerminfoError back into a terminfo::Error. This can be useful in scenarios where the underlying terminfo error type is needed.

```rust
fn from(source: TerminfoError) -> Self
```

--------------------------------

### Error Source Implementation for TerminfoError

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.TerminfoError.html

Implements the Error trait's source method for TerminfoError. This method returns the underlying error that caused this TerminfoError, if any.

```rust
fn source(&self) -> Option<&(dyn Error + 'static)>
```

--------------------------------

### TerminfoError Struct Definition

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.TerminfoError.html

Defines the TerminfoError struct, which wraps a private terminfo::Error. This is used to manage version updates of the terminfo crate without breaking the clearscreen API.

```rust
pub struct TerminfoError { /* private fields */ }
```

--------------------------------

### ToOwned Trait

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/enum.ClearScreen.html

Provides methods for creating owned data from borrowed data. This is useful for scenarios where you need to work with owned copies of data.

```APIDOC
## ToOwned Trait

### Description
Provides methods for creating owned data from borrowed data, usually by cloning.

### Associated Type
`type Owned = T` - The resulting type after obtaining ownership.

### Methods
#### `to_owned(&self) -> T`
Creates owned data from borrowed data, usually by cloning.

#### `clone_into(&self, target: &mut T)`
Uses borrowed data to replace owned data, usually by cloning.
```

--------------------------------

### NixError Struct Definition

Source: https://docs.rs/clearscreen/4.0.6/clearscreen/struct.NixError.html

Defines the NixError struct, which wraps a nix::Error. It is not possible to create a NixError directly from the public API.

```rust
pub struct NixError(/* private fields */);
```
Tokens:
Raw