Struct Terminal

pub struct Terminal<W: Write> { /* private fields */ }

A simple interface to perform operations on the terminal. It also allows terminal values to be queried.

Examples

use terminal::{Clear, Action, Value, Retrieved, error};

pub fn main() -> error::Result<()> {
    let terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..100 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("x: {}, y: {}", x, y);
    }

    Ok(())
}

Notes

Implementations

impl<W: Write> Terminal<W>

pub fn custom(buffer: W) -> Terminal<W>

Creates a custom buffered Terminal with the given buffer.

Examples found in repository

examples/basic.rs (line 8)

fn different_buffers() {
    let _stdout = stdout();
    let _stderr = stderr();
    let _file = Terminal::custom(File::create("./test.txt").unwrap());
}

/// Gets values from the terminal.
fn get_value() -> error::Result<()> {
    let stdout = stdout();

    if let Retrieved::CursorPosition(x, y) = stdout.get(Value::CursorPosition)? {
        println!("X: {}, Y: {}", x, y);
    }

    if let Retrieved::TerminalSize(column, row) = stdout.get(Value::TerminalSize)? {
        println!("columns: {}, rows: {}", column, row);
    }

    // see '/examples/event.rs'
    if let Retrieved::Event(event) = stdout.get(Value::Event(None))? {
        println!("Event: {:?}\r", event);
    }

    Ok(())
}

fn perform_action() -> error::Result<()> {
    let stdout = stdout();
    stdout.act(Action::MoveCursorTo(10, 10))
}

/// Batches multiple actions before executing.
fn batch_actions() -> error::Result<()> {
    let terminal = stdout();
    terminal.batch(Action::ClearTerminal(Clear::All))?;
    terminal.batch(Action::MoveCursorTo(5, 5))?;

    thread::sleep(Duration::from_millis(2000));
    println!("@");

    terminal.flush_batch()
}

/// Acquires lock once, and uses that lock to do actions.
fn lock_terminal() -> error::Result<()> {
    let terminal = Terminal::custom(File::create("./test.txt").unwrap());

    let mut lock = terminal.lock_mut()?;

    for i in 0..10000 {
        println!("{}", i);

        if i % 100 == 0 {
            lock.act(Action::ClearTerminal(Clear::All))?;
            lock.act(Action::MoveCursorTo(0, 0))?;
        }
        thread::sleep(Duration::from_millis(10));
    }

    Ok(())
}

pub fn lock_mut(&self) -> Result<TerminalLock<'_, W>>

Locks this Terminal, returning a mutable lock guard. A deadlock is not possible, instead an error will be returned if a lock is already in use. Make sure this lock is only used at one place. The lock is released when the returned lock goes out of scope.

Examples found in repository

examples/style.rs (line 74)

fn main() {
    let terminal = stdout();
    let mut lock = terminal.lock_mut().unwrap();

    rgb(&mut lock);

    thread::sleep(Duration::from_millis(2000))
}

examples/attribute.rs (line 39)

pub fn main() {
    let stdout = stdout();
    let mut lock = stdout.lock_mut().unwrap();

    display_attributes(&mut lock);

    thread::sleep(Duration::from_millis(5000))
}

examples/basic.rs (line 52)

fn lock_terminal() -> error::Result<()> {
    let terminal = Terminal::custom(File::create("./test.txt").unwrap());

    let mut lock = terminal.lock_mut()?;

    for i in 0..10000 {
        println!("{}", i);

        if i % 100 == 0 {
            lock.act(Action::ClearTerminal(Clear::All))?;
            lock.act(Action::MoveCursorTo(0, 0))?;
        }
        thread::sleep(Duration::from_millis(10));
    }

    Ok(())
}

examples/alternate-raw.rs (line 8)

fn main() {
    let terminal = stdout();

    let mut lock = terminal.lock_mut().unwrap();

    lock.act(Action::EnterAlternateScreen).unwrap();
    lock.act(Action::EnableRawMode).unwrap();
    lock.act(Action::HideCursor).unwrap();

    write_alt_screen_msg(&mut lock);

    lock.flush_batch().unwrap();

    loop {
        if let Retrieved::Event(Some(Event::Key(key))) = lock.get(Value::Event(None)).unwrap() {
            match key {
                KeyEvent {
                    code: KeyCode::Char('q'),
                    ..
                } => {
                    break;
                }
                KeyEvent {
                    code: KeyCode::Char('1'),
                    ..
                } => {
                    lock.act(Action::LeaveAlternateScreen).unwrap();
                }
                KeyEvent {
                    code: KeyCode::Char('2'),
                    ..
                } => {
                    lock.act(Action::EnterAlternateScreen).unwrap();
                    write_alt_screen_msg(&mut lock);
                }
                _ => {}
            };
        }
    }

    lock.act(Action::DisableRawMode).unwrap();
    lock.act(Action::ShowCursor).unwrap();
}

pub fn act(&self, action: Action) -> Result<()>

Performs an action on the terminal.

Note

Acquires an lock for underlying mutability, this can be prevented with lock_mut.

Examples found in repository

examples/basic.rs (line 33)

fn perform_action() -> error::Result<()> {
    let stdout = stdout();
    stdout.act(Action::MoveCursorTo(10, 10))
}

