Expand description
Headless Vim key handling and motion resolution over borrowed UTF-8 text.
Vimlet adds Vim editing to an application that already owns its text buffer. It interprets keys, manages modes, registers and repeat, and asks your application to apply edits. It needs no terminal, async runtime or Red dependency. Strings work out of the box; Ropey support is an optional feature.
§Start here
Quickstart: edit a string with Vim keys is a complete,
runnable program. It changes one two three into hello hello three with
cwhello<Esc>w., including the host code that applies edits and acknowledges them.
Then follow the host integration guide to connect your document, undo history and event loop. The recipes cover custom mappings, macros, composer drafts and Ropey storage.
| I want to… | Start with |
|---|---|
| Add modal editing to a buffer or input field | Session, EditingState and the quickstart |
| Compute a motion destination or text-object range | MotionResolver and the example below |
| Connect my application’s mutation and undo pipeline | HostOperation, HostResult and the integration guide |
| Use my own storage or a Ropey buffer | TextSource and the storage recipe |
§What Vimlet owns
Keep one EditingState per editing surface and a Session for surfaces that
share registers, macro playback and dot repeat. Pass a borrowed DocumentView
with each input. The view does not transfer ownership of the buffer.
| Vimlet | Your application |
|---|---|
| Key interpretation, counts and pending commands | Terminal events and custom keymaps |
| Modes, register contents, dot recipes and macro state | Text storage, cursor, selection and revisions |
| Motions, text objects and proposed edits | Applying edits, undo history and change notifications |
| Requests for host services | Search UI, syntax, clipboard transport and rendering |
Session::handle returns a Step. For a host operation, apply or reject the
request and acknowledge it with Session::resume. Process the returned step too:
one key can produce several operations. Cursor and edit coordinates are UTF-8 bytes.
§Resolving a motion
The resolver also works independently of modes and key handling. It reads your text and returns a destination or range without modifying the document.
use vimlet::{ByteOffset, Motion, MotionResolver};
let text = "éclair";
let resolver = MotionResolver::new(&text, ByteOffset(0));
let destination = resolver.resolve(Motion::Right, 1).map(|target| target.position);
assert_eq!(destination, Some(ByteOffset(2)));For inner/around words, quotes or delimiters, use MotionResolver::text_object.
For operator targets, use MotionResolver::operator_range to account for Vim’s
inclusive, exclusive and linewise range rules.
§Compatibility
Neovim decides behavior for the Vim commands implemented by this crate. The reference suite compares text, byte cursor, mode and unnamed register against Neovim 0.12.1. This is a modal editing engine, not an implementation of Neovim’s entire command language or plugin runtime. Host services and display behavior depend on your adapter; the integration guide explains that boundary.
Re-exports§
pub use engine::Action;pub use engine::AppliedEdit;pub use engine::Binding;pub use engine::BindingContext;pub use engine::Capabilities;pub use engine::Command;pub use engine::EditTarget;pub use engine::EditingState;pub use engine::EngineError;pub use engine::HistoryCommand;pub use engine::HostCommand;pub use engine::HostOperation;pub use engine::HostOutcome;pub use engine::HostResult;pub use engine::Input;pub use engine::InputOrigin;pub use engine::InsertStyle;pub use engine::Key;pub use engine::Lifecycle;pub use engine::Limits;pub use engine::Mode;pub use engine::OperationKind;pub use engine::Operator;pub use engine::Replacement;pub use engine::Session;pub use engine::Step;pub use engine::TargetRequest;pub use engine::Transaction;pub use motion::CharacterMotion;pub use motion::Motion;pub use motion::MotionResolver;pub use motion::ResolvedRange;pub use motion::Target;pub use motion::TextObjectKind;pub use motion::TextObjectScope;pub use motion::WordClass;pub use motion::WordDestination;pub use registers::Register;pub use registers::Registers;pub use text::TextSource;pub use types::ByteOffset;pub use types::DocumentVersion;pub use types::DocumentView;pub use types::Geometry;pub use types::Selection;pub use types::Shape;pub use types::TerminalGeometry;pub use types::TextRange;pub use types::DEFAULT_GEOMETRY;
Modules§
- engine
- Interpret Vim input and mode changes against a host-owned document.
- guide
- Practical guides for adding Vimlet to an application.
- motion
- Resolve Vim motions and text objects over a borrowed
TextSource. - registers
- One bank for text and recorded input, including automatic Vim registers.
- text
- Borrowed UTF-8 access for contiguous strings and chunked text.
- types
- Coordinates and host document views. All offsets are UTF-8 bytes.