diff options
Diffstat (limited to 'runtime/doc/remote_plugin.txt')
| -rw-r--r-- | runtime/doc/remote_plugin.txt | 91 |
1 files changed, 45 insertions, 46 deletions
diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index ca7e763d1b..e5d1efcc96 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -14,12 +14,12 @@ Nvim support for remote plugins *remote-plugin* ============================================================================== 1. Introduction *remote-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 -remote plugins, coprocesses that have a direct communication channel(via +Extensibility is a primary goal of Nvim. Any programming language may be used +to extend nvim without changes to nvim itself. This is achieved with remote +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 +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. @@ -27,24 +27,24 @@ process. 2. Plugin hosts *remote-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. +directly with the high-level 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 +chosen 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 its registered plugins are required, keeping -Nvim startup as fast a possible despite the number of installed plugins/hosts. +taking care of most boilerplate involved in defining commands, autocmds, and +functions that are implemented over |msgpack-rpc| connections. Hosts are +loaded only when one of their registered plugins require it, keeping Nvim's +startup as fast as possible if many plugins/hosts are installed. ============================================================================== 3. Example *remote-plugin-example* The best way to learn about remote plugins is with an example, so let's see -how a very useless python plugin looks like. This plugin exports a command, a -function and an autocmd. The plugin is called 'Limit', and all it does is -limit the number of requests made to it. Here's the plugin source code: +what a python plugin looks like. This plugin exports a command, a function and +an autocmd. The plugin is called 'Limit', and all it does is limit the number +of requests made to it. Here's the plugin source code: > import neovim @@ -53,7 +53,7 @@ limit the number of requests made to it. Here's the plugin source code: 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() @@ -61,76 +61,75 @@ limit the number of requests made to it. Here's the plugin source code: '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 < -As can be seen, the plugin is implemented using pure python idioms(classes, -methods and decorators), the translation between these language-specific -idioms to vimscript occurs while the plugin manifest is being generated(see +As can be seen, the plugin is implemented using pure python idioms (classes, +methods, and decorators), the translation between these language-specific +idioms to vimscript occurs while the plugin manifest is being generated (see below). Notice that the exported command and autocmd are defined with the "sync" flag, which affects how Nvim calls the plugin: with "sync" the |rpcrequest()| function is used, which will block Nvim until the handler function returns a value. Without the "sync" flag, the call is made using a fire and forget -approach with |rpcnotify()|(return values or exceptions raised in the handler -function are ignored) +approach with |rpcnotify()| (return values or exceptions raised in the handler +function are ignored). To test the above plugin, it must be saved in "rplugin/python" in a -'runtimepath' directory(~/.nvim/rplugin/python/limit.py for example). -Then, the remote plugin manifest must be generated with -`:UpdateRemotePlugins`. +'runtimepath' directory (~/.nvim/rplugin/python/limit.py for example). Then, +the remote plugin manifest must be generated with `:UpdateRemotePlugins`. ============================================================================== -4. remote plugin manifest *remote-plugin-manifest* +4. Remote plugin manifest *remote-plugin-manifest* -Just installing remote plugins to "rplugin/{host}" isn't enough to -load them at startup. The `:UpdateRemotePlugins` command must be executed -every time a remote plugin is installed, updated, or deleted. +Just installing remote plugins to "rplugin/{host}" isn't enough for them to be +automatically loaded when required. The `:UpdateRemotePlugins` command must be +executed every time a remote plugin is installed, updated, or deleted. `:UpdateRemotePlugins` will generate the remote plugin manifest, a special vimscript file containing declarations for all vimscript entities (commands/autocommands/functions) defined by all remote plugins, with each entity associated with the host and plugin path. The manifest can be seen as a -generated extension to the user's vimrc(it even has the vimrc filename +generated extension to the user's vimrc (it even has the vimrc filename prepended). The manifest declarations are nothing but calls to the remote#host#RegisterPlugin function, which will take care of bootstrapping the host as soon as the -declared command, autocommand or function is used for the first time. +declared command, autocommand, or function is used for the first time. -The manifest generation step is necessary to keep editor startup fast in -situations where a user has remote plugins with different hosts. For -example, imagine a user that has three plugins, for python, java and .NET -hosts respectively, if we were to load all three plugins at startup, then -three language runtimes would also be spawned which could take seconds! +The manifest generation step is necessary to keep Nvim's startup fast in +situations where a user has remote plugins with different hosts. For example, +say a user has three plugins, for python, java and .NET hosts respectively. If +we were to load all three plugins at startup, then three language runtimes +would also be spawned which could take seconds! With the manifest, each host will only be loaded when required. Continuing -with the example, imagine the java plugin is a semantic completion engine for -java files, if it defines an BufEnter *.java autocommand then the java host -will only be spawned when java source files are loaded. - -If the explicit call to `:UpdateRemotePlugins` seems incovenient, try -to see it like this: Its a way to give IDE-like capabilities to nvim while -still keeping it a fast/lightweight editor for general use. It can also be -seen as an analogous to the |:helptags| facility. +with the example, say the java plugin is a semantic completion engine for java +source files. If it defines the autocommand "BufEnter *.java", then the java +host will only be spawned when files ending with ".java" are loaded. + +If the explicit call to `:UpdateRemotePlugins` seems incovenient, try to see +it like this: It's a way to give IDE-like capabilities to nvim while still +keeping it fast and lightweight for general use. It can also be seen as +analogous to the |:helptags| facility. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: |