Skip to main content

Crate vim_navigation

Crate vim_navigation 

Source
Expand description

Vim-compatible navigation and explicit modal text input.

vim-navigation has no terminal-framework, filesystem, or application dependency. Its three modules have deliberately different owners:

  • motion applies completed read-only cursor and viewport movements to a borrowed text snapshot;
  • command resolves Normal-mode counts, character arguments, and character-search repetition without parsing terminal events;
  • editor is the separate opt-in owner of mutable Normal/Insert text.

Search histories, marks, jump lists, key bindings, and application resources stay with the caller. Positions use zero-based line numbers and UTF-8 byte columns; viewport columns use terminal display cells and four-cell tab stops.

§1. Apply a read-only motion

use vim_navigation::{Cursor, Motion, MotionKind, Viewport, apply};

let lines = ["alpha beta", "gamma"];
let before = lines;
let mut viewport = Viewport::new(0, 0, 2, 20, 0);
let cursor = apply(
    &lines,
    Cursor::new(0, 0),
    &mut viewport,
    Motion::new(MotionKind::WordForward),
);

assert_eq!(cursor, Cursor::new(0, 6));
assert_eq!(lines, before); // `apply` only borrows the snapshot.

§2. Resolve a count and character argument

use vim_navigation::{Motion, MotionKind, MotionResolution, MotionState};

let mut commands = MotionState::new();
assert!(commands.push_count_digit('2'));
assert_eq!(
    commands.finish(Motion::new(MotionKind::FindForward)),
    MotionResolution::AwaitingTarget,
);
let Some(find) = commands.accept_target('a') else {
    panic!("the preceding find motion is waiting for a target");
};
assert_eq!(find.count(), 2);
assert_eq!(find.target(), Some('a'));

§3. Opt into Normal/Insert editing

use vim_navigation::{EditOutcome, EditableBuffer, EditorInput, Mode, Viewport};

let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
assert_eq!(buffer.handle(EditorInput::Append), EditOutcome::ModeChanged);
assert_eq!(buffer.handle(EditorInput::Character('界')), EditOutcome::Changed);
assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
assert_eq!(buffer.handle(EditorInput::Character('x')), EditOutcome::Changed);
assert_eq!(buffer.handle(EditorInput::Character('j')), EditOutcome::Changed);
assert_eq!(buffer.handle(EditorInput::Character('j')), EditOutcome::ModeChanged);

assert_eq!(buffer.mode(), Mode::Normal);
assert_eq!(buffer.text(), "a界\nxb");

Re-exports§

pub use command::MotionResolution;
pub use command::MotionState;
pub use editor::EditOutcome;
pub use editor::EditableBuffer;
pub use editor::EditorInput;
pub use editor::InsertEscapeSequence;
pub use editor::InsertEscapeSequenceError;
pub use editor::Mode;
pub use motion::CountSource;
pub use motion::Cursor;
pub use motion::Motion;
pub use motion::MotionKind;
pub use motion::Viewport;
pub use motion::apply;
pub use motion::reveal;

Modules§

command
Normal-mode command resolution independent of key bindings.
editor
Explicitly mutable Normal/Insert buffer state.
motion
Read-only Vim cursor and viewport motion.