nvim-oxi

nvim-oxi provides safe and idiomatic Rust bindings to the Neovim API. Unlike traditional plugins that use RPC channels (which require MessagePack serialization and limit features like callbacks), nvim-oxi uses Rust's Foreign Function Interface (FFI) to hook directly into Neovim's C code. This provides feature parity with 'in-process' Lua plugins and avoids the overhead of an extra IO layer.

Key advantages include:

• Access to the Rust ecosystem: Use crates for networking, IO, serialization, and concurrency.
• Fully typed API: Function fields and callback arguments are checked at compile-time, allowing for faster iteration via cargo check.

To start a new plugin, create a library crate and configure Cargo.toml to produce a dynamic library (cdylib) and include nvim-oxi as a dependency.

1. Create the crate:

   cargo new --lib {your_plugin}

2. Update Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
nvim-oxi = "0.3"

3. Annotate your entry point in lib.rs using the #[nvim_oxi::plugin] macro:

// lib.rs

#[nvim_oxi::plugin]
fn foo() -> i32 {
    42
}

To run integration tests, you must place them in a separate cdylib crate and use the following build.rs configuration to ensure the environment is set up correctly for the Neovim testing harness.

// build.rs
fn main() -> Result<(), nvim_oxi::tests::BuildError> {
    nvim_oxi::tests::build()
}

macOS users must configure the Rust linker to treat FFI functions provided by nvim-oxi as dynamic lookups. Create a .cargo/config file in your project root with the following settings:

[target.x86_64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]

[target.aarch64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]

By enabling the test feature, you can use the #[nvim_oxi::test] macro. This replaces the standard #[test] macro and allows you to run Rust tests from within a spawned Neovim instance. When cargo test is executed, it spawns a new Neovim process using the nvim binary found in your $PATH, runs your code, and then exits.

Limitations:

• You cannot have two tests with the same name in the same crate, even if they are in different modules.
• Integration tests must reside in a separate cdylib crate.

use nvim_oxi::api;

#[nvim_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"));
}

After building your plugin with cargo build {--release}, follow these steps to load it into Neovim:

1. Locate artifacts: Find the compiled library in target/debug or target/release.

   • Linux: libfoo.so
   • macOS: libfoo.dylib
   • Windows: foo.dll

2. Prepare Lua directory: Create a directory named lua and place the library inside it. Rename the file to match Lua naming conventions:

   • Linux: foo.so
   • macOS: foo.so
   • Windows: foo.dll (no renaming required)

3. Update runtimepath: Add the parent directory of the lua folder to Neovim's runtimepath: :set rtp+=~/foobar (assuming the path is ~/foobar/lua)

4. Load in Lua: Use require to load the plugin. It will return the output of your annotated entry point function.

print(require("foo")) -- prints 42

print(require("foo")) -- prints `42`

The nvim-oxi crate is organized into several functional modules that provide different levels of access to Neovim:

• api: Bindings to the official Neovim C API.
• libuv: (Requires libuv feature) Bindings to the Neovim event loop powered by libuv, accessible via vim.loop in Lua.
• lua: Low-level Rust bindings to LuaJIT, the Lua engine used by Neovim.
• mlua: (Requires mlua feature) Safe Lua bindings via the mlua crate, including the ability to retrieve the active Lua instance.
• types: Common Neovim-related types and string utilities.

The api crate exports several modules that provide access to Neovim's core functionality. Key exported modules include:

• autocmd: Autocommand management.
• buffer: Buffer-related operations and the Buffer object.
• command: Command execution.
• extmark: Extended marks (extmarks) management.
• options: Neovim option manipulation.
• tabpage: Tabpage-related operations and the TabPage object.
• types: Core Neovim types.
• window: Window-related operations and the Window object.
• vim: Core vim table bindings.
• vimscript: Vimscript execution capabilities.

The nvim-oxi API provides bindings to the Neovim API. To make the API more idiomatic, it follows two main transformation rules:

1. Prefix Removal: All functions have the leading nvim_ prefix removed. For example, nvim_get_current_buf is exposed as get_current_buf.
2. Object-Oriented Methods: Functions that originally started with nvim_buf_*, nvim_win_*, or nvim_tabpage_* are implemented as methods on the Buffer, Window, and TabPage objects respectively, rather than being standalone functions.

The Object struct is the core representation of any valid Neovim type in the nvim-oxi ecosystem. It is a C-compatible (#[repr(C)]) container that holds either a primitive value or a reference to a Lua object. It is used to bridge data between Rust and Neovim/Lua.

Key characteristics:

• Type Safety: It uses an ObjectKind enum to track the underlying data type.
• Memory Management: It handles ownership for complex types like String, Array, and Dictionary using ManuallyDrop to ensure correct cleanup when the Object is dropped.
• Conversion: It implements From for most common Rust primitives (bool, integer, float, string, etc.), making it easy to wrap values.

The String type in nvim-oxi is a binding to Neovim's internal string representation. It differs from Rust's standard String in several critical ways:

• Not guaranteed to be valid UTF-8: It can contain arbitrary byte sequences.
• Null bytes: It can contain null bytes within the sequence.
• Null-terminated: The underlying buffer is null-terminated.

When working with this type, use to_str() if you need a validated UTF-8 slice, or to_string_lossy() if you want to convert it to a standard Rust String while replacing invalid UTF-8 sequences with the replacement character �.