Struct linefeed::reader::Reader

pub struct Reader<Term: Terminal> { /* fields omitted */ }

Interactively reads user input

Methods

impl Reader<DefaultTerminal>

fn new<T>(application: T) -> Result<Reader<DefaultTerminal>> where
    T: Into<Cow<'static, str>>, 

Creates a new Reader 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 platform-dependent default terminal interface is used.

impl<Term: Terminal> Reader<Term>

fn with_term<T>(application: T, term: Term) -> Result<Reader<Term>> where
    T: Into<Cow<'static, str>>, 

Creates a new Reader instance with a particular terminal implementation.

To use the platform-dependent default terminal interface, call Reader::new instead.

fn read_line(&mut self) -> Result<ReadResult>

Interactively reads a line from stdin.

If end-of-file occurs, returns ReadResult::Eof.

If a reported signal (see set_report_signal) is received, it is returned as ReadResult::Signal(_).

Otherwise, user input is returned as ReadResult::Input(_).

fn buffer(&self) -> &str

Returns the current buffer.

fn backup_buffer(&self) -> &str

Returns the "backup" buffer.

When the user is currently editing a history entry, the backup buffer contains the original user input.

fn last_command_category(&self) -> Category

Returns the command Category of the most recently executed command.

Some commands may use this to influence behavior of repeated commands.

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

Sets the buffer to the given value. The cursor is moved to the end of the buffer.

fn cursor(&self) -> usize

Returns the current position of the cursor.

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

Sets the cursor to the given position within the buffer.

fn explicit_arg(&self) -> bool

Returns whether a numerical argument was explicitly supplied by the user.

fn sequence(&self) -> &str

Returns the current input sequence.

fn set_prompt(&mut self, prompt: &str)

Sets the prompt that will be displayed when read_line is called.

Note

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'.

fn bindings(&self) -> BindingIter

Returns an iterator over bound sequences

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.

fn bind_sequence_if_unbound<T>(&mut self, seq: T, cmd: Command) -> bool where
    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.

fn unbind_sequence(&mut self, seq: &str) -> Option<Command>

Removes a binding for the given sequence.

Returns the previously bound command.

fn define_function<T>(
    &mut self,
    name: T,
    cmd: Rc<Function<Term>>
) -> Option<Rc<Function<Term>>> where
    T: Into<Cow<'static, str>>, 

Defines a named function to which sequences may be bound.

The name should contain no spaces, with words separated by hyphens, and all lowercase.

Returns the function previously defined with the same name.

fn remove_function(&mut self, name: &str) -> Option<Rc<Function<Term>>>

Removes a function defined with the given name.

Returns the defined function.

fn add_history(&mut self, line: String)

Adds a line to history.

If the maximum size is reached, the oldest entry is removed.

fn history(&self) -> HistoryIter

Returns an iterator over history entries

fn history_index(&self) -> Option<usize>

Returns the index into history currently being edited.

If the user is not editing a line of history, None is returned.

fn history_len(&self) -> usize

Returns the current number of history entries.

fn remove_history(&mut self, n: usize)

Removes the nth history entry

Panics

If n is out of bounds.

fn truncate_history(&mut self, n: usize)

Truncates history to the most recent n entries.

If there are fewer than n entries in history, this has no effect.

fn select_history_entry(&mut self, new: Option<usize>) -> Result<()>

Selects the history entry currently being edited by the user.

Setting the entry to None will result in editing the input buffer.

fn completer(&self) -> &Rc<Completer<Term>>

Returns a reference to the current completer instance

fn set_completer(
    &mut self,
    completer: Rc<Completer<Term>>
) -> Rc<Completer<Term>>

Replaces the current completer, returning the previous instance.

fn completions(&self) -> Option<&[Completion]>

Returns the current set of completions.

The result is only not None when the most recent command executed was one operating on completion sets.

fn set_completions(&mut self, completions: Option<Vec<Completion>>)

Sets the current set of completions.

This completion set is accessed by commands such as complete and possible-completions.

This set will only remain active until the end of the next non-completion command's execution. Therefore, any Function that uses this method must be of the Complete category.

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

Moves the cursor to the given position, waits for BLINK_TIMEOUT_MS (or until next user input), then restores the original cursor position.

fn delete_range<R: RangeArgument<usize>>(&mut self, range: R) -> Result<()>

