Module rucline::actions

Provides mappings and actions to change the behavior of Prompt when parsing the 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 Prompt to cause a different Action to be taken.

Examples

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

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

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

use rucline::Prompt;
use rucline::actions::{Action, Context, Event, KeyBindings};
use crossterm::event::KeyCode;

let prompt = Prompt::new().overrider(&|e, _: &dyn Context| 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};
use crossterm::event::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};
use crossterm::event::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,

Re-exports

pub use crate::Context;

Enums

Action	An action that can be performed while reading a line
Direction	The direction an Action may take
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

Event	Alias to crossterm::event::KeyEvent from crossterm
KeyBindings	Alias to HashMap<Event, Action>