Struct reedline::Reedline

pub struct Reedline { /* private fields */ }

Line editor engine

Example usage

use reedline::{Reedline, Signal, DefaultPrompt};
let mut line_editor = Reedline::create();
let prompt = DefaultPrompt::default();

let out = line_editor.read_line(&prompt).unwrap();
match out {
   Signal::Success(content) => {
       // process content
   }
   _ => {
       eprintln!("Entry aborted!");

   }
}

Implementations

impl Reedline

pub fn create() -> Self

Create a new Reedline engine with a local History that is not synchronized to a file.

pub fn create_history_session_id() -> Option<HistorySessionId>

Get a new history session id based on the current time and the first commit datetime of reedline

pub fn use_bracketed_paste(self, enable: bool) -> Self

Toggle whether reedline enables bracketed paste to reed copied content

This currently alters the behavior for multiline pastes as pasting of regular text will execute after every complete new line as determined by the Validator. With enabled bracketed paste all lines will appear in the buffer and can then be submitted with a separate enter.

At this point most terminals should support it or ignore the setting of the necessary flags. For full compatibility, keep it disabled.

pub fn use_kitty_keyboard_enhancement(self, enable: bool) -> Self

Toggle whether reedline uses the kitty keyboard enhancement protocol

This allows us to disambiguate more events than the traditional standard Only available with a few terminal emulators. You can check for that with crate::kitty_protocol_available Reedline will perform this check internally

Read more: https://sw.kovidgoyal.net/kitty/keyboard-protocol/

pub fn get_history_session_id(&self) -> Option<HistorySessionId>

Return the previously generated history session id

pub fn set_history_session_id( &mut self, session: Option<HistorySessionId> ) -> Result<()>

Set a new history session id This should be used in situations where the user initially did not have a history_session_id and then later realized they want to have one without restarting the application.

pub fn with_hinter(self, hinter: Box<dyn Hinter>) -> Self

A builder to include a Hinter in your instance of the Reedline engine

Example

//Cargo.toml
//[dependencies]
//nu-ansi-term = "*"
use {
    nu_ansi_term::{Color, Style},
    reedline::{DefaultHinter, Reedline},
};

let mut line_editor = Reedline::create().with_hinter(Box::new(
    DefaultHinter::default()
    .with_style(Style::new().italic().fg(Color::LightGray)),
));

pub fn disable_hints(self) -> Self

Remove current Hinter

pub fn with_completer(self, completer: Box<dyn Completer>) -> Self

A builder to configure the tab completion

Example

// Create a reedline object with tab completions support

use reedline::{DefaultCompleter, Reedline};

let commands = vec![
  "test".into(),
  "hello world".into(),
  "hello world reedline".into(),
  "this is the reedline crate".into(),
];
let completer = Box::new(DefaultCompleter::new_with_wordlen(commands.clone(), 2));

let mut line_editor = Reedline::create().with_completer(completer);

pub fn with_quick_completions(self, quick_completions: bool) -> Self

Turn on quick completions. These completions will auto-select if the completer ever narrows down to a single entry.

pub fn with_partial_completions(self, partial_completions: bool) -> Self

Turn on partial completions. These completions will fill the buffer with the smallest common string from all the options

pub fn with_ansi_colors(self, use_ansi_coloring: bool) -> Self

A builder which enables or disables the use of ansi coloring in the prompt and in the command line syntax highlighting.

pub fn with_highlighter(self, highlighter: Box<dyn Highlighter>) -> Self

A builder that configures the highlighter for your instance of the Reedline engine

Example

// Create a reedline object with highlighter support

use reedline::{ExampleHighlighter, Reedline};

let commands = vec![
  "test".into(),
  "hello world".into(),
  "hello world reedline".into(),
  "this is the reedline crate".into(),
];
let mut line_editor =
Reedline::create().with_highlighter(Box::new(ExampleHighlighter::new(commands)));

pub fn with_visual_selection_style(self, style: Style) -> Self

A builder that configures the style used for visual selection

pub fn with_history(self, history: Box<dyn History>) -> Self

A builder which configures the history for your instance of the Reedline engine

Example

// Create a reedline object with history support, including history size limits

use reedline::{FileBackedHistory, Reedline};

let history = Box::new(
FileBackedHistory::with_file(5, "history.txt".into())
    .expect("Error configuring history with file"),
);
let mut line_editor = Reedline::create()
    .with_history(history);

pub fn with_history_exclusion_prefix( self, ignore_prefix: Option<String> ) -> Self

A builder which configures history exclusion for your instance of the Reedline engine

Example

