Skip to main content

vim_navigation/
lib.rs

1//! Vim-compatible navigation and explicit modal text input.
2//!
3//! `vim-navigation` has no terminal-framework, filesystem, or application
4//! dependency. Its three modules have deliberately different owners:
5//!
6//! - [`motion`] applies completed read-only cursor and viewport movements to a
7//!   borrowed text snapshot;
8//! - [`command`] resolves Normal-mode counts, character arguments, and
9//!   character-search repetition without parsing terminal events;
10//! - [`editor`] is the separate opt-in owner of mutable Normal/Insert text.
11//!
12//! Search histories, marks, jump lists, key bindings, and application resources
13//! stay with the caller. Positions use zero-based line numbers and UTF-8 byte
14//! columns; viewport columns use terminal display cells and four-cell tab stops.
15//!
16//! # 1. Apply a read-only motion
17//!
18//! ```
19//! use vim_navigation::{Cursor, Motion, MotionKind, Viewport, apply};
20//!
21//! let lines = ["alpha beta", "gamma"];
22//! let before = lines;
23//! let mut viewport = Viewport::new(0, 0, 2, 20, 0);
24//! let cursor = apply(
25//!     &lines,
26//!     Cursor::new(0, 0),
27//!     &mut viewport,
28//!     Motion::new(MotionKind::WordForward),
29//! );
30//!
31//! assert_eq!(cursor, Cursor::new(0, 6));
32//! assert_eq!(lines, before); // `apply` only borrows the snapshot.
33//! ```
34//!
35//! # 2. Resolve a count and character argument
36//!
37//! ```
38//! use vim_navigation::{Motion, MotionKind, MotionResolution, MotionState};
39//!
40//! let mut commands = MotionState::new();
41//! assert!(commands.push_count_digit('2'));
42//! assert_eq!(
43//!     commands.finish(Motion::new(MotionKind::FindForward)),
44//!     MotionResolution::AwaitingTarget,
45//! );
46//! let Some(find) = commands.accept_target('a') else {
47//!     panic!("the preceding find motion is waiting for a target");
48//! };
49//! assert_eq!(find.count(), 2);
50//! assert_eq!(find.target(), Some('a'));
51//! ```
52//!
53//! # 3. Opt into Normal/Insert editing
54//!
55//! ```
56//! use vim_navigation::{EditOutcome, EditableBuffer, EditorInput, Mode, Viewport};
57//!
58//! let mut buffer = EditableBuffer::new("ab", Viewport::new(0, 0, 2, 20, 0));
59//! assert_eq!(buffer.handle(EditorInput::Append), EditOutcome::ModeChanged);
60//! assert_eq!(buffer.handle(EditorInput::Character('界')), EditOutcome::Changed);
61//! assert_eq!(buffer.handle(EditorInput::Newline), EditOutcome::Changed);
62//! assert_eq!(buffer.handle(EditorInput::Character('x')), EditOutcome::Changed);
63//! assert_eq!(buffer.handle(EditorInput::Character('j')), EditOutcome::Changed);
64//! assert_eq!(buffer.handle(EditorInput::Character('j')), EditOutcome::ModeChanged);
65//!
66//! assert_eq!(buffer.mode(), Mode::Normal);
67//! assert_eq!(buffer.text(), "a界\nxb");
68//! ```
69
70pub mod command;
71pub mod editor;
72pub mod motion;
73
74pub use command::{MotionResolution, MotionState};
75pub use editor::{
76    EditOutcome, EditableBuffer, EditorInput, InsertEscapeSequence, InsertEscapeSequenceError, Mode,
77};
78pub use motion::{CountSource, Cursor, Motion, MotionKind, Viewport, apply, reveal};
79
80// Keep the published README's examples executable alongside the API examples.
81#[cfg(doctest)]
82#[doc = include_str!("../README.md")]
83mod readme_examples {}