pub struct Interface<Term: Terminal> { /* private fields */ }
Expand description
The main interface to input reading and other terminal operations
§Concurrency
Each Interface
contains two internal locks to allow concurrent read and write
operations. The following types are used to hold a lock and to provide
access to a set of operations:
Reader
holds the read lock; it provides access to variables and bindings and can initiate aread_line
call. Whenread_line
begins, the read lock is acquired and it is held until the function returns. During theread_line
loop, theReader
waits for user input, reads input from the terminal device, then acquires the write lock to process input and run commands which may alter the prompt and the input buffer.Writer
holds the write lock; it provides an interface to write line-by-line output to the terminal device without interfering with the prompt when aread_line
may be in progress.Prompter
holds both the read and write locks; it is created by theReader
during theread_line
loop and destroyed when the write lock is released. It provides access to the current state of user input.
Implementations§
Source§impl Interface<DefaultTerminal>
impl Interface<DefaultTerminal>
Sourcepub fn new<T>(application: T) -> Result<Interface<DefaultTerminal>>
pub fn new<T>(application: T) -> Result<Interface<DefaultTerminal>>
Creates a new Interface
with the given application name.
application
is a string containing the name of the application.
This can be used in user configurations to specify behavior for
particular applications.
The default terminal interface is used.
Source§impl<Term: Terminal> Interface<Term>
impl<Term: Terminal> Interface<Term>
Sourcepub fn with_term<T>(application: T, term: Term) -> Result<Interface<Term>>
pub fn with_term<T>(application: T, term: Term) -> Result<Interface<Term>>
Creates a new Interface
instance with a particular terminal implementation.
To use the default terminal interface, call Interface::new
instead.
Sourcepub fn lock_reader(&self) -> Reader<'_, Term>
pub fn lock_reader(&self) -> Reader<'_, Term>
Acquires the read lock and returns a Reader
instance.
The Reader
instance allows exclusive access to variables, bindings,
and command implementations.
Sourcepub fn lock_writer_append(&self) -> Result<Writer<'_, '_, Term>>
pub fn lock_writer_append(&self) -> Result<Writer<'_, '_, Term>>
Acquires the write lock and returns a Writer
instance.
If a read_line
call is in progress, this method will move the cursor
to a new line after the prompt, allowing output to be written without
corrupting the prompt text. The prompt will be redrawn when the Writer
instance is dropped.
To instead erase the prompt and write text, use lock_writer_erase
.
Sourcepub fn lock_writer_erase(&self) -> Result<Writer<'_, '_, Term>>
pub fn lock_writer_erase(&self) -> Result<Writer<'_, '_, Term>>
Acquires the write lock and returns a Writer
instance.
If a read_line
call is in progress, this method will erase the prompt,
allowing output to be written without corrupting the prompt text.
The prompt will be redrawn when the Writer
instance is dropped.
To instead write text after the prompt, use lock_writer_append
.
Source§impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire the read lock.
impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire the read lock.
The lock is released before the method returns.
If the read lock is already held, e.g. because a read_line
call is in
progress, the method will block until the lock is released.
Sourcepub fn read_line(&self) -> Result<ReadResult>
pub fn read_line(&self) -> Result<ReadResult>
Interactively reads a line from the terminal device.
User input is collected until one of the following conditions is met:
- If the user issues an end-of-file,
ReadResult::Eof
is returned. - When the user inputs a newline (
'\n'
), the resulting input (not containing a trailing newline character) is returned asReadResult::Input(_)
. - When a reported signal (see
set_report_signal
) is received, it is returned asReadResult::Signal(_)
. Theread_line
operation may then be either resumed with another call toread_line
or ended by callingcancel_read_line
.
Sourcepub fn read_line_step(
&self,
timeout: Option<Duration>,
) -> Result<Option<ReadResult>>
pub fn read_line_step( &self, timeout: Option<Duration>, ) -> Result<Option<ReadResult>>
Performs one step of the interactive read_line
loop.
This method can be used to drive the read_line
process asynchronously.
It will wait for input only up to the specified duration, then process
any available input from the terminal.
If the user completes the input process, Ok(Some(result))
is returned.
Otherwise, Ok(None)
is returned to indicate that the interactive loop
may continue.
The interactive prompt may be cancelled prematurely using the
cancel_read_line
method.
See read_line
for details on the return value.
Sourcepub fn cancel_read_line(&self) -> Result<()>
pub fn cancel_read_line(&self) -> Result<()>
Cancels an in-progress read_line
operation.
This method will reset internal data structures to their original state and move the terminal cursor to a new, empty line.
This method is called to prematurely end the interactive loop when
using the read_line_step
method.
It is not necessary to call this method if using the read_line
method.
Sourcepub fn completer(&self) -> Arc<dyn Completer<Term>>
pub fn completer(&self) -> Arc<dyn Completer<Term>>
Returns a clone of the current completer instance.
Sourcepub fn set_completer(
&self,
completer: Arc<dyn Completer<Term>>,
) -> Arc<dyn Completer<Term>>
pub fn set_completer( &self, completer: Arc<dyn Completer<Term>>, ) -> Arc<dyn Completer<Term>>
Replaces the current completer, returning the previous instance.
Sourcepub fn get_variable(&self, name: &str) -> Option<Variable>
pub fn get_variable(&self, name: &str) -> Option<Variable>
Returns the value of the named variable or None
if no such variable exists.
Sourcepub fn set_variable(&self, name: &str, value: &str) -> Option<Variable>
pub fn set_variable(&self, name: &str, value: &str) -> Option<Variable>
Sets the value of the named variable and returns the previous value.
If name
does not refer to a variable or the value
is not
a valid value for the variable, None
is returned.
Sourcepub fn ignore_signal(&self, signal: Signal) -> bool
pub fn ignore_signal(&self, signal: Signal) -> bool
Returns whether the given Signal
is ignored.
Sourcepub fn set_ignore_signal(&self, signal: Signal, set: bool)
pub fn set_ignore_signal(&self, signal: Signal, set: bool)
Sets whether the given Signal
will be ignored.
Sourcepub fn report_signal(&self, signal: Signal) -> bool
pub fn report_signal(&self, signal: Signal) -> bool
Returns whether the given Signal
is reported.
Sourcepub fn set_report_signal(&self, signal: Signal, set: bool)
pub fn set_report_signal(&self, signal: Signal, set: bool)
Sets whether the given Signal
is reported.
Sourcepub fn bind_sequence<T>(&self, seq: T, cmd: Command) -> Option<Command>
pub fn bind_sequence<T>(&self, seq: T, cmd: Command) -> Option<Command>
Binds a sequence to a command.
Returns the previously bound command.
Sourcepub fn bind_sequence_if_unbound<T>(&self, seq: T, cmd: Command) -> bool
pub fn bind_sequence_if_unbound<T>(&self, seq: T, cmd: Command) -> bool
Binds a sequence to a command, if and only if the given sequence is not already bound to a command.
Returns true
if a new binding was created.
Sourcepub fn unbind_sequence(&self, seq: &str) -> Option<Command>
pub fn unbind_sequence(&self, seq: &str) -> Option<Command>
Removes a binding for the given sequence.
Returns the previously bound command.
Sourcepub fn define_function<T>(
&self,
name: T,
cmd: Arc<dyn Function<Term>>,
) -> Option<Arc<dyn Function<Term>>>
pub fn define_function<T>( &self, name: T, cmd: Arc<dyn Function<Term>>, ) -> Option<Arc<dyn Function<Term>>>
Defines a named function to which sequences may be bound.
The name should consist of lowercase ASCII letters and numbers, containing no spaces, with words separated by hyphens. However, this is not a requirement.
Returns the function previously defined with the same name.
Sourcepub fn remove_function(&self, name: &str) -> Option<Arc<dyn Function<Term>>>
pub fn remove_function(&self, name: &str) -> Option<Arc<dyn Function<Term>>>
Removes a function defined with the given name.
Returns the defined function.
Sourcepub fn evaluate_directives(&self, dirs: Vec<Directive>)
pub fn evaluate_directives(&self, dirs: Vec<Directive>)
Evaluates a series of configuration directives.
Sourcepub fn evaluate_directive(&self, dir: Directive)
pub fn evaluate_directive(&self, dir: Directive)
Evaluates a single configuration directive.
Source§impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire the write lock.
impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire the write lock.
The lock is released before the method returns.
If the write lock is already held, the method will block until it is released.
Sourcepub fn history_len(&self) -> usize
pub fn history_len(&self) -> usize
Returns the current number of history entries.
Sourcepub fn history_size(&self) -> usize
pub fn history_size(&self) -> usize
Returns the maximum number of history entries.
Not to be confused with history_len
, which returns the current
number of history entries.
Sourcepub fn save_history<P: AsRef<Path>>(&self, path: P) -> Result<()>
pub fn save_history<P: AsRef<Path>>(&self, path: P) -> Result<()>
Save history entries to the specified file.
Sourcepub fn load_history<P: AsRef<Path>>(&self, path: P) -> Result<()>
pub fn load_history<P: AsRef<Path>>(&self, path: P) -> Result<()>
Load history entries from the specified file.
Sourcepub fn write_fmt(&self, args: Arguments<'_>) -> Result<()>
pub fn write_fmt(&self, args: Arguments<'_>) -> Result<()>
Writes formatted text to the terminal display.
This method enables Interface
to be used as the receiver to
the writeln!
macro.
If the text contains any unprintable characters (e.g. escape sequences), those characters will be escaped before printing.
§Notes
If this method is called during a read_line
call, the prompt will
first be erased, then restored after the given string is printed.
Therefore, the written text should end with a newline. If the writeln!
macro is used, a newline is automatically added to the end of the text.
To instead write text after the prompt, use lock_writer_append
.
Source§impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire both the read and write locks.
impl<Term: Terminal> Interface<Term>
§Locking
The following methods internally acquire both the read and write locks.
The locks are released before the method returns.
If either lock is already held, the method will block until it is released.
Sourcepub fn set_prompt(&self, prompt: &str) -> Result<()>
pub fn set_prompt(&self, prompt: &str) -> Result<()>
Sets the prompt that will be displayed when read_line
is called.
§Notes
If prompt
contains any terminal escape sequences (e.g. color codes),
such escape sequences should be immediately preceded by the character
'\x01'
and immediately followed by the character '\x02'
.
Sourcepub fn set_buffer(&self, buf: &str) -> Result<()>
pub fn set_buffer(&self, buf: &str) -> Result<()>
Sets the input buffer to the given string.
§Notes
To prevent invalidating the cursor, this method sets the cursor position to the end of the new buffer.
Sourcepub fn set_cursor(&self, pos: usize) -> Result<()>
pub fn set_cursor(&self, pos: usize) -> Result<()>
Sets the cursor position in the input buffer.
§Panics
If the given position is out of bounds or not on a char
boundary.
Sourcepub fn add_history(&self, line: String)
pub fn add_history(&self, line: String)
Adds a line to history.
If a read_line
call is in progress, this method has no effect.
Sourcepub fn add_history_unique(&self, line: String)
pub fn add_history_unique(&self, line: String)
Adds a line to history, unless it is identical to the most recent entry.
If a read_line
call is in progress, this method has no effect.
Sourcepub fn clear_history(&self)
pub fn clear_history(&self)
Removes all history entries.
If a read_line
call is in progress, this method has no effect.
Sourcepub fn remove_history(&self, idx: usize)
pub fn remove_history(&self, idx: usize)
Removes the history entry at the given index.
If the index is out of bounds, this method has no effect.
If a read_line
call is in progress, this method has no effect.
Sourcepub fn set_history_size(&self, n: usize)
pub fn set_history_size(&self, n: usize)
Sets the maximum number of history entries.
If n
is less than the current number of history entries,
the oldest entries are truncated to meet the given requirement.
If a read_line
call is in progress, this method has no effect.
Sourcepub fn truncate_history(&self, n: usize)
pub fn truncate_history(&self, n: usize)
Truncates history to the only the most recent n
entries.
If a read_line
call is in progress, this method has no effect.