vim-navigation is a terminal-framework-independent Rust library for
Vim-compatible cursor and viewport motion, Normal-mode command state, and an
explicitly opt-in Normal/Insert text buffer. It does not perform terminal I/O,
read files, or know about an application's documents.
The compatibility contract lists the tested motions and limits, including scalar-based Unicode movement and simplified structural scans.
Installation
Requires Rust 1.88 or newer. For a published release, add:
[]
= "0.2.0"
When upgrading from 0.1.0, replace the boolean count-origin argument to
Motion::counted with CountSource::Explicit or CountSource::Implicit.
The enum keeps the same distinction while making call sites self-describing.
To try unreleased source before its version is available on crates.io, use the repository instead:
[]
= { = "https://github.com/karanabe/chronogit" }
The library is developed in the ChronoGit workspace. ChronoGit's own manifest
uses both version and path: Cargo uses the local crate in the checkout and
the versioned registry dependency in a published package. External consumers
do not need the workspace's directory layout.
Major concepts
motionowns zero-basedCursorcoordinates,Viewportdisplay geometry, theMotionKindvocabulary, explicit/implicitCountSource, and pure motion over borrowed logical lines.commandowns a saturating count, an incomplete find/till command, its character argument, and;/,repetition throughMotionState.editorowns the separate mutableEditableBuffer, its Normal/Insert mode, input vocabulary, byte limit, and edit outcomes.
All public types remain available from the crate root for concise imports; the three public module paths expose the responsibility boundaries for reference documentation. Application-owned key bindings, search history, marks, jump lists, file access, and rendering stay outside the crate.
Read-only motion
Cursor::byte_column is a UTF-8 byte offset. Viewport left, width, and
gutter are terminal display cells. Tabs use four-cell stops, and Unicode
display width is measured independently of its byte length.
use ;
let lines = ;
let before = lines;
let mut viewport = new;
let cursor = apply;
assert_eq!;
assert_eq!;
apply accepts empty input and clamps invalid line or byte coordinates to a
safe Normal-mode position. It updates the viewport and retained desired display
column, but cannot mutate the borrowed lines.
Counts and character arguments
Feed decimal digits and completed key bindings into MotionState. A find/till
template first reports that it needs a character, then produces a complete
motion for apply:
use ;
let mut commands = new;
assert!;
assert_eq!;
let Some = commands.accept_target else ;
assert_eq!;
assert_eq!;
Counts saturate at usize::MAX; a leading zero remains available for the Vim
0 motion. Callers own terminal event parsing and should reset an incomplete
command when mode or focus changes.
When a caller constructs an already-resolved counted motion directly, the count origin remains explicit in the type instead of a positional boolean:
use ;
let motion = new.counted;
assert_eq!;
assert!;
Opt-in editing
Applications that intentionally permit editing can own an EditableBuffer.
Read-only applications do not need to depend on or construct this type.
use ;
let mut buffer = new;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Use EditableBuffer::with_byte_limit for bounded input. Invalid mode/input
combinations, line separators passed as characters, boundary deletion, and
limit-exceeding insertion return EditOutcome::Ignored rather than panicking.
The default Insert escape sequence is jj; the first j is inserted
immediately and only its candidate status is retained, so a lone prefix never
waits behind a timeout or disappears on a focus change. The second j removes
the escape prefix and applies the same cursor normalization as Esc. Call
flush_pending_input before changing an input target, use
InsertEscapeSequence::disabled() for literal jj, or construct a replacement
such as InsertEscapeSequence::new("jk").
cargo test -p vim-navigation --doc verifies the Rust examples in this README
and the API documentation, including the multi-line editor example.
ChronoGit boundary and compatibility
ChronoGit's adapter converts application
positions and pane geometry, applies crate motion to borrowed document lines,
and retains application-specific search and mark state. ChronoGit never creates
EditableBuffer, so source, diff, Git-object, and commit text remain read-only.
Its normal application context reserves Space as a leader, so its default
adapter omits standalone Space/RightWrap while keeping l and Right. Search
prompts treat Space and jj as literal text. These application choices do not
remove the library's Vim Space motion or default editable-buffer jj contract.
See the ChronoGit architecture
for that integration boundary.
COMPATIBILITY.md records the fixed Vim reference and
comparison conditions, supported command inventory, executable
85-case Vim oracle, stateful adapter evidence, and explicit exclusions. A
successful Rust build alone is not treated as Vim-compatibility evidence.