Implements support for Neovim remote plugins written in Elixir.
- Neovim >= 1.6-dev
- Elixir >= 1.3
Install the host archive, we will use it to build the host locally.
$ mix archive.install https://github.com/dm1try/nvim/releases/download/v0.4.2/nvim.ez
Build and install the host by running nvim.install
and providing the path to nvim config(~/.config/nvim
by default on linux systems)
$ mix nvim.install /path/to/nvim/config
Same as the install step but if you have any problem try to remove the host at first:
mix nvim.remove /path/to/nvim/config
mix nvim.install /path/to/nvim/config
Currently, each time you somehow update remote plugins you should run :UpdateElixirPlugins
nvim command.
See :h remote-plugin-manifest
for the clarification why the manifest is needed(generally, it saves the neovim startup time if remote plugins are installed).
+--------------------------+
+--------+ MsgPack | +---------+ |
| | RPC | +------+ | | |
| Neovim <---------> | Host <-----> Plugins | |
| | | +------+ | | |
+--------+ | +---------+ |
+--------------------------+
Host supports two types of plugins:
-
Scripts (an elixir script that usually contains simple logic and does not depend on other libs/does not need the versioning/etc).
-
Applications (an OTP application that is implemented as part of host umbrella project). You can find more information about umbrella projects here.
Host with plugins lives in rplugin/elixir
neovim config directory.
Script plugin name must have postfix plugin
in his name.
Example
my_plugin.exs
Typical files tree for such dir:
~/.config/nvim/rplugin/elixir
├── scripts <~ scripts
├── apps <~ applications AKA "precompiled plugins"
└── mix.exs
on_event
(better known as autocmd
for vim users) defines the callback that triggered by editor when some event
happened. Run :h autocmd-events
for the list of events.
on_event :vim_enter do
Logger.info("the editor is ready")
end
function
defines the vim function
function wrong_sum(left, right) do
left - right
end
use it in the editor :echo WrongSum(1,2)
command
defines the command.
command just_echo do
NVim.Session.nvim_command("echo 'from remote plugin'")
end
use it in the editor :JustEcho
Only single param can be defined for a command.
This param holds an array of strings provided on the command call.
Elixir OptionParser
is good choice here.
In the latest example we used nvim_command
method which is part of Neovim remote API.
In the examples below we asume that we import NVim.Session
in context of plugin.
Each plugin is GenServer. So you can share the state between all actions while the plugin is running:
def init(_args) do
{:ok, %{move_count: 0}}
end
on_event :cursor_moved do
state = %{state | move_count: state.move_count + 1}
end
command show_moves_count do
moves_info = "Current moves: #{state.move_count}"
nvim_command("echo '#{moves_info}'")
end
NOTE: you cannot assing the state in inner scopes(
if/case/with/etc
). You should return the value from the scope and then assing it to the state in root scope.
Any vim value can be pre-evaluated before the action will be triggered:
on_event :cursor_hold_i,
pre_evaluate: %{
"expand('cWORD')" => word_under_cursor
}
do
if word_under_cursor == "Elixir" do
something()
end
end
"Hello" from plug:
# ~/.config/nvim/rplugin/elixir/scripts/my_plugin.exs
defmodule MyPlug do
use NVim.Plugin
command hello_from_plug do
NVim.Session.nvim_command "echo 'hello'"
end
end
ElixirHostLog
opens the host log.
Log severety level can be changed in the host config.
~/.config/nvim/rplugin/elixir/apps/host/config/config.exs
is default path on linux
ElixirReloadScript
reloads running script.
This works only for the reloading an implementation of already defined command/function/event. This means if you add/remove some definition or change its option(
pre_evaluate
for example) you should restart the editor.