// Create a reedline instance with history that will *not* include commands starting with a space

use reedline::{FileBackedHistory, Reedline};

let history = Box::new(
FileBackedHistory::with_file(5, "history.txt".into())
    .expect("Error configuring history with file"),
);
let mut line_editor = Reedline::create()
    .with_history(history)
    .with_history_exclusion_prefix(Some(" ".into()));

pub fn with_validator(self, validator: Box<dyn Validator>) -> Self

A builder that configures the validator for your instance of the Reedline engine

Example

// Create a reedline object with validator support

use reedline::{DefaultValidator, Reedline};

let mut line_editor =
Reedline::create().with_validator(Box::new(DefaultValidator));

pub fn with_buffer_editor(self, editor: Command, temp_file: PathBuf) -> Self

A builder that configures the alternate text editor used to edit the line buffer

You are responsible for providing a file path that is unique to this reedline session

Example

// Create a reedline object with vim as editor

use reedline::Reedline;
use std::env::temp_dir;
use std::process::Command;

let temp_file = std::env::temp_dir().join("my-random-unique.file");
let mut command = Command::new("vim");
// you can provide additional flags:
command.arg("-p"); // open in a vim tab (just for demonstration)
// you don't have to pass the filename to the command
let mut line_editor =
Reedline::create().with_buffer_editor(command, temp_file);

pub fn disable_validator(self) -> Self

Remove the current Validator

pub fn with_transient_prompt(self, transient_prompt: Box<dyn Prompt>) -> Self

Set a different prompt to be used after submitting each line

pub fn with_edit_mode(self, edit_mode: Box<dyn EditMode>) -> Self

A builder which configures the edit mode for your instance of the Reedline engine

pub fn with_menu(self, menu: ReedlineMenu) -> Self

A builder that appends a menu to the engine

pub fn clear_menus(self) -> Self

A builder that clears the list of menus added to the engine

pub fn with_history_session_id(self, session: Option<HistorySessionId>) -> Self

A builder that adds the history item id

pub fn with_cursor_config(self, cursor_shapes: CursorConfig) -> Self

A builder that enables reedline changing the cursor shape based on the current edit mode. The current implementation sets the cursor shape when drawing the prompt. Do not use this if the cursor shape is set elsewhere, e.g. in the terminal settings or by ansi escape sequences.

pub fn prompt_edit_mode(&self) -> PromptEditMode

Returns the corresponding expected prompt style for the given edit mode

pub fn print_history(&mut self) -> Result<()>

Output the complete History chronologically with numbering to the terminal

pub fn print_history_session(&mut self) -> Result<()>

Output the complete History for this session, chronologically with numbering to the terminal

pub fn print_history_session_id(&mut self) -> Result<()>

Print the history session id

pub fn toggle_history_session_matching( &mut self, session: Option<HistorySessionId> ) -> Result<()>

Toggle between having a history that uses the history session id and one that does not

pub fn history(&self) -> &dyn History

Read-only view of the history

pub fn history_mut(&mut self) -> &mut dyn History

Mutable view of the history

pub fn sync_history(&mut self) -> Result<()>

Update the underlying History to/from disk

pub fn has_last_command_context(&self) -> bool

Check if any commands have been run.

When no commands have been run, calling Self::update_last_command_context does not make sense and is guaranteed to fail with a “No command run” error.

pub fn update_last_command_context( &mut self, f: &dyn Fn(HistoryItem) -> HistoryItem ) -> Result<()>

update the last history item with more information

pub fn read_line(&mut self, prompt: &dyn Prompt) -> Result<Signal>

Wait for input and provide the user with a specified Prompt.

Returns a std::io::Result in which the Err type is std::io::Result and the Ok variant wraps a Signal which handles user inputs.

pub fn current_insertion_point(&self) -> usize

Returns the current insertion point of the input buffer.

pub fn current_buffer_contents(&self) -> &str

Returns the current contents of the input buffer.

pub fn clear_screen(&mut self) -> Result<()>

Clear the screen by printing enough whitespace to start the prompt or other output back at the first line of the terminal.

pub fn clear_scrollback(&mut self) -> Result<()>

Clear the screen and the scrollback buffer of the terminal

pub fn run_edit_commands(&mut self, commands: &[EditCommand])

Executes EditCommand actions by modifying the internal state appropriately. Does not output itself.

pub fn with_external_printer(self, printer: ExternalPrinter<String>) -> Self

Adds an external printer

Required feature:

external_printer

Trait Implementations

impl Drop for Reedline

fn drop(&mut self)

Executes the destructor for this type.