Expand description
§reedline \|/
§A readline replacement written in Rust
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.
§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, MenuBuilder};
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 theSystemClipboard
. Enabling this feature will return aSystemClipboard
instead of a local clipboard when callingget_default_clipboard()
.bashisms
: Enable support for special text sequences that recall components from the history. e.g.!!
and!$
. For use in shells likebash
ornushell
.sqlite
: Provides theSqliteBackedHistory
to store richer information in the history. Statically links the required sqlite version.sqlite-dynlib
: Alternative to the featuresqlite
. Will not statically link. Requiressqlite >= 3.38
to link dynamically!external_printer
: Experimental: Thread-safeExternalPrinter
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 multilple 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 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:
Modules§
- Collection of common functions that can be used to create menus
Structs§
- Menu to present suggestions in a columnar fashion It presents a description of the suggestion if available
- Maps cursor shapes to each edit mode (emacs, vi normal & vi insert). If any of the fields is
None
, the cursor won’t get changed by Reedline for that mode. - A hinter that uses the completions or the history to show a hint to the user
- A default completer that can detect keywords
- A hinter that uses the completions or the history to show a hint to the user
- Simple
Prompt
displaying a configurable left and a right prompt. For more fine-tuned configuration, implement thePrompt
trait. For the default configuration, useDefaultPrompt::default()
- A default validator which checks for mismatched quotes and brackets
- Completion menu definition
- Stateful editor executing changes to the underlying
LineBuffer
- This parses the incoming Events like a emacs style-editor
- A simple, example highlighter that shows how to highlight keywords
- An ExternalPrinter allows to print messages of text while editing a line. The message is printed as a new line, the line-edit will continue below the output.
- Stateful history that allows up/down-arrow browsing with an internal cursor.
- Represents one run command with some optional additional context
- Unique ID for the
HistoryItem
. More recent items have higher ids than older ones. - Unique ID for the session in which reedline was run to disambiguate different sessions
- Menu to present suggestions like similar to Ide completion menus
- Represents key modifiers (shift, control, alt, etc.).
- Main definition of editor keybindings
- In memory representation of the entered line(s) including a cursor position to facilitate cursor based editing.
- Struct to store the menu style Context menu definition
- Struct to store the menu style
- Implementation of the output to the terminal
- A representation of the history search
- Line editor engine
- separate struct to not expose anything to the public (for now)
- A wrapper for crossterm::event::Event.
- Defines additional filters for querying the
History
- Query for search in the potentially rich
History
- Highlight all matches for a given search string in a line
- A span of source code, with positions in bytes
- A history that stores the values to an SQLite database. In addition to storing the command, the history can store an additional arbitrary HistoryEntryContext, to add information such as a timestamp, running directory, result…
- A representation of a buffer with styling, used for doing syntax highlighting
- Suggestion returned by the Completer
- This parses incoming input
Event
s like a Vi-Style editor
Enums§
- Represents a color.
- Ways to search for a particular command line in the
History
- A struct to control the appearance of the left or right prompt in a
DefaultPrompt
- The direction of the description box
- Editing actions which can be mapped to key bindings.
- Browsing modes for a
History
- Represents a key.
- Defines all possible events that could happen with a menu.
- Modes that the prompt can be in
- The current success/failure of the history search
- The vi-specific modes that the prompt can be in
- non-public (for now)
- Reedline supported actions.
- Allowed menus in Reedline
- Defines how to traverse the history when executing a
SearchQuery
- Valid ways how
Reedline::read_line()
can return - Every line change should come with an
UndoBehavior
tag, which can be used to calculate how the change should be reflected on the undo stack - Whether or not the validation shows the input was complete
Constants§
- Default size of the
FileBackedHistory
used when callingFileBackedHistory::default()
Traits§
- A trait that defines how to convert some text and a position to a list of potential completions in that position. The text could be a part of the whole line, and the position is the index of the end of the text in the original line.
- Define the style of parsing for the edit events Available default options:
- The syntax highlighting trait. Implementers of this trait will take in the current string and then return a
StyledText
object, which represents the contents of the original line as styled strings - A trait that’s responsible for returning the hint for the current line and position Hints are often shown in-line as part of the buffer, showing the user text they can accept or ignore
- Represents a history file or database Data could be stored e.g. in a plain text file, in a
JSONL
file, in aSQLite
database - Trait that defines how a menu will be printed by the painter
- Common builder for all menus
- API to provide a custom prompt.
- The syntax validation trait. Implementers of this trait will check to see if the current input is incomplete and spans multiple lines
Functions§
- Returns the current default emacs keybindings
- Default Vi insert keybindings
- Default Vi normal keybindings
- Get the default keybindings and return a
Vec<(String, String, String, String)>
where String 1 ismode
, String 2 iskey_modifiers
, String 3 iskey_code
, and Sting 4 isevent
- Return a
Vec<String>
of the ReedlineEditCommand
s - Return a
Vec
of the Reedline Keybinding Modifiers - Return a
Vec<String>
of the ReedlineKeyCode
s - Return a
Vec<String>
of the ReedlinePromptEditMode
s - Return a
Vec<String>
of the ReedlineReedlineEvent
s - Return if the terminal supports the kitty keyboard enhancement protocol
Type Aliases§
- Standard
std::result::Result
, withReedlineError
as the error variant