Struct mortal::terminal::Terminal

pub struct Terminal(_);

Provides concurrent read and write access to a terminal device

Concurrency

Access to read and write operations is controlled by two internal locks: One for reading and one for writing. Each lock may be held independently of the other.

If any one thread wishes to hold both locks, the read lock must be acquired first, in order to prevent deadlocks.

Methods

impl Terminal

pub fn new() -> Result<Terminal>

Opens a new interface to the terminal on stdout.

pub fn stderr() -> Result<Terminal>

Opens a new interface to the terminal on stderr.

pub fn name(&self) -> &str

Returns the name of the terminal.

Notes

On Unix, this method returns the contents of the TERM environment variable.

On Windows, this method always returns the string "windows-console".

pub fn lock_read(&self) -> LockResult<TerminalReadGuard>

Attempts to acquire an exclusive lock on terminal read operations.

The current thread will block until the lock can be acquired.

pub fn lock_write(&self) -> LockResult<TerminalWriteGuard>

Attempts to acquire an exclusive lock on terminal write operations.

The current thread will block until the lock can be acquired.

pub fn try_lock_read(&self) -> TryLockResult<TerminalReadGuard>

Attempts to acquire an exclusive lock on terminal read operations.

If the lock cannot be acquired immediately, Err(_) is returned.

pub fn try_lock_write(&self) -> TryLockResult<TerminalWriteGuard>

Attempts to acquire an exclusive lock on terminal write operations.

If the lock cannot be acquired immediately, Err(_) is returned.

impl Terminal

Locking

The following methods internally acquire both the read and write locks.

The locks are released before the method returns.

These methods are also implemented on TerminalReadGuard, which holds the Terminal read lock until the value is dropped.

pub fn prepare(&self, config: PrepareConfig) -> Result<PrepareState>

Prepares the terminal to read input.

When reading operations have concluded, restore should be called with the resulting PrepareState value to restore the terminal to its previous state.

This method may be called more than once before a corresponding restore call. However, each restore call must receive the most recently created PrepareState value.

See PrepareConfig for details.

pub fn restore(&self, state: PrepareState) -> Result<()>

Restores the terminal to its previous state.

impl Terminal

Locking

The following methods internally acquire the read lock.

The lock is released before the method returns.

These methods are also implemented on TerminalReadGuard, which holds the Terminal read lock until the value is dropped.

pub fn wait_event(&self, timeout: Option<Duration>) -> Result<bool>

Waits for an event from the terminal.

Returns Ok(false) if timeout elapses without an event occurring.

If timeout is None, this method will wait indefinitely.

pub fn read_event(&self, timeout: Option<Duration>) -> Result<Option<Event>>

Waits for input and reads an event from the terminal.

Returns Ok(None) if timeout elapses without an event occurring.

If timeout is None, this method will wait indefinitely.

impl Terminal

Locking

The following methods internally acquire the write lock.

The lock is released before the method returns.

These methods are also implemented on TerminalWriteGuard, which holds the Terminal write lock until the value is dropped.

pub fn size(&self) -> Result<Size>

Returns the size of the terminal.

pub fn clear_screen(&self) -> Result<()>

Clears the terminal screen, placing the cursor at the first line and column.

If the terminal contains a scrolling window over a buffer, the window will be scrolled downward, preserving as much of the existing buffer as possible.

pub fn clear_to_line_end(&self) -> Result<()>

Clears the current line, starting at cursor position.

pub fn clear_to_screen_end(&self) -> Result<()>

Clears the screen, starting at cursor position.

pub fn move_up(&self, n: usize) -> Result<()>

Moves the cursor up n lines.

pub fn move_down(&self, n: usize) -> Result<()>

Moves the cursor down n lines.

pub fn move_left(&self, n: usize) -> Result<()>

Moves the cursor left n columns.

pub fn move_right(&self, n: usize) -> Result<()>

Moves the cursor right n columns.

pub fn move_to_first_column(&self) -> Result<()>

Moves the cursor to the first column of the current line

pub fn set_cursor_mode(&self, mode: CursorMode) -> Result<()>

Set the current cursor mode.

This setting is a visible hint to the user. It produces no change in behavior.

Notes

On some systems, this setting may have no effect.

pub fn add_style(&self, style: Style) -> Result<()>

Adds a set of Style flags to the current style setting.

pub fn remove_style(&self, style: Style) -> Result<()>

Removes a set of Style flags from the current style setting.

pub fn set_style<S>(&self, style: S) -> Result<()> where
    S: Into<Option<Style>>, 

Sets the current style to the given set of flags.

pub fn set_theme(&self, theme: Theme) -> Result<()>

Sets all attributes for the terminal.

pub fn set_fg<C: Into<Option<Color>>>(&self, fg: C) -> Result<()>

Sets the foreground text color.

pub fn set_bg<C: Into<Option<Color>>>(&self, bg: C) -> Result<()>

Sets the background text color.

pub fn clear_attributes(&self) -> Result<()>

Removes color and style attributes.

pub fn bold(&self) -> Result<()>

Adds bold to the current style setting.

This is equivalent to self.add_style(Style::BOLD).

pub fn italic(&self) -> Result<()>

Adds italic to the current style setting.

This is equivalent to self.add_style(Style::ITALIC).

pub fn underline(&self) -> Result<()>

Adds underline to the current style setting.

This is equivalent to self.add_style(Style::UNDERLINE).

pub fn reverse(&self) -> Result<()>

Adds reverse to the current style setting.

This is equivalent to self.add_style(Style::REVERSE).

pub fn write_styled<F, B, S>(
    &self,
    fg: F,
    bg: B,
    style: S,
    s: &str
) -> Result<()> where
    F: Into<Option<Color>>,
    B: Into<Option<Color>>,
    S: Into<Option<Style>>, 

Writes output to the terminal with the given color and style.

All attributes are removed after the given text is written.

pub fn write_char(&self, ch: char) -> Result<()>

Writes a single character to the terminal using the current style and color settings.

pub fn write_str(&self, s: &str) -> Result<()>

Writes a string to the terminal using the current style and color settings.

pub fn write_fmt(&self, args: Arguments) -> Result<()>

Writes formatted text to the terminal using the current style and color settings.

This method enables Terminal to be used as the receiver to the write! and writeln! macros.

Examples

let term = Terminal::new()?;

writeln!(term, "Hello, world!")?;

Trait Implementations

impl OpenTerminalExt for Terminal

fn from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Opens a terminal interface on the device at the given path.

impl TerminalExt for Terminal

fn read_raw(
    &mut self,
    buf: &mut [u8],
    timeout: Option<Duration>
) -> Result<Option<Event>>

Reads raw data from the terminal.