No support to overwrite keybindings.

A feature-rich line editor - powering Nushell

Introduction

Reedline is a project to create a line editor (like bash's readline or zsh's zle) that supports many of the modern conveniences of CLIs, including syntax highlighting, completions, multiline support, Unicode support, and more. It is currently primarily developed as the interactive editor for nushell (starting with v0.60) striving to provide a pleasant interactive experience.

Examples

For the full documentation visit https://docs.rs/reedline. The examples should highlight how you enable the most important features or which traits can be implemented for language-specific behavior.

Basic example

// Create a default reedline object to handle user input

use reedline::{DefaultPrompt, Reedline, Signal};

let mut line_editor = Reedline::create();
let prompt = DefaultPrompt::default();

loop {
    let sig = line_editor.read_line(&prompt);
    match sig {
        Ok(Signal::Success(buffer)) => {
            println!("We processed: {}", buffer);
        }
        Ok(Signal::CtrlD) | Ok(Signal::CtrlC) => {
            println!("\nAborted!");
            break;
        }
        x => {
            println!("Event: {:?}", x);
        }
    }
}

Integrate with custom keybindings

// Configure reedline with custom keybindings

//Cargo.toml
//    [dependencies]
//    crossterm = "*"

use {
  crossterm::event::{KeyCode, KeyModifiers},
  reedline::{default_emacs_keybindings, EditCommand, Reedline, Emacs, ReedlineEvent},
};

let mut keybindings = default_emacs_keybindings();
keybindings.add_binding(
    KeyModifiers::ALT,
    KeyCode::Char('m'),
    ReedlineEvent::Edit(vec![EditCommand::BackspaceWord]),
);
let edit_mode = Box::new(Emacs::new(keybindings));

let mut line_editor = Reedline::create().with_edit_mode(edit_mode);

Integrate with `History`

// 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);

Integrate with custom syntax `Highlighter`

// 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)));

Integrate with custom tab completion

// Create a reedline object with tab completions support

use reedline::{default_emacs_keybindings, ColumnarMenu, DefaultCompleter, Emacs, KeyCode, KeyModifiers, Reedline, ReedlineEvent, ReedlineMenu};

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));
// Use the interactive menu to select options from the completer
let completion_menu = Box::new(ColumnarMenu::default().with_name("completion_menu"));
// Set up the required keybindings
let mut keybindings = default_emacs_keybindings();
keybindings.add_binding(
    KeyModifiers::NONE,
    KeyCode::Tab,
    ReedlineEvent::UntilFound(vec![
        ReedlineEvent::Menu("completion_menu".to_string()),
        ReedlineEvent::MenuNext,
    ]),
);

let edit_mode = Box::new(Emacs::new(keybindings));

let mut line_editor = Reedline::create()
    .with_completer(completer)
    .with_menu(ReedlineMenu::EngineCompleter(completion_menu))
    .with_edit_mode(edit_mode);

Integrate with `Hinter` for fish-style history autosuggestions

// Create a reedline object with in-line hint support

//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)),
));

Integrate with custom line completion `Validator`

// Create a reedline object with line completion validation support

use reedline::{DefaultValidator, Reedline};

let validator = Box::new(DefaultValidator);

let mut line_editor = Reedline::create().with_validator(validator);

Use custom `EditMode`

// Create a reedline object with custom edit mode
// This can define a keybinding setting or enable vi-emulation

use reedline::{
    default_vi_insert_keybindings, default_vi_normal_keybindings, EditMode, Reedline, Vi,
};

let mut line_editor = Reedline::create().with_edit_mode(Box::new(Vi::new(
    default_vi_insert_keybindings(),
    default_vi_normal_keybindings(),
)));

Crate features

clipboard: Enable support to use the SystemClipboard. Enabling this feature will return a SystemClipboard instead of a local clipboard when calling get_default_clipboard().
bashisms: Enable support for special text sequences that recall components from the history. e.g. !! and !$. For use in shells like bash or nushell.
sqlite: Provides the SqliteBackedHistory to store richer information in the history. Statically links the required sqlite version.
sqlite-dynlib: Alternative to the feature sqlite. Will not statically link. Requires sqlite >= 3.38 to link dynamically!
external_printer: Experimental: Thread-safe ExternalPrinter handle to print lines from concurrently running threads.

Are we prompt yet? (Development status)

Reedline has now all the basic features to become the primary line editor for nushell

General editing functionality, that should feel familiar coming from other shells (e.g. bash, fish, zsh).
Configurable keybindings (emacs-style bindings and basic vi-style).
Configurable prompt
Content-aware syntax highlighting.
Autocompletion (With graphical selection menu or simple cycling inline).
History with interactive search options (optionally persists to file, can support multiple sessions accessing the same file)
Fish-style history autosuggestion hints
Undo support.
Clipboard integration
Line completeness validation for seamless entry of multiline command sequences.

Areas for future improvements

Support for Unicode beyond simple left-to-right scripts
Easier keybinding configuration
Support for more advanced vi commands
Visual selection
Smooth experience if completion or prompt content takes long to compute
Support for a concurrent output stream from background tasks to be displayed, while the input prompt is active. ("Full duplex" mode)

For more ideas check out the feature discussion or hop on the #reedline channel of the nushell discord.

Development history

If you want to follow along with the history of how reedline got started, you can watch the recordings of JT's live-coding streams.

Playlist: Creating a line editor in Rust

Alternatives

For currently more mature Rust line editing check out:

rustyline

	// Performing mutation here might incur a perf hit down this line when
	// we would like to do multiple inserts.
	// A simple solution that we can do is to queue up these and perform the wrapping
	// check after the loop finishes. Will need to sort out the details.
	EditCommand::InsertChar(c) => {
	self.editor.insert_char(*c);

	if self.require_wrapping() {
	let position = cursor::position()?;
	self.wrap(position)?;
	}

	self.editor.remember_undo_state(false);

	self.repaint(prompt)?;
	}

	if [
	EditCommand::MoveToEnd,
	EditCommand::MoveToStart,
	EditCommand::MoveLeft,
	EditCommand::MoveRight,
	EditCommand::MoveWordLeft,
	EditCommand::MoveWordRight,
	EditCommand::Backspace,
	EditCommand::Delete,
	EditCommand::BackspaceWord,
	EditCommand::DeleteWord,
	EditCommand::CutFromStart,
	EditCommand::CutToEnd,
	EditCommand::CutWordLeft,
	EditCommand::CutWordRight,
	]
	.contains(command)
	{
	self.editor.remember_undo_state(true);
	}

	if self.edits.len() > 1
	&& self.edits.last()?.word_count() == self.line_buffer.word_count()
	&& !is_after_action
	{
	self.edits.pop();
	}

	pub struct Editor {
	line_buffer: LineBuffer,
	cut_buffer: Box<dyn Clipboard>,

	edits: Vec<LineBuffer>,
	index_undo: usize,
	}

	pub fn reset_undo_stack(&mut self) {
	self.edits = vec![LineBuffer::new()];
	self.index_undo = 2;
	}

	fn get_index_undo(&self) -> usize {
	if let Some(c) = self.edits.len().checked_sub(self.index_undo) {
	c
	} else {
	0
	}
	}

	pub fn undo(&mut self) {
	// NOTE: Try-blocks should help us get rid of this indirection too
	self.undo_internal();
	}

	pub fn redo(&mut self) {
	// NOTE: Try-blocks should help us get rid of this indirection too
	self.redo_internal();
	}

	fn redo_internal(&mut self) -> Option<()> {
	if self.index_undo > 2 {
	self.index_undo = self.index_undo.checked_sub(2)?;
	self.undo_internal()
	} else {
	None
	}
	}

	fn undo_internal(&mut self) -> Option<()> {
	self.line_buffer = self.edits.get(self.get_index_undo())?.clone();

	if self.index_undo <= self.edits.len() {
	self.index_undo = self.index_undo.checked_add(1)?;
	}
	Some(())
	}

	pub fn remember_undo_state(&mut self, is_after_action: bool) -> Option<()> {
	self.reset_index_undo();

	if self.edits.len() > 1
	&& self.edits.last()?.word_count() == self.line_buffer.word_count()
	&& !is_after_action
	{
	self.edits.pop();
	}
	self.edits.push(self.line_buffer.clone());

	Some(())
	}

	fn reset_index_undo(&mut self) {
	self.index_undo = 2;
	}

	/// Counts the number of words in the buffer
	pub fn word_count(&self) -> usize {
	self.lines.trim().split_whitespace().count()
	}

nushell / reedline Goto Github PK

reedline's Introduction

A feature-rich line editor - powering Nushell

Introduction

Outline

Examples

Basic example

Integrate with custom keybindings

Integrate with History

Integrate with custom syntax Highlighter

Integrate with custom tab completion

Integrate with Hinter for fish-style history autosuggestions

Integrate with custom line completion Validator

Use custom EditMode

Crate features

Are we prompt yet? (Development status)

Areas for future improvements

Development history

Alternatives

reedline's People

Contributors

Stargazers

Watchers

Forkers

reedline's Issues

History Features

PopUps/PopUnders Features

1. Line Editor UI/UX Features

1.2. Prompt Features #64

1.3. Completions Features #65

1.4. History Features #66

1.5. Hinting Features #65

1.6. Syntax Highlighting Features #67

1.7. PopUps/PopUnders Features #68

1.8. Keybinding #69

1.9. Miscellaneous #70

Syntax Highlighting Features

Current state

Challenge

Example discovered when excluding moves from tracking:

Potentially problematic part of the current implementation

Prompt Features

Keybinding Features

Miscellaneous Features and Goals

Open questions:

Completions Features

Hinting Features

Approach

Implementation

Recommend Projects

Recommend Topics

Recommend Org

Integrate with `History`

Integrate with custom syntax `Highlighter`

Integrate with `Hinter` for fish-style history autosuggestions

Integrate with custom line completion `Validator`

Use custom `EditMode`