alex/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-01-06 19:39:53 +10:00
Code Issues Packages Projects Releases Wiki Activity

doc/provider: cleanup

Browse Source 
- Move design/impl discussion to develop.txt
- Move clipboard notes to provider.txt
This commit is contained in:
Justin M. Keyes
2016-06-15 01:20:08 -04:00
parent c698ed0531
commit 7718f8f24c
4 changed files with 85 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
runtime/doc/autocmd.txt
View File

@@ -912,8 +912,7 @@ TermClose When a terminal buffer ends.
{Nvim} *TermOpen*
TermOpen When a terminal buffer is starting. This can
be used to configure the terminal emulator by
setting buffer variables.
See |nvim-terminal-emulator| for details.
setting buffer variables. |terminal-emulator|
*TermResponse*
TermResponse After the response to |t_RV| is received from
the terminal. The value of |v:termresponse|

47
runtime/doc/develop.txt
View File

@@ -122,7 +122,7 @@ include the kitchen sink... but you can use it for plumbing."
==============================================================================
2. Design decisions *design-decisions*
Naming the window
Window
The word "window" is commonly used for several things: A window on the screen,
the xterm window, a window inside Vim to view a buffer.
@@ -137,6 +137,51 @@ window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
Providers *dev-provider*
A goal of Nvim is to allow extension of the editor without special knowledge
in the core. But some Vim components are too tightly coupled; in those cases
a "provider" hook is exposed.
Consider two examples of integration with external systems that are
implemented in Vim and are now decoupled from Nvim core as providers:
1. In the Vim source code, clipboard logic accounts for more than 1k lines of
C source code (ui.c), to perform two tasks that are now accomplished with
shell commands such as xclip or pbcopy/pbpaste.
2. Python scripting support: Vim has three files dedicated to embedding 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. In contrast, Nvim Python
scripting is performed by an external host process implemented in ~2k lines
of Python.
Ideally we could implement Python and clipboard integration in pure vimscript
and without touching the C code. But this is infeasible without compromising
backwards compatibility with Vim; that's where providers help.
The provider framework helps call vimscript from C. It is composed of two
functions in eval.c:
- eval_call_provider(name, method, arguments): calls provider#(name)#Call
with the method and arguments.
- eval_has_provider(name): Checks if a provider is implemented. Returns true
if the provider#(name)#Call function is implemented. Called by |has()|
(vimscript) to check if features are available.
The provider#(name)#Call function implements integration with an external
system, because calling shell commands and |rpc| clients are easier to work
with in vimscript.
For example, the Python provider is implemented by the
autoload/provider/python.vim script; the provider#python#Call function is only
defined if a valid external Python host is found. 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 the |+python| feature.
RPC API
API client
remote plugin

61
runtime/doc/nvim_clipboard.txt
View File

@@ -1,61 +0,0 @@
*nvim_clipboard.txt* For Nvim. {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda
Clipboard integration for Nvim *clipboard*
1. Intro |clipboard-intro|
2. X11 selection mechanism |clipboard-x11|
==============================================================================
1. Intro *clipboard-intro*
Nvim has no direct connection to the system clipboard. Instead it is
accessible through a |provider| which transparently uses shell commands for
communicating with the clipboard.
Clipboard access is implicitly enabled if any of the following clipboard tools
are found in your `$PATH`.
- xclip
- xsel (newer alternative to xclip)
- pbcopy/pbpaste (Mac OS X)
- lemonade (for SSH) https://github.com/pocke/lemonade
- doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
The presence of a suitable clipboard tool implicitly enables the '+' and '*'
registers.
If you want to ALWAYS use the clipboard for ALL operations (as opposed
to interacting with the '+' and/or '*' registers explicitly), set the
following option:
>
set clipboard+=unnamedplus
<
See 'clipboard' for details and more options.
==============================================================================
2. X11 selection mechanism *clipboard-x11* *x11-selection*
The clipboard providers for X11 store text in what is known as "selections".
Selections are "owned" by an application, so when the application is closed,
the selection text is lost.
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).
*quoteplus* *quote+*
There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
`CLIPBOARD` is typically used in X11 applications for copy/paste operations
(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
generally inserted with the middle mouse button.
Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
selections, used for the '*' and '+' registers, respectively.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

90
runtime/doc/provider.txt
View File

@@ -4,71 +4,57 @@
NVIM REFERENCE MANUAL by Thiago de Arruda
Nvim provider infrastructure *provider*
Providers *provider*
This document is for developers. If you are a normal user or plugin developer
looking to learn about Nvim |rpc| for implementing plugins in other
programming languages, see |remote-plugin|. For instructions on how to enable
Python plugins, see |nvim-python|. For clipboard, see |clipboard|.
Nvim delegates some features to dynamic "providers".
Instead of doing everything by itself, Nvim aims to simplify its 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.
==============================================================================
Clipboard integration *clipboard*
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:
Nvim has no direct connection to the system clipboard. Instead it is
accessible through a |provider| which transparently uses shell commands for
communicating with the clipboard.
The first example is clipboard integration: in 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 perform two tasks that are now accomplished with
simple shell commands such as xclip or pbcopy/pbpaste.
Clipboard access is implicitly enabled if any of the following clipboard tools
are found in your `$PATH`.
The other example is Python scripting support: Vim has three files dedicated to
embedding 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.
- xclip
- xsel (newer alternative to xclip)
- pbcopy/pbpaste (Mac OS X)
- lemonade (for SSH) https://github.com/pocke/lemonade
- doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
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 severely compromising backwards compatibility with Vim.
That's where providers come to the rescue.
The presence of a suitable clipboard tool implicitly enables the '+' and '*'
registers.
In essence, this infrastructure is 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:
If you want to ALWAYS use the clipboard for ALL operations (as opposed
to interacting with the '+' and/or '*' registers explicitly), set the
following option:
>
set clipboard+=unnamedplus
<
See 'clipboard' for details and more options.
- eval_call_provider(name, method, arguments): Call a provider(name) method
with arguments
- eval_has_provider(name): Checks if a provider is implemented
==============================================================================
X11 selection mechanism *clipboard-x11* *x11-selection*
What these functions do is simple:
The clipboard providers for X11 store text in what is known as "selections".
Selections are "owned" by an application, so when the application is closed,
the selection text is lost.
- 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 contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).
The basic idea is that the provider#(name)#Call function should implement
integration with an external system, because calling shell commands and |rpc|
clients (Nvim only) is easier to do in vimscript.
*quoteplus* *quote+*
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.
There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
`CLIPBOARD` is typically used in X11 applications for copy/paste operations
(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
generally inserted with the middle mouse button.
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.
Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
selections, used for the '*' and '+' registers, respectively.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: