Attribute Macro plugin

#[plugin]

Marks a function as the entrypoint of the plugin.

The function wrapped by this macro will be called by Neovim when the user loads the plugin by passing its name to the require function. It can return any type that implements the Pushable trait, and the value will be returned on the Lua side by require.

Examples

Let’s say your crate only consists of this single lib.rs file:

// lib.rs

#[nvim_oxi::plugin]
fn my_plugin() -> u32 {
    42
}

Once the crate is compiled and the resulting dynamic library is placed under lua/my_plugin.{so|dylib|dll} somewhere in Neovim’s runtimepath, it can be loaded with:

local ret = require("my_plugin")
assert(ret == 42)

Attributes

nvim-oxi

The code generated by this macro includes calls to functions defined in the nvim-oxi crate, which is expected to be in scope under ::nvim_oxi. This can cause problems if you renamed the crate in your Cargo.toml or if it’s re-exported from another crate.

In these cases, you can use the nvim_oxi attribute to specify the path to nvim-oxi.

For example, let’s say your crate has a single dependency called foo whose whose lib.rs re-exports nvim-oxi as nvim:

// foo's lib.rs
pub use nvim_oxi as nvim;

Doing this would generate a compilation error because nvim_oxi is not in scope:

#[foo::nvim::plugin]
fn my_plugin() {}

To fix this, you can use the nvim_oxi attribute to specify the correct path:

#[foo::nvim::plugin(nvim_oxi = foo::nvim)]
fn my_plugin() {}