Deletes a range from the buffer; the cursor is moved to the end of the given range.

fn kill_range<R: RangeArgument<usize>>(&mut self, range: R) -> Result<()>

Deletes a range from the buffer and adds the removed text to the kill ring.

fn transpose_range(
    &mut self,
    src: Range<usize>,
    dest: Range<usize>
) -> Result<()>

Transposes two regions of the buffer, src and dest. The cursor is placed at the end of the new location of src.

Panics

If src and dest overlap.

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

Insert text from the front of the kill ring at the current cursor position. The cursor is placed at the end of the new text.

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

Rotates the kill ring and replaces yanked text with the new front.

If the previous operation was not yank, this has no effect.

fn insert(&mut self, n: usize, ch: char) -> Result<()>

Insert a given character at the current cursor position n times.

fn insert_str(&mut self, s: &str) -> Result<()>

Insert a string at the current cursor position.

fn replace_str_backward<R: RangeArgument<usize>>(
    &mut self,
    range: R,
    s: &str
) -> Result<()>

Replaces a range in the buffer and redraws. Cursor is placed at the start of the range

fn replace_str_forward<R: RangeArgument<usize>>(
    &mut self,
    range: R,
    s: &str
) -> Result<()>

Replaces a range in the buffer and redraws. Cursor is placed at the end of the new string

fn evaluate_directives(&mut self, dirs: Vec<Directive>)

Evaluates a series of configuration directives.

fn evaluate_directive(&mut self, dir: Directive)

Evaluates a single configuration directive.

impl<Term: Terminal> Reader<Term>

Variables and other configurable parameters

fn application(&self) -> &str

Returns the application name

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

Sets the application name

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

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

fn set_variable(&mut self, name: &str, value: &str) -> Option<Variable<'static>>

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.

fn variables(&self) -> VariableIter<Term>

Returns an iterator over stored variables.

fn history_size(&self) -> usize

Returns the maximum number of history entries.

Note

Not to be confused with history_len which returns the current number of stored history entries.

fn set_history_size(&mut self, n: usize)

Sets the maximum number of history entries. If n is less than the current number of history entries, history will be truncated to the most recent n entries.

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.

fn set_blink_matching_paren(&mut self, set: bool)

Sets the blink-matching-paren variable.

fn catch_signals(&self) -> bool

Returns whether linefeed will catch certain signals.

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.

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

Returns whether the given Signal is ignored.

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

Sets whether the given Signal will be ignored.

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

Returns whether the given Signal is to be reported.

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 Reader::read_line as Ok(Signal(signal)).

fn disable_completion(&self) -> bool

Returns whether Tab completion is disabled.

The default value is false.

fn set_disable_completion(&mut self, disable: bool)

Sets the disable-completion variable.

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.

fn set_echo_control_characters(&mut self, echo: bool)

Sets the echo-control-characters variable.

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

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

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

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

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().

fn set_completion_display_width(&mut self, n: usize)

Sets the completion-display-width variable.

fn completion_query_items(&self) -> usize

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

The default value is 100.

fn set_completion_query_items(&mut self, n: usize)

Sets the completion-query-items variable.

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 is equal to KEYSEQ_TIMEOUT_MS.

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

Sets the keyseq-timeout variable.

fn page_completions(&self) -> bool

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

The default value is true.

fn set_page_completions(&mut self, set: bool)

Sets the page-completions variable.

fn print_completions_horizontally(&self) -> bool

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

The default value is false.

fn set_print_completions_horizontally(&mut self, set: bool)

Sets the print-completions-horizontally variable.

fn string_chars(&self) -> &str

Returns the set of characters that delimit strings.

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

Sets the set of characters that delimit strings.

fn word_break_chars(&self) -> &str

Returns the set of characters that indicate a word break.

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.

fn get_log_sender(&mut self) -> LogSender

Creaes a sender object that allows other threads to log messages while a prompt is open, without causing display errors. The Reader handles checking the buffer, so unless read_line or a similar function is running in the Reader, the messages sent will not be printed.

fn poll_log_interval(&self) -> Duration

Returns the interval at which Reader checks for log messages while waiting for user input.

The default value is POLL_LOG_INTERVAL_MS milliseconds.

fn set_poll_log_interval(&mut self, interval: Duration)

Sets the interval at which Reader checks for log messages while waiting for user input.