RustyLine Documentation

RustyLine provides several advanced readline capabilities including:

• Unicode (UTF-8) support
• Word completion and Filename completion
• History search
• Kill ring
• Multi-line support (line wrapping)
• Word commands
• Hints

RustyLine includes a built-in feature that automatically wraps lines that exceed the terminal width to the next visual line. However, this is not a 'true' multi-line mode where the Enter key inserts a literal newline into the input buffer.

To implement true multi-line editing (where a user can explicitly add newlines to the input buffer), you must implement the Validator trait.

To use RustyLine in your Rust project, add it to your Cargo.toml dependencies. Note that the current version is 18.0.0.

[dependencies]
rustyline = "18.0.0"

You can customize how tab completion works using the following settings:

• Completion Type: Set via completion_type(CompletionType). Options include:
  • CompletionType::Circular: Complete the next full match.
  • CompletionType::List: Complete to the longest match and list all matches (similar to Bash).
  • CompletionType::Fuzzy: Fuzzy search (requires --features=fuzzy on Unix).
• Ambiguity Handling: Use completion_show_all_if_ambiguous(bool) to decide if all alternatives are shown immediately when using List mode. By default, a second tab is required.
• Prompt Limit: Use completion_prompt_limit(usize) to limit how many possibilities are displayed at once when using List mode.

To add features like tab-completion, syntax highlighting, or validation, you must implement the Helper trait. A Helper is a composite trait that requires your type to implement Completer, Hinter, Highlighter, and Validator.

Once implemented, you can attach it to an editor using set_helper(Some(your_helper)).

RustyLine provides several options for managing command history:

• Maximum Size: Use max_history_size to limit the number of entries.
• Duplicate Handling: Use history_ignore_dups(bool) to decide if consecutive identical entries should be saved. By default, they are ignored (HistoryDuplicates::IgnoreConsecutive).
• Space Ignoring: Use history_ignore_space(bool) to determine if lines starting with a space character should be saved. By default, they are saved.
• Automatic Addition: Use auto_add_history(bool) to enable/disable automatic history updates for nonblank lines.

The History trait defines the interface for managing, searching, and persisting command history. Implementations allow for both transient in-memory history and persistent file-based history.

Key capabilities include:

• Adding new entries with duplicate or whitespace filtering.
• Searching history (both forward and reverse) using substring or anchored (starts_with) matching.
• Managing history size and clearing entries.
• Loading and saving history to files (when using a file-based implementation).

The simplest way to use RustyLine is by using DefaultEditor. It provides a high-level API to read lines from the terminal with support for history, completion, and editing.

let mut rl = rustyline::DefaultEditor::new()?;
let readline = rl.readline(">> ");
match readline {
    Ok(line) => println!("Line: {:?}", line),
    Err(_) => println!("No input"),
}
# Ok::<(), rustyline::error::ReadlineError>(())

To customize the behavior of the line editor, use the Config::builder() method. The builder pattern allows you to chain configuration settings before building the final Config object.

Commonly configured settings include:

• max_history_size(usize): Maximum number of entries in history.
• history_ignore_dups(bool): Whether to ignore consecutive duplicate history entries.
• edit_mode(EditMode): Choose between EditMode::Emacs or EditMode::Vi.
• completion_type(CompletionType): Set how completions behave (e.g., Circular, List).
• auto_add_history(bool): If true, nonblank lines are automatically added to history.
• color_mode(ColorMode): Control color highlighting.
• tab_stop(u8): Horizontal space taken by a tab.
• indent_size(u8): Indentation size for indent/dedent commands.

When running RustyLine examples compiled for Windows on a non-Windows system using Wine, you may encounter handle errors. Using wineconsole with the curses backend can help mitigate issues.

$ cargo run --example example --target 'x86_64-pc-windows-gnu'
...
Error: Io(Error { repr: Os { code: 6, message: "Invalid handle." } })
$ wineconsole --backend=curses target/x86_64-pc-windows-gnu/debug/examples/example.exe