Environment:

• macOS 11.6.8
• Terminal.app (TERM=xterm-256color)
• Rust 1.65.0
• rustyline-async commit f9817e7 cloned from GitHub

When running the readline example in this repository, if I hit Ctrl-D, the program exits immediately without printing the "Exiting..." message, like so:

If I remove the break in the Err(ReadlineError::Eof) branch, the message is printed.

Similarly, if I add a break to the Err(ReadlineError::Interrupted) branch, pressing Ctrl-C results in the "^C" message not being printed — along with an additional prompt being printed before my shell command prompt, like so:

Adding rl.flush()?; or Write::flush(&mut stdout)?; after the call to writeln doesn't help.

Note that this isn't just limited to Eof and Interrupted, either. When running the following code:

use rustyline_async::{Readline, ReadlineError};
use std::io::Write;
use std::time::Duration;
use tokio::time::sleep;

#[tokio::main]
async fn main() -> Result<(), ReadlineError> {
    let (mut rl, mut stdout) = Readline::new("> ".into())?;
    loop {
        tokio::select! {
            _ = sleep(Duration::from_secs(3)) => {
                writeln!(stdout, "Message received!")?;
            }
            cmd = rl.readline() => match cmd {
                Ok(line) => {
                    writeln!(stdout, "{line:?}")?;
                    rl.add_history_entry(line.clone());
                    if line == "quit" {
                        break;
                    }
                }
                Err(ReadlineError::Eof) => {
                    writeln!(stdout, "<EOF>")?;
                    break;
                }
                Err(ReadlineError::Interrupted) => {
                    writeln!(stdout, "<Ctrl-C>")?;
                    break;
                }
                Err(e) => {
                    writeln!(stdout, "Error: {e:?}")?;
                    break;
                }
            }
        }
    }
    Ok(())
}

typing "quit" will result in the program exiting without outputting "quit", yet it still outputs the next readline prompt (which ends up prepended to my shell prompt), like so:

This implements a simple optional history, that can be manually appended to through a function on Readline.

History entries can be recalled by using the arrow keys. I chose to make the history unchangeable, although there are shells that allow the user to change history entries.

Usage

A Readline with history can be created using Readline::with_history(prompt, max_size). New history entries can be appended using Readline::add_history_entry(entry).

Up for debate

• Should the history really be unchangeable?
• Should this be hidden behind a feature flag?
• The implementation currently uses a Mutex to ensure thread-safety of appending new entries. Alternatives:
  • Use a RwLock instead, currently not really useful as there aren't really any read-only accesses.
  • Remove the thread-safety and let the user handle mutable concurrent accesses to Readline
• Should there be a way to get (read-only) access to the history from Readline?
• Should this be separated into its own file? (Should be a general consideration in this library :) )
• Should the constructor be changed into accepting struct/builder for the history size (and future additional parameters)?
• The VecDeque used is currently created through default. Technically a capacity could be specified based on the max_size. This could consume unnecessarily large memory amounts when the max_size is high, but the history's actual length is low.

This implements functionality when pressing Home or End keys to go the beginning and end of the input respectively.

This also adds Ctrl-A and Ctrl-E as the well-known Emacs-based aliases for these actions.

Currently, this library has no explicit license, resulting in a strong copyright.

As you're welcoming contributions in the README, I suspect this to be an oversight.

You can check https://choosealicense.com/ for a simple overview over some free licenses.

