nvim-oxi 0.6.0

Rust bindings to all things Neovim
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# Examples

## [`api`](./api.rs)

Shows how to use the `api` module to create commands, set keymaps and
manipulate floating windows.

## [`calc`](./calc.rs)

Shows how to expose your plugin's core functions to Lua.

```lua
local calc = require("calc")

-- All the following commands will print `42` in the Neovim message area.

print(calc.add(1, 41))
print(calc.multiply(2, 21))

print(calc.compute(function(a, b) return a + b; end, 1, 41))
print(calc.compute(function(a, b) return a * b; end, 2, 21))
```

## [`mechanic`](./mechanic.rs)

Shows how to deserialize Lua tables into Rust objects using
[`serde`](https://serde.rs).

```lua
local mechanic = require("mechanic")

local fixed = mechanic.fix({
  manufacturer = "Tesla",
  miles = 69420,
  works = false,
  problem = "kills_pedestrians",
})

assert(fixed.works)
assert(fixed.problem == nil)
```

## [`mlua`](./mlua.rs)

Shows how to integrate `nvim-oxi` with the
[`mlua`](https://github.com/khvzak/mlua) crate.

## [`libuv`](./libuv.rs)

Shows how to use the `nvim_oxi::libuv` module to trigger a callback registered
on the Neovim thread from other threads.

# Crate setup

The first step is to create a new library crate with `cargo new --lib
{your_plugin}` and edit the generated `Cargo.toml` to include:

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

[dependencies]
nvim-oxi = "0.3"
```

Next, in `lib.rs` we'll annotate the entry point of the plugin with the
`#[nvim_oxi::plugin]` macro:

```rust
// lib.rs

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

macOS users will also need to set a few linker arguments to tell the Rust
linker that the FFI functions `nvim-oxi` links to will only be available at
runtime. A possible way to do this is to create a `.cargo/config` file with the
following content:

```toml
[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",
]
```

After building the crate with `cargo build {--release}`, cargo will place the
compiled artifacts in `target/debug` or `target/release` depending on whether
you built a debug or release version of the crate. If the package name
specified in `Cargo.toml` is `"foo"`, the library will be named:

  - `libfoo.so` on Linux;
  - `libfoo.dylib` on macOS;
  - `foo.dll` on Windows.

Next, we need to tell Neovim where to load the plugin from. Create a new
directory named `lua` and place the compiled library inside it, renaming it to

  - `foo.so` on Linux;
  - `foo.so` on macOS;
  - `foo.dll` on Windows (i.e. no renaming).

Now open Neovim and add *the parent directory* of `lua` to the
[runtimepath](https://neovim.io/doc/user/options.html#'runtimepath'), for
example with `:set rtp+=~/foobar`, assuming `lua` is in `~/foobar/lua`.

And we're done. You can now call the `require` function to load the plugin just
like any other Lua plugin, which will return the output of the `foo()` function
defined in `lib.rs`:

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