🔗
nvim-oxi
nvim-oxi provides safe and idiomatic Rust bindings to the rich API exposed by the Neovim text editor.
The project is mostly intended for plugin authors, although nothing's stopping end users from writing their Neovim configs in Rust.
How
The traditional way to write Neovim plugins in languages other than the "builtin" ones, i.e. Vimscript or Lua, is via RPC channels. This approach comes with a few limitations mostly due to having to (de)serialize everything to MessagePack-encoded messages, prohibiting things like attaching callbacks to keymaps or scheduling functions.
nvim-oxi takes a different approach. It leverages Rust's foreign function interface (FFI) support to hook straight into the Neovim C code, allowing feature parity with "in process" plugins while also avoiding the need for an extra IO layer.
This thread on the Neovim discourse goes into a bit more detail for anyone who's interested.
Why
Why bother when Neovim already has Lua as a first-class citizen? Mainly two reasons:
-
access to the Rust ecosystem: Lua is a great, minimal scripting language but can also be limiting when writing more complex plugins. In contrast Rust is a fully-fledged, statically typed language with a huge ecosystem of crates for (de)serialization, networking, IO, green threads, etc;
-
nvim-oxi provides a fully typed API: everything from optional function fields to callback arguments is checked at compile-time. This allows plugin authors to spend less time reading through the help docs and more time iterating via
cargo checks.
Examples
The examples directory contains several examples of how to use nvim-oxi. It also contains instructions on how to setup your Rust crate, where to place the compiled artifacts and how to load the final plugin from Neovim.
If you're still not sure about something feel free to open a new issue and I might add a new example documenting your use case (if it can be done).
Testing
The test feature flag enables the #[nvim_oxi::test] proc macro. This macro replaces the regular #[test] annotations and can be used to test a piece of code from within a Neovim instance using Rust's excellent testing framework.
For example:
use nvim_oxi::{self as oxi, api};
#[oxi::test]
fn set_get_del_var() {
api::set_var("foo", 42).unwrap();
assert_eq!(Ok(42), api::get_var("foo"));
assert_eq!(Ok(()), api::del_var("foo"));
}
Then cargo test will spawn a new Neovim process with an empty config, run that code and exit. There are a couple of gotchas:
-
after changing a piece of code,
cargo buildhas to be run before you can test that withcargo test; -
you cannot have two test functions with the same name, even if they belong to different modules. For example this won't work:
mod a {
#[nvim_oxi::test]
fn foo() {}
}
mod b {
#[nvim_oxi::test]
fn foo() {}
}
1 Dec 2, 2021
10 Dec 13, 2022
3 Apr 6, 2024
126 Jul 12, 2023
4 Feb 3, 2023
3.3k Jan 3, 2023
162 Dec 31, 2022
5 Aug 25, 2023
193 Dec 28, 2022
34 Mar 18, 2023
574 Jan 5, 2023
4 Aug 5, 2022
66 Apr 9, 2023
690 Jun 29, 2023
220 Dec 26, 2022
6 Dec 19, 2022
58 Dec 26, 2022
7 Mar 12, 2023