remote_plugin.txt (6114B)
1 *remote_plugin.txt* Nvim 2 3 4 NVIM REFERENCE MANUAL by Thiago de Arruda 5 6 7 Nvim support for remote plugins *remote-plugin* 8 9 Type |gO| to see the table of contents. 10 11 ============================================================================== 12 1. Introduction *remote-plugin-intro* 13 14 Extensibility is a primary goal of Nvim. Any programming language may be used 15 to extend Nvim without changes to Nvim itself. This is achieved with remote 16 plugins, coprocesses that have a direct communication channel (via |RPC|) with 17 the Nvim process. 18 19 Even though these plugins run in separate processes they can call, be called, 20 and receive events just as if the plugin's code were executed in the main 21 process. 22 23 ============================================================================== 24 2. Plugin hosts *remote-plugin-hosts* 25 26 While plugins can be implemented as arbitrary programs that communicate 27 directly with the high-level Nvim API and are called via |rpcrequest()| and 28 |rpcnotify()|, that is not the best approach. Instead, developers should first 29 check whether a plugin host is available for their chosen programming language. 30 31 Plugin hosts are programs that provide a high-level environment for plugins, 32 taking care of most boilerplate involved in defining commands, autocmds, and 33 functions implemented over |RPC| connections. Hosts are loaded only when one 34 of their registered plugins require it, keeping Nvim's startup as fast as 35 possible, even if many plugins/hosts are installed. 36 37 ============================================================================== 38 3. Example *remote-plugin-example* 39 40 The best way to learn about remote plugins is with an example, so let's see 41 what a Python plugin looks like. This plugin exports a command, a function, and 42 an autocmd. The plugin is called 'Limit', and all it does is limit the number 43 of requests made to it. Here's the plugin source code: >python 44 45 import pynvim 46 47 @pynvim.plugin 48 class Limit(object): 49 def __init__(self, vim): 50 self.vim = vim 51 self.calls = 0 52 53 @pynvim.command('Cmd', range='', nargs='*', sync=True) 54 def command_handler(self, args, range): 55 self._increment_calls() 56 self.vim.current.line = ( 57 'Command: Called %d times, args: %s, range: %s' % (self.calls, 58 args, 59 range)) 60 61 @pynvim.autocmd('BufEnter', pattern='*.py', eval='expand("<afile>")', 62 sync=True) 63 def autocmd_handler(self, filename): 64 self._increment_calls() 65 self.vim.current.line = ( 66 'Autocmd: Called %s times, file: %s' % (self.calls, filename)) 67 68 @pynvim.function('Func') 69 def function_handler(self, args): 70 self._increment_calls() 71 self.vim.current.line = ( 72 'Function: Called %d times, args: %s' % (self.calls, args)) 73 74 def _increment_calls(self): 75 if self.calls == 5: 76 raise Exception('Too many calls!') 77 self.calls += 1 78 < 79 80 As can be seen, the plugin is implemented using idiomatic Python (classes, 81 methods, and decorators). The translation between these language-specific 82 idioms to Vimscript occurs while the plugin manifest is being generated (see 83 the next section). 84 85 Notice that the exported command and autocmd are defined with the "sync" flag, 86 which affects how Nvim calls the plugin: with "sync" the |rpcrequest()| 87 function is used, which will block Nvim until the handler function returns a 88 value. Without the "sync" flag, the call is made using a fire and forget 89 approach with |rpcnotify()|, meaning return values or exceptions raised in the 90 handler function are ignored. 91 92 To test the above plugin, it must be saved in "rplugin/python" in a 93 'runtimepath' directory (~/.config/nvim/rplugin/python/limit.py for example). 94 Then, the remote plugin manifest must be generated with 95 |:UpdateRemotePlugins|. 96 97 ============================================================================== 98 4. Remote plugin manifest *remote-plugin-manifest* 99 *:UpdateRemotePlugins* 100 101 Just installing remote plugins to "rplugin/{host}" isn't enough for them to be 102 automatically loaded when required. You must execute |:UpdateRemotePlugins| 103 every time a remote plugin is installed, updated, or deleted. 104 105 |:UpdateRemotePlugins| generates the remote plugin manifest, a special 106 Vimscript file containing declarations for all Vimscript entities 107 (commands/autocommands/functions) defined by all remote plugins, with each 108 entity associated with the host and plugin path. 109 110 Manifest declarations are just calls to the `remote#host#RegisterPlugin` 111 function, which takes care of bootstrapping the host as soon as the declared 112 command, autocommand, or function is used for the first time. 113 114 The manifest generation step is necessary to keep Nvim's startup fast in 115 situations where a user has remote plugins with different hosts. For example, 116 say a user has three plugins, for Python, Java and .NET hosts respectively. If 117 we were to load all three plugins at startup, then three language runtimes 118 would also be spawned, which could take seconds! 119 120 With the manifest, each host will only be loaded when required. Continuing with 121 the example, say the Java plugin is a semantic completion engine for Java code. 122 If it defines the autocommand `BufEnter *.java`, then the Java host is spawned 123 only when Nvim loads a buffer matching "*.java". 124 125 If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see 126 it like this: It's a way to provide IDE capabilities in Nvim while still 127 keeping it fast and lightweight for general use. It's also analogous to the 128 |:helptags| command. 129 130 *$NVIM_RPLUGIN_MANIFEST* 131 Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file 132 named `rplugin.vim` at: 133 134 Unix ~ 135 $XDG_DATA_HOME/nvim/ or ~/.local/share/nvim/ 136 137 Windows ~ 138 $LOCALAPPDATA/nvim/ or ~/AppData/Local/nvim/ 139 140 vim:tw=78:ts=8:noet:ft=help:norl: