Struct linefeed::reader::Reader

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

Interactively reads user input

Methods

impl Reader<DefaultTerminal>

pub 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>

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

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

pub fn buffer(&self) -> &str

Returns the current buffer.

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

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

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

pub fn cursor(&self) -> usize

Returns the current position of the cursor.

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

Sets the cursor to the given position within the buffer.

pub fn explicit_arg(&self) -> bool

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

pub fn sequence(&self) -> &str

Returns the current input sequence.

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

Important traits for BindingIter<'a>

impl<'a> Iterator for BindingIter<'a> type Item = (&'a str, &'a Command);

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

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

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

Removes a function defined with the given name.

Returns the defined function.

pub fn add_history(&mut self, line: String)

Adds a line to history.

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

Important traits for HistoryIter<'a>

impl<'a> Iterator for HistoryIter<'a> type Item = &'a str;

pub fn history(&self) -> HistoryIter

Returns an iterator over history entries

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

pub fn history_len(&self) -> usize

Returns the current number of history entries.

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

Removes the nth history entry

Panics

If n is out of bounds.

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

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

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

Returns a reference to the current completer instance

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

Replaces the current completer, returning the previous instance.

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

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

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

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

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

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

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

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

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

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

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

Insert a string at the current cursor position.

pub 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

pub 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

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

Evaluates a series of configuration directives.

pub fn evaluate_directive(&mut self, dir: Directive)

Evaluates a single configuration directive.

impl<Term: Terminal> Reader<Term>

Variables and other configurable parameters

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

Important traits for VariableIter<'a, Term>

impl<'a, Term: 'a + Terminal> Iterator for VariableIter<'a, Term> type Item = (&'static str, Variable<'a>);

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

Returns an iterator over stored variables.

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

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

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

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

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

pub fn set_poll_log_interval(&mut self, interval: Duration)

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

Trait Implementations