examples/event.rs (line 13)

fn block_read() -> error::Result<()> {
    let terminal = stdout();

    terminal.act(Action::EnableRawMode)?;

    loop {
        if let Retrieved::Event(event) = terminal.get(Value::Event(None))? {
            match event {
                Some(Event::Key(KeyEvent {
                    code: KeyCode::Esc, ..
                })) => return Ok(()),
                Some(event) => {
                    println!("{:?}\r", event);
                }
                _ => {}
            }
        }
    }
}

/// Reads events withing a certain duration.
fn with_duration_read() -> error::Result<()> {
    let terminal = stdout();

    terminal.act(Action::EnableRawMode)?;
    terminal.act(Action::EnableMouseCapture)?;

    loop {
        if let Retrieved::Event(event) =
            terminal.get(Value::Event(Some(Duration::from_millis(500))))?
        {
            match event {
                Some(Event::Key(KeyEvent {
                    code: KeyCode::Esc, ..
                })) => return Ok(()),
                Some(event) => {
                    println!("{:?}\r", event);
                }
                None => println!("...\r"),
            }
        }
    }
}

examples/readme.rs (line 8)

pub fn main() -> error::Result<()> {
    let mut terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..20 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
        terminal.write(format!("{}", i).as_bytes());
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("\nx: {}, y: {}", x, y);
    }

    Ok(())
}

pub fn batch(&self, action: Action) -> Result<()>

Batches an action for later execution. You can flush/execute the batched actions with batch.

Note

Acquires an lock for underlying mutability, this can be prevented with lock_mut.

Examples found in repository

examples/basic.rs (line 39)

fn batch_actions() -> error::Result<()> {
    let terminal = stdout();
    terminal.batch(Action::ClearTerminal(Clear::All))?;
    terminal.batch(Action::MoveCursorTo(5, 5))?;

    thread::sleep(Duration::from_millis(2000));
    println!("@");

    terminal.flush_batch()
}

examples/readme.rs (line 12)

pub fn main() -> error::Result<()> {
    let mut terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..20 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
        terminal.write(format!("{}", i).as_bytes());
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("\nx: {}, y: {}", x, y);
    }

    Ok(())
}

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

Flushes the batched actions, this executes the actions in the order that they were batched. You can batch an action with batch.

Note

Acquires an lock for underlying mutability, this can be prevented with lock_mut.

Examples found in repository

examples/basic.rs (line 45)

fn batch_actions() -> error::Result<()> {
    let terminal = stdout();
    terminal.batch(Action::ClearTerminal(Clear::All))?;
    terminal.batch(Action::MoveCursorTo(5, 5))?;

    thread::sleep(Duration::from_millis(2000));
    println!("@");

    terminal.flush_batch()
}

examples/readme.rs (line 17)

pub fn main() -> error::Result<()> {
    let mut terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..20 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
        terminal.write(format!("{}", i).as_bytes());
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("\nx: {}, y: {}", x, y);
    }

    Ok(())
}

pub fn get(&self, value: Value) -> Result<Retrieved>

Gets an value from the terminal.

Examples found in repository

examples/event.rs (line 16)

fn block_read() -> error::Result<()> {
    let terminal = stdout();

    terminal.act(Action::EnableRawMode)?;

    loop {
        if let Retrieved::Event(event) = terminal.get(Value::Event(None))? {
            match event {
                Some(Event::Key(KeyEvent {
                    code: KeyCode::Esc, ..
                })) => return Ok(()),
                Some(event) => {
                    println!("{:?}\r", event);
                }
                _ => {}
            }
        }
    }
}

/// Reads events withing a certain duration.
fn with_duration_read() -> error::Result<()> {
    let terminal = stdout();

    terminal.act(Action::EnableRawMode)?;
    terminal.act(Action::EnableMouseCapture)?;

    loop {
        if let Retrieved::Event(event) =
            terminal.get(Value::Event(Some(Duration::from_millis(500))))?
        {
            match event {
                Some(Event::Key(KeyEvent {
                    code: KeyCode::Esc, ..
                })) => return Ok(()),
                Some(event) => {
                    println!("{:?}\r", event);
                }
                None => println!("...\r"),
            }
        }
    }
}

examples/basic.rs (line 15)

fn get_value() -> error::Result<()> {
    let stdout = stdout();

    if let Retrieved::CursorPosition(x, y) = stdout.get(Value::CursorPosition)? {
        println!("X: {}, Y: {}", x, y);
    }

    if let Retrieved::TerminalSize(column, row) = stdout.get(Value::TerminalSize)? {
        println!("columns: {}, rows: {}", column, row);
    }

    // see '/examples/event.rs'
    if let Retrieved::Event(event) = stdout.get(Value::Event(None))? {
        println!("Event: {:?}\r", event);
    }

    Ok(())
}

examples/readme.rs (line 20)

pub fn main() -> error::Result<()> {
    let mut terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..20 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
        terminal.write(format!("{}", i).as_bytes());
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("\nx: {}, y: {}", x, y);
    }

    Ok(())
}

Trait Implementations

impl<'a, W: Write> Write for Terminal<W>

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.