mirror of
https://github.com/neovim/neovim.git
synced 2025-10-02 07:58:35 +00:00
105 lines
4.4 KiB
Plaintext
105 lines
4.4 KiB
Plaintext
*external_plugin.txt* For Nvim. {Nvim}
|
|
|
|
|
|
NVIM REFERENCE MANUAL by Thiago de Arruda
|
|
|
|
|
|
Nvim support for external plugins *external-plugin*
|
|
|
|
1. Introduction |external-plugin-intro|
|
|
2. Plugin Hosts |external-plugin-hosts|
|
|
3. Example |external-plugin-example|
|
|
|
|
==============================================================================
|
|
1. Introduction *external-plugin-intro*
|
|
|
|
A big Nvim goal is to allow extensibility in arbitrary programming languages
|
|
without requiring direct support from the editor. This is achieved with
|
|
external plugins, coprocesses that have a direct communication channel(via
|
|
|msgpack-rpc|) with the Nvim process.
|
|
|
|
Even though these plugins are running in separate processes, they can call, be
|
|
called, and receive events just as if the code was being executed in the main
|
|
process.
|
|
|
|
==============================================================================
|
|
2. Plugin Hosts *external-plugin-hosts*
|
|
|
|
While plugins can be implemented as arbitrary programs that communicate
|
|
directly with Nvim API and are called via |rpcrequest()| and |rpcnotify()|,
|
|
that is not the best approach available. Instead, developers should first
|
|
check if a plugin host implementation is available for their favorite
|
|
programming language.
|
|
|
|
Plugin hosts are programs that provide a high level environment for plugins,
|
|
and also take care of most boilerplate involved in defining commands, autocmds
|
|
and functions that are implemented over msgpack-rpc connections. They are
|
|
loaded the first time one of it's registered plugins are required, keeping
|
|
Nvim startup as fast a possible despite the number of installed plugins/hosts.
|
|
|
|
==============================================================================
|
|
3. Example *external-plugin-example*
|
|
|
|
The best way to learn how to create external plugins is with an example, so
|
|
let's see how to implement a very useless python plugin that exports a
|
|
command, a function and an autocmd(requires configuration detailed in
|
|
|nvim-python| to work).
|
|
|
|
The plugin is called 'Limit', and all it does is limit the number of "calls"
|
|
made to it. Here's the plugin source code:
|
|
>
|
|
import neovim
|
|
|
|
@neovim.plugin
|
|
class Limit(object):
|
|
def __init__(self, vim):
|
|
self.vim = vim
|
|
self.calls = 0
|
|
|
|
@neovim.command('Cmd', range='', nargs='*', sync=True)
|
|
def command_handler(self, args, range):
|
|
self._increment_calls()
|
|
self.vim.current.line = (
|
|
'Command: Called %d times, args: %s, range: %s' % (self.calls,
|
|
args,
|
|
range))
|
|
|
|
@neovim.autocmd('BufEnter', pattern='*.py', eval='expand("<afile>")',
|
|
sync=True)
|
|
def autocmd_handler(self, filename):
|
|
self._increment_calls()
|
|
self.vim.current.line = (
|
|
'Autocmd: Called %s times, file: %s' % (self.calls, filename))
|
|
|
|
@neovim.function('Func')
|
|
def function_handler(self, args):
|
|
self._increment_calls()
|
|
self.vim.current.line = (
|
|
'Function: Called %d times, args: %s' % (self.calls, args))
|
|
|
|
def _increment_calls(self):
|
|
if self.calls == 5:
|
|
raise Exception('Too many calls!')
|
|
self.calls += 1
|
|
<
|
|
|
|
This code needs to be saved to "external/python/limit.py" in a runtime
|
|
directory(~/.nvim/plugin/external/python/limit.py for example).
|
|
|
|
As can be seen, the plugin is implemented using pure python idioms(classes,
|
|
methods and decorators). It is the host's responsibility to translate
|
|
language-specific idioms to vimscript entities. Notice that the exported
|
|
command and autocmd are defined with the "sync" flag, which tells Nvim to call
|
|
it using |rpcrequest()|. Since the "Func" doesn't set "sync", it will be
|
|
called using |rpcnotify()|.
|
|
|
|
Just installing the plugin to ~/.nvim/plugin/external/python/limit.py won't
|
|
make Nvim load it at startup. That is because external plugins are loaded
|
|
only when required, and for that Nvim must be fed with information about
|
|
installed external plugins with the `:UpdateExternalPlugins` command(must be
|
|
called whenever plugins are updated, this is analogous to the |:helptags|
|
|
command but for external plugins).
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|