terminal_prompt

Struct Terminal

Source
pub struct Terminal { /* private fields */ }
Expand description

A handle to the terminal associated with the current process.

Once opened, you can use Self::prompt() to read non-sensitive data from the terminal, and Self::prompt_sensitive() to read sensitive data like passwords.

Alternatively, you can manually call Self::enable_echo() and Self::disable_echo(), and read/write from the terminal directly. The terminal handle implements the standard Read, Write and BufRead traits, and it has a Self::read_line() convenience function that returns a new string.

§Terminal modes

When opened, the terminal will be put in line editing mode. When dropped, the original mode of the terminal will be restored. Note that the terminal is inherently a global resource, so creating multiple terminal objects and dropping them in a different order can cause the terminal to be left in a different mode.

Implementations§

Source§

impl Terminal

Source

pub fn open() -> Result<Self>

Open the terminal associated with the current process.

The exact behavior is platform dependent.

On Unix platforms, if one of standard I/O streams is a terminal, that terminal is used. First standard error is tried, then standard input and finally standard output. If none of those work, the function tries to open /dev/tty. This means that on Unix platforms, the terminal prompt can still work, even when both standard input and standard output are connected to pipes instead of the terminal.

On Windows, if both standard input and standard error are connected to a terminal, those streams are used.

In all cases, if the function fails to find a terminal for the process, an error is returned.

Examples found in repository?
examples/username-password.rs (line 4)
3
4
5
6
7
8
9
10
fn main() -> std::io::Result<()> {
	let mut terminal = Terminal::open()?;
	let username = terminal.prompt("Username: ")?;
	let password = terminal.prompt_sensitive("Password: ")?;
	println!("Username: {username}");
	println!("Password: {password}");
	Ok(())
}
Source

pub fn is_echo_enabled(&self) -> Result<bool>

Check if the terminal is echoing input.

If enabled, any text typed on the terminal will be visible.

Source

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

Disable echoing of terminal input.

This will prevent text typed on the terminal from being visible. This can be used to hide passwords while they are being typed.

Source

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

Enable echoing of terminal input.

This will cause any text typed on the terminal to be visible.

Source

pub fn read_input_line(&mut self) -> Result<String>

Read a line of input from the terminal.

If echoing is disabled, this will also print a newline character to visually indicate to the user. If this is not desired, use the BufRead::read_line() function instead.

Source

pub fn prompt(&mut self, prompt: impl Display) -> Result<String>

Prompt the user on the terminal.

This function does not enable or disable echoing and should not normally be used for reading sensitive data like passwords. Consider Self::prompt_sensitive() instead.

Examples found in repository?
examples/username-password.rs (line 5)
3
4
5
6
7
8
9
10
fn main() -> std::io::Result<()> {
	let mut terminal = Terminal::open()?;
	let username = terminal.prompt("Username: ")?;
	let password = terminal.prompt_sensitive("Password: ")?;
	println!("Username: {username}");
	println!("Password: {password}");
	Ok(())
}
Source

pub fn prompt_sensitive(&mut self, prompt: impl Display) -> Result<String>

Prompt the user for sensitive data (like passwords) on the terminal.

This function makes sure that echoing is disabled before the prompt is shown. If echoing was enabled, it is re-enabled after the response is read.

Use Self::prompt() to read non-sensitive data.

Examples found in repository?
examples/username-password.rs (line 6)
3
4
5
6
7
8
9
10
fn main() -> std::io::Result<()> {
	let mut terminal = Terminal::open()?;
	let username = terminal.prompt("Username: ")?;
	let password = terminal.prompt_sensitive("Password: ")?;
	println!("Username: {username}");
	println!("Password: {password}");
	Ok(())
}

Trait Implementations§

Source§

impl BufRead for Terminal

Source§

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty. Read more
Source§

fn consume(&mut self, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to read. Read more
Source§

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)
Checks if the underlying Read has any data left to be read. Read more
1.0.0 · Source§

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

Reads all bytes into buf until the delimiter byte or EOF is reached. Read more
1.83.0 · Source§

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached. Read more
1.0.0 · Source§

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

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer. Read more
1.0.0 · Source§

fn split(self, byte: u8) -> Split<Self>
where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte. Read more
1.0.0 · Source§

fn lines(self) -> Lines<Self>
where Self: Sized,

Returns an iterator over the lines of this reader. Read more
Source§

impl Drop for Terminal

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl Read for Terminal

Source§

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. Read more
Source§

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

Like read, except that it reads into a slice of buffers. Read more
Source§

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. Read more
1.0.0 · Source§

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. Read more
1.0.0 · Source§

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

Reads all bytes until EOF in this source, appending them to buf. Read more
1.6.0 · Source§

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

Reads the exact number of bytes required to fill buf. Read more
Source§

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. Read more
Source§

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. Read more
1.0.0 · Source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

Creates a “by reference” adaptor for this instance of Read. Read more
1.0.0 · Source§

fn bytes(self) -> Bytes<Self>
where Self: Sized,

Transforms this Read instance to an Iterator over its bytes. Read more
1.0.0 · Source§

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

Creates an adapter which will chain this stream with another. Read more
1.0.0 · Source§

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

Creates an adapter which will read at most limit bytes from it. Read more
Source§

impl Write for Terminal

Source§

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

Writes a buffer into this writer, returning how many bytes were written. Read more
Source§

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

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Source§

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

Like write, except that it writes from a slice of buffers. Read more
Source§

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. Read more
1.0.0 · Source§

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

Attempts to write an entire buffer into this writer. Read more
Source§

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. Read more
1.0.0 · Source§

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

Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0 · Source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

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

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.