*remote_plugin.txt*    Nvim


		 NVIM REFERENCE MANUAL    by Thiago de Arruda


Nvim support for remote plugins			  *remote-plugin*

				      Type |gO| to see the table of contents.

==============================================================================
1. Introduction					    *remote-plugin-intro*

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 |RPC|) with
the Nvim process.

Even though these plugins run in separate processes they can call, be called,
and receive events just as if the plugin's code were executed in the main
process.

==============================================================================
2. Plugin hosts					    *remote-plugin-hosts*

While plugins can be implemented as arbitrary programs that communicate
directly with the high-level Nvim API and are called via |rpcrequest()| and
|rpcnotify()|, that is not the best approach. Instead, developers should first
check whether a plugin host is available for their chosen programming language.

Plugin hosts are programs that provide a high-level environment for plugins,
taking care of most boilerplate involved in defining commands, autocmds, and
functions implemented over |RPC| connections. Hosts are loaded only when one
of their registered plugins require it, keeping Nvim's startup as fast as
possible, even 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
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: >python

    import pynvim

    @pynvim.plugin
    class Limit(object):
        def __init__(self, vim):
            self.vim = vim
            self.calls = 0

        @pynvim.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))

        @pynvim.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))

        @pynvim.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):