reedline

Reedline manages terminal interaction using the following technical approaches:

• Terminal Control: Uses the crossterm crate to abstract terminal styling, setup, and event handling. This allows Reedline to handle both ANSI escape sequences (standard on Unix) and Windows-specific API calls for non-ANSI compliant Windows terminals.
• Input Handling: Operates in raw mode to intercept user input events directly.
• Newline Handling: Because of raw mode, standard \n (LF) behavior may vary by platform. On Unix, \n might only move the cursor down without returning to the start of the line, necessitating \r\n (CRLF) for proper drawing operations.
• Keybindings: Note that some Ctrl keybindings may be affected by how terminal emulators encode CTRL-<key> sequences.

To catch potential index overflows and other runtime issues, run the example binary.

• Debug mode: Use cargo run to catch errors like index overflows. Note that debug mode may be significantly slower, which can impact the perceived smoothness of features like window resizing.
• Release mode: Use cargo run --release to test the actual user experience, especially for performance-sensitive tasks like resizing.

Since Reedline lacks automated tests for user-facing terminal logic, manual verification is required when changes affect the following areas:

• Repaint logic.
• Key press dispatching.
• Addition of new components.
• Components that lack unit tests upholding the I/O facing engine contract.
• Large refactors touching multiple components simultaneously.

For completers that perform heavy or asynchronous work (like network calls), use the CompletionStatus and CompletionResult types to manage the lifecycle of the request.

Workflow

1. Start: Return CompletionResult::Pending and set poll_completion to return CompletionStatus::Pending.
2. Polling: The engine calls poll_completion periodically. Return CompletionStatus::Pending while working.
3. Finish: Once data is ready, return CompletionResult::Fresh and have poll_completion return CompletionStatus::Ready.

CompletionStatus Variants

• Idle: No background work is happening.
• Pending: Background work is in progress; the engine should keep polling.
• Ready: The background work just finished; the engine should refresh the UI with the new results.

The Partial struct allows a completer to tell Reedline to replace a specific Span in the buffer with a specific insert string. This is useful for implementing custom longest common prefix (LCP) logic.

When a CompletionResult includes a Partial object, Reedline splices the insert text over the span verbatim, rather than using its default LCP derivation.

Partial Fields

• span: The Span (start and end bytes) in the buffer to be replaced.
• insert: The String to be spliced in.

When implementing custom completion logic, be aware of how ColumnarMenu handles stale results. A result is considered stale if its CompletionOrigin (the buffer state and insertion point when the completion was requested) no longer matches the current state of the Editor buffer.

To prevent incorrect text splicing, ColumnarMenu performs the following checks:

• Partial Completion: menu.can_partially_complete will return false if the suggestion's origin is mismatched with the live buffer.
• Accepting Completion: menu.replace_in_buffer will not splice a stale span into the buffer if the origin is mismatched.

If you are providing completions, ensure you correctly track the CompletionOrigin to allow the menu to validate whether the suggestions are still applicable to the user's current input.

The DescriptionMode enum determines how the description box (the extra information shown for a selected suggestion) is positioned relative to the completion list:

• DescriptionMode::Left: The description is always shown on the left side of the completion box.
• DescriptionMode::Right: The description is always shown on the right side of the completion box.
• DescriptionMode::PreferRight: The description is shown on the right if there is sufficient terminal space; otherwise, it falls back to the left side.

pub enum DescriptionMode {
    Left,
    Right,
    PreferRight,
}

The ColumnarMenu supports two modes of navigation via the TraversalDirection enum:

1. Horizontal: The menu fills rows first. Moving 'next' moves to the next column in the current row. When the end of a row is reached, it wraps to the start of the next row.
2. Vertical: The menu fills columns first. Moving 'next' moves down the current column. When the bottom of a column is reached, it wraps to the top of the next column.

Navigation is handled via MenuEvents such as MoveUp, MoveDown, MoveLeft, MoveRight, NextElement, and PreviousElement.

#[derive(Debug, PartialEq, Eq)]
pub enum TraversalDirection {
    /// Traverse horizontally
    Horizontal,
    /// Traverse vertically
    Vertical,
}

The LineBuffer struct is the in-memory representation of the text being edited. It manages multiple lines of text and maintains a Cursor to facilitate editing, including text selection.

Line-ending Contract

Warning: The buffer may contain \r characters. While typing emits \n and certain operations normalize CRLF to LF, other entry points (like EditCommand::InsertString, external editors, or completers) can introduce \r. All line, word, and cursor logic treats \r or \r\n as a terminator. Do not assume the buffer is CR-free.

use reedline::core_editor::LineBuffer;

let mut buffer = LineBuffer::new();
buffer.insert_str("Hello, world!");