Struct linefeed::interface::Interface
[−]
[src]
pub struct Interface<Term: Terminal> { /* fields omitted */ }
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>> 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: Terminal> Interface<Term>
[src]
pub fn with_term<T>(application: T, term: Term) -> Result<Interface<Term>> where
T: Into<Cow<'static, str>>,
[src]
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(&self) -> Result<Writer<Term>>
[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.
impl<Term: Terminal> Interface<Term>
[src]
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>
[src]
Interactively reads a line from the terminal device.
If the user issues an end-of-file, ReadResult::Eof
is returned.
If a reported signal (see set_report_signal
) is received,
it is returned as ReadResult::Signal(_)
.
Otherwise, user input is collected until a newline is entered.
The resulting input (not containing a trailing newline character)
is returned as ReadResult::Input(_)
.
pub fn completer(&self) -> Arc<Completer<Term>>
[src]
Returns a clone of the current completer instance.
pub fn set_completer(
&self,
completer: Arc<Completer<Term>>
) -> Arc<Completer<Term>>
[src]
&self,
completer: Arc<Completer<Term>>
) -> Arc<Completer<Term>>
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 set_prompt(&self, prompt: &str)
[src]
Sets the prompt that will be displayed when read_line
is called.
This method internally acquires the Interface
write lock.
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 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<Function<Term>>
) -> Option<Arc<Function<Term>>> where
T: Into<Cow<'static, str>>,
[src]
&self,
name: T,
cmd: Arc<Function<Term>>
) -> Option<Arc<Function<Term>>> 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<Function<Term>>>
[src]
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: Terminal> Interface<Term>
[src]
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 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: AsRef<Path>>(&self, path: P) -> Result<()>
[src]
Save history entries to the specified file.
pub fn load_history<P: AsRef<Path>>(&self, path: P) -> Result<()>
[src]
Load history entries from the specified file.
pub fn write_fmt(&self, args: Arguments) -> Result<()>
[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.
impl<Term: Terminal> Interface<Term>
[src]
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 add_history(&self, line: String)
[src]
Adds a line to history.
pub fn add_history_unique(&self, line: String)
[src]
Adds a line to history, unless it is identical to the most recent entry.
pub fn clear_history(&self)
[src]
Removes all history entries.
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.
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.
pub fn truncate_history(&self, n: usize)
[src]
Truncates history to the only the most recent n
entries.