Module rucline::actions

Provides mappings and actions to change the behavior of the prompt when reading user input.

There is a built-in set of default Actions that will be executed upon user interaction. These are meant to feel natural when coming from the default terminal, while also adding further functionality and editing commands.

However, bindings that override the default behavior can be given to the prompt to cause a different Action to be taken.

Examples

Changing the behavior of TAB from the default Suggest action to actually printing \t.

Using KeyBindings:

use rucline::actions::{Action, Event, KeyBindings, KeyCode};
use rucline::prompt::{Builder, Prompt};

let mut bindings = KeyBindings::new();
bindings.insert(Event::from(KeyCode::Tab), Action::Write('\t'));

let prompt = Prompt::new().overrider(bindings);

Using a closure:

use rucline::actions::{Action, Event, KeyCode};
use rucline::prompt::{Builder, Prompt};

let prompt = Prompt::new().overrider_fn(|e, _| {
    if e == Event::from(KeyCode::Tab) {
        Some(Action::Write('\t'))
    } else {
        None
    }
});

Overriding a default action

The KeyBindings map provides a way to store the association between Event and Action which will override the default behavior.

use rucline::actions::{Action, Event, KeyBindings, KeyCode};

let mut bindings = KeyBindings::new();
bindings.insert(Event::from(KeyCode::Tab), Action::Write('\t'));

Disabling a default action

To explicitly remove an Action from the default behavior, the Noop action can be set as the override.

use rucline::actions::{Action, Event, KeyBindings, KeyCode};

let mut bindings = KeyBindings::new();
bindings.insert(Event::from(KeyCode::Tab), Action::Noop);

Saving key binding configurations

If the feature serialize is enabled, KeyBindings can be serialized, stored, and loaded at runtime.

Default behavior

In the absence of KeyBindings or an entry for a given Event, the default behavior will be as follows:

KeyCode::Enter => Accept,
KeyCode::Esc => Cancel,
KeyCode::Tab => Suggest(Forward),
KeyCode::BackTab => Suggest(Backward),
KeyCode::Backspace => Delete(Relative(Single, Backward)),
KeyCode::Delete => Delete(Relative(Single, Forward)),
KeyCode::Right => Move(Single, Forward),
KeyCode::Left => Move(Single, Backward),
KeyCode::Home => Move(Line, Backward),
KeyCode::End => Move(Line, Forward),
KeyCode::Char(c) => {
    if event.modifiers == crossterm::event::KeyModifiers::CONTROL {
        match c {
            'm' | 'd' => Accept,
            'c' => Cancel,

            'b' => Move(Single, Backward),
            'f' => Move(Single, Forward),
            'a' => Move(Line, Backward),
            'e' => Move(Line, Forward),

            'j' => Delete(Relative(Word, Backward)),
            'k' => Delete(Relative(Word, Forward)),
            'h' => Delete(Relative(Line, Backward)),
            'l' => Delete(Relative(Line, Forward)),
            'w' => Delete(WholeWord),
            'u' => Delete(WholeLine),
            _ => Noop,
        }
    } else if event.modifiers == crossterm::event::KeyModifiers::ALT {
        match c {
            'b' => Move(Word, Backward),
            'f' => Move(Word, Forward),
            _ => Noop,
        }
    } else {
        Write(c)
    }
}
_ => Noop,

Check the test cases for Buffer to see how line edits are expected to behave.

Structs

Event

Alias to crossterm::event::KeyEvent from crossterm.

Enums

Action	An action that can be performed while reading a line
Direction	The direction an Action may take
KeyCode	Alias to crossterm::event::KeyCode from crossterm.
Range	The range an Action should extend for
Scope	The scope an Action should be applied on

Traits

Overrider

Overrides the behavior for a given Event.

Type Definitions

KeyBindings

Alias to HashMap<Event, Action>