mirror of
https://github.com/neovim/neovim.git
synced 2024-12-26 14:11:15 -07:00
593d63f1d5
- Improved wording in a few places for clarity - Various capitalization/grammar fixes - Change references to Neovim as 'editor' to 'Nvim' - Be consistent regarding utilization of vim's documentation features, e.g. unnamedclip -> |unnamedclip| - Reflowed all changed paragraphs accordingly - Add spaces before parentheses - Remove trailing whitespace - Standardize single spaces after periods. Vim's docs use two for the most part, but Nvim's use one mainly, so just follow Nvim's conventions
77 lines
3.7 KiB
Plaintext
77 lines
3.7 KiB
Plaintext
*nvim_provider.txt* For Nvim. {Nvim}
|
|
|
|
|
|
NVIM REFERENCE MANUAL by Thiago de Arruda
|
|
|
|
|
|
Nvim provider infrastructure *nvim-provider*
|
|
|
|
First of all, this document is meant to be read by developers interested in
|
|
contributing to the refactoring effort. If you are a normal user or plugin
|
|
developer looking to learn about Nvim |msgpack-rpc| infrastructure for
|
|
implementing plugins in other programming languages, see |external-plugin|.
|
|
For instructions on how to enable python plugins, see |nvim-python|. For
|
|
clipboard, see |nvim-clipboard|.
|
|
|
|
Instead of doing everything by itself, Nvim aims to simplify it's own
|
|
maintenance by delegating as much work as possible to external systems. But
|
|
some Vim components are too tightly coupled and in some cases the refactoring
|
|
work necessary to swap in-house implementations by code that integrates to
|
|
other systems is too great. Nvim provider infrastructure is a facility that
|
|
aims to make this task simpler.
|
|
|
|
To understand why the provider infrastructure is useful, let us consider two
|
|
examples of integration with external systems that are implemented in Vim and
|
|
are now decoupled from Nvim core as providers:
|
|
|
|
The first example is clipboard integration: On the original Vim source code,
|
|
clipboard functions account for more than 1k lines of C source code (and that
|
|
is just on ui.c). All to peform two tasks that are now accomplished with
|
|
simple shell commands such as xclip or pbcopy/pbpaste.
|
|
|
|
The other example is python scripting support: Vim has three files dedicated
|
|
to embed the python interpreter: if_python.c, if_python3.c and if_py_both.h.
|
|
Together these files sum about 9.5k lines of C source code. On Nvim, python
|
|
scripting is performed by an external host process that is running 2k sloc
|
|
python program.
|
|
|
|
In a perfect world, we would implement python and clipboard integration in
|
|
pure vimscript and without touching the C code. Unfortunately we can't achieve
|
|
these goals without severly compromising backwards compatibility with Vim.
|
|
Thats where providers comes to rescue.
|
|
|
|
In essence, this infrastructure a simple framework that simplifies the task of
|
|
calling vimscript from C code, making it simpler to rewrite C functions that
|
|
interact with external systems in pure vimscript. It is composed of two
|
|
functions in eval.c:
|
|
|
|
- eval_call_provider(name, method, arguments): Call a provider(name) method
|
|
with arguments
|
|
- eval_has_provider(name): Checks if a provider is implemented
|
|
|
|
What these functions do is simple:
|
|
|
|
- eval_call_provider will call the provider#(name)#Call function passing in
|
|
the method and arguments.
|
|
- eval_has_provider will return true if the provider#(name)#Call function is
|
|
implemented, and is called by the "has" vimscript function to check if
|
|
features are available.
|
|
|
|
The basic idea is that the provider#(name)#Call function should implement
|
|
integration with an external system, because calling shell commands and
|
|
|msgpack-rpc| clients (Nvim only) is easier to do in vimscript.
|
|
|
|
Now, back to the python example. Instead of modifying vimscript to allow for
|
|
the definition of lowercase functions and commands (for the |:python|,
|
|
|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would
|
|
break backwards compatibility with Vim, we implemented the
|
|
autoload/provider/python.vim script and the provider#python#Call function
|
|
that is only defined if an external python host is started successfully.
|
|
|
|
That works well with the `has('python')` expression (normally used by python
|
|
plugins) because if the python host isn't installed then the plugin will
|
|
"think" it is running in a Vim compiled without |+python| feature.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|