Struct linefeed::reader::Reader

pub struct Reader<'a, Term: 'a + Terminal> { /* private fields */ }

Provides access to data related to reading and processing user input.

Holds a lock on terminal read operations. See Interface for more information about concurrent operations.

An instance of this type can be constructed using the Interface::lock_reader method.

Implementations

impl<'a, Term: 'a + Terminal> Reader<'a, Term>

pub fn read_line(&mut 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 as ReadResult::Input(_).
• When a reported signal (see set_report_signal) is received, it is returned as ReadResult::Signal(_). The read_line operation may then be either resumed with another call to read_line or ended by calling cancel_read_line.

pub fn read_line_step(
    &mut 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.

pub fn cancel_read_line(&mut 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.

pub fn set_buffer(&mut self, buf: &str) -> Result<()>

Sets the input buffer to the given string.

This method internally acquires the Interface write lock.

Notes

To prevent invalidating the cursor, this method sets the cursor position to the end of the new buffer.

pub fn set_cursor(&mut self, pos: usize) -> Result<()>

Sets the cursor position in the input buffer.

This method internally acquires the Interface write lock.

Panics

If the given position is out of bounds or not on a char boundary.

pub fn set_prompt(&mut self, prompt: &str) -> Result<()>

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 add_history(&self, line: String)

Adds a line to history.

This method internally acquires the Interface write lock.

If a read_line call is in progress, this method has no effect.

pub fn add_history_unique(&self, line: String)

Adds a line to history, unless it is identical to the most recent entry.

This method internally acquires the Interface write lock.

If a read_line call is in progress, this method has no effect.

pub fn clear_history(&self)

Removes all history entries.

This method internally acquires the Interface write lock.

If a read_line call is in progress, this method has no effect.

pub fn remove_history(&self, idx: usize)

Removes the history entry at the given index.

This method internally acquires the Interface write lock.

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)

Sets the maximum number of history entries.

This method internally acquires the Interface write lock.

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)

Truncates history to the only the most recent n entries.

This method internally acquires the Interface write lock.

If a read_line call is in progress, this method has no effect.

pub fn application(&self) -> &str

Returns the application name

pub fn set_application<T>(&mut self, application: T)where
    T: Into<Cow<'static, str>>,

Sets the application name

pub fn completer(&self) -> &Arc<dyn Completer<Term>>

Returns a reference to the current completer instance.

pub fn set_completer(
    &mut self,
    completer: Arc<dyn Completer<Term>>
) -> Arc<dyn Completer<Term>>

Replaces the current completer, returning the previous instance.

pub fn get_variable(&self, name: &str) -> Option<Variable>

Returns the value of the named variable or None if no such variable exists.

pub fn set_variable(&mut 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.

pub fn variables(&self) -> VariableIter<'_>

Returns an iterator over stored variables.

pub fn blink_matching_paren(&self) -> bool

Returns whether to “blink” matching opening parenthesis character when a closing parenthesis character is entered.

The default value is false.

pub fn set_blink_matching_paren(&mut self, set: bool)

Sets the blink-matching-paren variable.

pub fn catch_signals(&self) -> bool

Returns whether linefeed will catch certain signals.

pub fn set_catch_signals(&mut self, enabled: bool)

Sets whether linefeed will catch certain signals.

This setting is true by default. It can be disabled to allow the host program to handle signals itself.

pub fn ignore_signal(&self, signal: Signal) -> bool

Returns whether the given Signal is ignored.

pub fn set_ignore_signal(&mut self, signal: Signal, set: bool)

Sets whether the given Signal will be ignored.

pub fn report_signal(&self, signal: Signal) -> bool

Returns whether the given Signal is to be reported.

pub fn set_report_signal(&mut self, signal: Signal, set: bool)

Sets whether to report the given Signal.

When a reported signal is received via the terminal, it will be returned from Interface::read_line as Ok(Signal(signal)).

pub fn disable_completion(&self) -> bool

Returns whether Tab completion is disabled.

The default value is false.

pub fn set_disable_completion(&mut self, disable: bool)

Sets the disable-completion variable.

pub fn echo_control_characters(&self) -> bool

When certain control characters are pressed, a character sequence equivalent to this character will be echoed.

The default value is true.

pub fn set_echo_control_characters(&mut self, echo: bool)

Sets the echo-control-characters variable.

pub fn completion_append_character(&self) -> Option<char>

Returns the character, if any, that is appended to a successful completion.

pub fn set_completion_append_character(&mut self, ch: Option<char>)

Sets the character, if any, that is appended to a successful completion.

pub fn completion_display_width(&self) -> usize

Returns the width of completion listing display.

If this value is greater than the terminal width, terminal width is used instead.

The default value is equal to usize::max_value().

pub fn set_completion_display_width(&mut self, n: usize)

Sets the completion-display-width variable.

pub fn completion_query_items(&self) -> usize

Returns the minimum number of completion items that require user confirmation before listing.

The default value is 100.

pub fn set_completion_query_items(&mut self, n: usize)

Sets the completion-query-items variable.

pub fn keyseq_timeout(&self) -> Option<Duration>

Returns the timeout to wait for further user input when an ambiguous sequence has been entered. If the value is None, wait is indefinite.

The default value 500 milliseconds.

pub fn set_keyseq_timeout(&mut self, timeout: Option<Duration>)

Sets the keyseq-timeout variable.

pub fn page_completions(&self) -> bool

Returns whether to list possible completions one page at a time.

The default value is true.

pub fn set_page_completions(&mut self, set: bool)

Sets the page-completions variable.

pub fn print_completions_horizontally(&self) -> bool

Returns whether to list completions horizontally, rather than down the screen.

The default value is false.

pub fn set_print_completions_horizontally(&mut self, set: bool)

Sets the print-completions-horizontally variable.

pub fn string_chars(&self) -> &str

Returns the set of characters that delimit strings.

pub fn set_string_chars<T>(&mut self, chars: T)where
    T: Into<Cow<'static, str>>,

Sets the set of characters that delimit strings.

pub fn word_break_chars(&self) -> &str

Returns the set of characters that indicate a word break.

pub fn set_word_break_chars<T>(&mut self, chars: T)where
    T: Into<Cow<'static, str>>,

Sets the set of characters that indicate a word break.

pub fn bindings(&self) -> BindingIter<'_>

Returns an iterator over bound sequences

pub fn bind_sequence<T>(&mut self, seq: T, cmd: Command) -> Option<Command>where
    T: Into<Cow<'static, str>>,

Binds a sequence to a command.

Returns the previously bound command.

pub fn bind_sequence_if_unbound<T>(&mut self, seq: T, cmd: Command) -> boolwhere
    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(&mut self, seq: &str) -> Option<Command>

Removes a binding for the given sequence.

Returns the previously bound command.

pub fn define_function<T>(
    &mut self,
    name: T,
    cmd: Arc<dyn Function<Term>>
) -> Option<Arc<dyn 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(&mut self, name: &str) -> Option<Arc<dyn Function<Term>>>

Removes a function defined with the given name.

Returns the defined function.