diff options
Diffstat (limited to 'runtime/doc/external_plugin.txt')
| -rw-r--r-- | runtime/doc/external_plugin.txt | 104 |
1 files changed, 0 insertions, 104 deletions
diff --git a/runtime/doc/external_plugin.txt b/runtime/doc/external_plugin.txt deleted file mode 100644 index 3f7772c906..0000000000 --- a/runtime/doc/external_plugin.txt +++ /dev/null @@ -1,104 +0,0 @@ -*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: |