[−][src]Struct cmdtree::completion::Interface
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.
Methods
impl Interface<DefaultTerminal>
[src]
pub fn new<T>(application: T) -> Result<Interface<DefaultTerminal>, Error> where
T: Into<Cow<'static, str>>,
[src]
T: Into<Cow<'static, str>>,
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.
impl<Term> Interface<Term> where
Term: Terminal,
[src]
Term: Terminal,
pub fn with_term<T>(
application: T,
term: Term
) -> Result<Interface<Term>, Error> where
T: Into<Cow<'static, str>>,
[src]
application: T,
term: Term
) -> Result<Interface<Term>, Error> where
T: Into<Cow<'static, str>>,
Creates a new Interface
instance with a particular terminal implementation.
To use the default terminal interface, call Interface::new
instead.
pub fn lock_reader(&self) -> Reader<Term>
[src]
Acquires the read lock and returns a Reader
instance.
The Reader
instance allows exclusive access to variables, bindings,
and command implementations.
pub fn lock_writer_append(&self) -> Result<Writer<Term>, Error>
[src]
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
.
pub fn lock_writer_erase(&self) -> Result<Writer<Term>, Error>
[src]
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
.
impl<Term> Interface<Term> where
Term: Terminal,
[src]
Term: Terminal,
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.
pub fn read_line(&self) -> Result<ReadResult, Error>
[src]
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
.
pub fn read_line_step(
&self,
timeout: Option<Duration>
) -> Result<Option<ReadResult>, Error>
[src]
&self,
timeout: Option<Duration>
) -> Result<Option<ReadResult>, Error>
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.
pub fn cancel_read_line(&self) -> Result<(), Error>
[src]
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.
pub fn completer(&self) -> Arc<dyn Completer<Term> + 'static>
[src]
Returns a clone of the current completer instance.
pub fn set_completer(
&self,
completer: Arc<dyn Completer<Term> + 'static>
) -> Arc<dyn Completer<Term> + 'static>
[src]
&self,
completer: Arc<dyn Completer<Term> + 'static>
) -> Arc<dyn Completer<Term> + 'static>
Replaces the current completer, returning the previous instance.
pub fn get_variable(&self, name: &str) -> Option<Variable>
[src]
Returns the value of the named variable or None
if no such variable exists.
pub fn set_variable(&self, name: &str, value: &str) -> Option<Variable>
[src]
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.
pub fn ignore_signal(&self, signal: Signal) -> bool
[src]
Returns whether the given Signal
is ignored.
pub fn set_ignore_signal(&self, signal: Signal, set: bool)
[src]
Sets whether the given Signal
will be ignored.
pub fn report_signal(&self, signal: Signal) -> bool
[src]
Returns whether the given Signal
is reported.
pub fn set_report_signal(&self, signal: Signal, set: bool)
[src]
Sets whether the given Signal
is reported.
pub fn bind_sequence<T>(&self, seq: T, cmd: Command) -> Option<Command> where
T: Into<Cow<'static, str>>,
[src]
T: Into<Cow<'static, str>>,
Binds a sequence to a command.
Returns the previously bound command.
pub fn bind_sequence_if_unbound<T>(&self, seq: T, cmd: Command) -> bool where
T: Into<Cow<'static, str>>,
[src]
T: Into<Cow<'static, str>>,
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.
pub fn unbind_sequence(&self, seq: &str) -> Option<Command>
[src]
Removes a binding for the given sequence.
Returns the previously bound command.
pub fn define_function<T>(
&self,
name: T,
cmd: Arc<dyn Function<Term> + 'static>
) -> Option<Arc<dyn Function<Term> + 'static>> where
T: Into<Cow<'static, str>>,
[src]
&self,
name: T,
cmd: Arc<dyn Function<Term> + 'static>
) -> Option<Arc<dyn Function<Term> + 'static>> where
T: Into<Cow<'static, str>>,
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.
pub fn remove_function(
&self,
name: &str
) -> Option<Arc<dyn Function<Term> + 'static>>
[src]
&self,
name: &str
) -> Option<Arc<dyn Function<Term> + 'static>>
Removes a function defined with the given name.
Returns the defined function.
pub fn evaluate_directives(&self, dirs: Vec<Directive>)
[src]
Evaluates a series of configuration directives.
pub fn evaluate_directive(&self, dir: Directive)
[src]
Evaluates a single configuration directive.
impl<Term> Interface<Term> where
Term: Terminal,
[src]
Term: Terminal,
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.
pub fn buffer(&self) -> String
[src]
Returns the current input buffer.
pub fn history_len(&self) -> usize
[src]
Returns the current number of history entries.
pub fn history_size(&self) -> usize
[src]
Returns the maximum number of history entries.
Not to be confused with history_len
, which returns the current
number of history entries.
pub fn save_history<P>(&self, path: P) -> Result<(), Error> where
P: AsRef<Path>,
[src]
P: AsRef<Path>,
Save history entries to the specified file.
pub fn load_history<P>(&self, path: P) -> Result<(), Error> where
P: AsRef<Path>,
[src]
P: AsRef<Path>,
Load history entries from the specified file.
pub fn write_fmt(&self, args: Arguments) -> Result<(), Error>
[src]
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
.
impl<Term> Interface<Term> where
Term: Terminal,
[src]
Term: Terminal,
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.
pub fn set_prompt(&self, prompt: &str) -> Result<(), Error>
[src]
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'
.
pub fn set_buffer(&self, buf: &str) -> Result<(), Error>
[src]
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.
pub fn set_cursor(&self, pos: usize) -> Result<(), Error>
[src]
Sets the cursor position in the input buffer.
Panics
If the given position is out of bounds or not on a char
boundary.
pub fn add_history(&self, line: String)
[src]
Adds a line to history.
If a read_line
call is in progress, this method has no effect.
pub fn add_history_unique(&self, line: String)
[src]
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.
pub fn clear_history(&self)
[src]
Removes all history entries.
If a read_line
call is in progress, this method has no effect.
pub fn remove_history(&self, idx: usize)
[src]
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.
pub fn set_history_size(&self, n: usize)
[src]
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.
pub fn truncate_history(&self, n: usize)
[src]
Truncates history to the only the most recent n
entries.
If a read_line
call is in progress, this method has no effect.
Auto Trait Implementations
impl<Term> Send for Interface<Term>
impl<Term> Unpin for Interface<Term> where
Term: Unpin,
Term: Unpin,
impl<Term> Sync for Interface<Term>
impl<Term> UnwindSafe for Interface<Term> where
Term: UnwindSafe,
Term: UnwindSafe,
impl<Term> RefUnwindSafe for Interface<Term> where
Term: RefUnwindSafe,
Term: RefUnwindSafe,
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,