Personally, I prefer using the MIT or Apache 2.0 licenses, but the final choice is up to you (and probably partially me because I contributed without noticing it and therefore probably have copyright on my stuff ^^ - but I'll go with any free license).

This PR fixes an important issue: Currently this library prevents users from entering special characters on Windows!

The previous code specifies the KeyModifiers explicitly:

https://github.com/zyansheep/rustyline-async/blob/da40db1dd0d12babc46f74b5268aa15618433ade/src/line.rs#L167-L174

There are two flaws with this design:

1. A lot of international keyboard layouts rely on modifier keys to reach certain special keys. Especially AltGr is used relatively often for that on international keyboard layouts. For example on typical German layouts, the [ is only reachable via AltGr + 8. Since some terminals (for example Windows terminals) send AltGr as Ctrl + Alt, these special keys wouldn't be matched by a simple KeyModifiers::NONE | KeyModifiers::SHIFT.

2. Building up on 1: One would think that explicitly allowing modifiers: KeyModifiers::CONTROL | KeyModifiers::ALT would match for this case. This is not the case! KeyModifiers are implemented as an enum using the bitflags crate. Since the underlying type is an enum the bitor operator (|) will only perform a logical or in a match expression. There seems to be no easy way to check for a combination of modifier keys in a match branch.

My solution moves the whole regular input code down below the control keys. This means that input with any modifiers other than plain CONTROL will be handled as normal input.

While Ctrl + Alt + Something isn't typically used for commands in terminals (Compare rustyline's actions), Ctrl + Shift + Something isn't that unusual and should maybe be captured in the future.

If you decide that you want to check the modifier combinations more closely in the code, then you'll probably have to drop them from the match and resort to some ol' if-checking.

The examples were previously their own subprojects.

This is arguably overcomplicated and unintuitive as they won't be easily executable with cargo run --example.

This pr simply moves the respective main.rs files up to the examples directory and adds async-std, log and simplelog as dev-dependenvies to the Cargo.toml.

When a line of input is terminated by pressing Ctrl-C, the prompt and any text entered so far will remain on the screen even as new lines are printed below them. This is unlike lines terminated by pressing Enter, for which the line and prompt disappear, and it leads to a messy-looking interface.

Program that can be used to reproduce this behavior:

use rustyline_async::{Readline, ReadlineError};
use std::io::Write;
use std::time::Duration;
use tokio::time::sleep;

#[tokio::main]
async fn main() -> Result<(), ReadlineError> {
    let (mut rl, mut stdout) = Readline::new("prompt> ".into())?;
    loop {
        tokio::select! {
            _ = sleep(Duration::from_secs(1)) => {
                writeln!(stdout, "Message received!")?;
            }
            cmd = rl.readline() => match cmd {
                Ok(line) => {
                    writeln!(stdout, "You entered: {line:?}")?;
                    rl.add_history_entry(line.clone());
                    if line == "quit" {
                        break;
                    }
                }
                Err(ReadlineError::Eof) => {
                    writeln!(stdout, "<EOF>")?;
                    break;
                }
                Err(ReadlineError::Interrupted) => {writeln!(stdout, "^C")?; continue; }
                Err(e) => {
                    writeln!(stdout, "Error: {e:?}")?;
                    break;
                }
            }
        }
    }
    rl.flush()?;
    Ok(())
}

Recording of this behavior:

(Incidentally, if no text is printed in response to the Ctrl-C, things get a bit messed up on the next output; perhaps that should be a separate issue.)

Issue on implementation details for readline history:

Up for debate

• Should the history really be unchangeable?
• Should this be hidden behind a feature flag?
• The implementation (#4) currently uses a Mutex to ensure thread-safety of appending new entries. Failing to acquire a lock (which should only be possible, if another thread panicked with the lock), will currently panic. Alternatives:
  • Pass lock errors through as a new type of error
  • Use a RwLock instead, currently not really useful as there aren't really any read-only accesses.
  • Remove the thread-safety and let the user handle mutable concurrent accesses to Readline
• Should there be a way to get (read-only) access to the history from Readline?
• Should this be separated into its own file? (Should be a general consideration in this library :) )
• Should the constructor be changed into accepting struct/builder for the history size (and future additional parameters)?
• The VecDeque used is currently created through default. Technically a capacity could be specified based on the max_size. This could consume unnecessarily large memory amounts when the max_size is high, but the history's actual length is low.

My Thoughts

Should the history really be unchangeable?

Probably... A history is a history because it happened in the past, and past in unchangeable.

Should this be hidden behind a feature flag?

Nahh

The implementation currently uses a Mutex to ensure thread-safety of appending new entries. Failing to acquire a lock (which should only be possible, if another thread panicked with the lock), will currently panic. Alternatives: Pass lock errors through as a new type of error Use a RwLock instead, currently not really useful as there aren't really any read-only accesses. Remove the thread-safety and let the user handle mutable concurrent accesses to Readline Should there be a way to get (read-only) access to the history from Readline?

My "perfect" history implementation would look something along the lines of :

1. append-from-anywhere & read-from-anywhere like boxcar
2. storage-agnostic system that allows for either in-memory history or sync-to-file history a. The downside sync-to-file is how its done, do we use Seek to look for newlines between history entries? Or do we manually serialize & deserialize the whole file whenever we want to sync? seeking & appending would be faster, but what happens if we want max history sizes? then the whole file needs to be rewritten which may require loading the entire thing into memory.

Should this be separated into its own file? (Should be a general consideration in this library :) )

Definitely, maybe even its own library to allow for other people to use it.

Should the constructor be changed into accepting struct/builder for the history size (and future additional parameters)?

That is a good idea, and is basically what rustyline does, which goes with the theme of trying to match their api.

Also to consider: do we want to have history searching (which would probably necessitate a BTree of some kind) or history deduplication? This is how rustyline does it, no async tho: https://docs.rs/rustyline/6.3.0/src/rustyline/history.rs.html#25-30 I'm curious how ion does it, but I cannot grok their codebase...