1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
*develop.txt*
NVIM REFERENCE MANUAL
Development of Nvim. *development*
1. Design goals |design-goals|
2. Design decisions |design-decisions|
Nvim is open source software. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
See src/nvim/README.md for a high-level overview of the source code:
https://github.com/neovim/neovim/blob/master/src/nvim/README.md
==============================================================================
1. Design goals *design-goals*
Most important things come first (roughly).
Note that quite a few items are contradicting. This is intentional. A
balance must be found between them.
NVIM IS... IMPROVED *design-improved*
The IMproved bits of Vim should make it a better Vi, without becoming a
completely different editor. Extensions are done with a "Vi spirit".
- Use the keyboard as much as feasible. The mouse requires a third hand,
which we don't have. Many terminals don't have a mouse.
- When the mouse is used anyway, avoid the need to switch back to the
keyboard. Avoid mixing mouse and keyboard handling.
- Add commands and options in a consistent way. Otherwise people will have a
hard time finding and remembering them. Keep in mind that more commands and
options will be added later.
- A feature that people do not know about is a useless feature. Don't add
obscure features, or at least add hints in documentation that they exist.
- Minimize using CTRL and other modifiers, they are more difficult to type.
- There are many first-time and inexperienced Vim users. Make it easy for
them to start using Vim and learn more over time.
- There is no limit to the features that can be added. Selecting new features
is one based on (1) what users ask for, (2) how much effort it takes to
implement and (3) someone actually implementing it.
NVIM IS... MULTI PLATFORM *design-multi-platform*
Vim tries to help as many users on as many platforms as possible.
- Support many kinds of terminals. The minimal demands are cursor positioning
and clear-screen. Commands should only use key strokes that most keyboards
have. Support all the keys on the keyboard for mapping.
- Support many platforms. A condition is that there is someone willing to do
Vim development on that platform, and it doesn't mean messing up the code.
- Support many compilers and libraries. Not everybody is able or allowed to
install another compiler or GUI library.
- People switch from one platform to another, and from GUI to terminal
version. Features should be present in all versions, or at least in as many
as possible with a reasonable effort. Try to avoid that users must switch
between platforms to accomplish their work efficiently.
- That a feature is not possible on some platforms, or only possible on one
platform, does not mean it cannot be implemented. [This intentionally
contradicts the previous item, these two must be balanced.]
NVIM IS... WELL DOCUMENTED *design-documented*
- A feature that isn't documented is a useless feature. A patch for a new
feature must include the documentation.
- Documentation should be comprehensive and understandable. Using examples is
recommended.
- Don't make the text unnecessarily long. Less documentation means that an
item is easier to find.
- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
differences from Vim. The {Nvim} annotation is also available
to mark a specific feature. No other distinction is necessary.
- If a feature is removed, delete its doc entry and move its tag to
|vim_diff.txt|.
NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
Using Vim must not be a big attack on system resources. Keep it small and
fast.
- Computers are becoming faster and bigger each year. Vim can grow too, but
no faster than computers are growing. Keep Vim usable on older systems.
- Many users start Vim from a shell very often. Startup time must be short.
- Commands must work efficiently. The time they consume must be as small as
possible. Useful commands may take longer.
- Don't forget that some people use Vim over a slow connection. Minimize the
communication overhead.
- Vim is a component among other components. Don't turn it into a massive
application, but have it work well together with other programs.
NVIM IS... MAINTAINABLE *design-maintain*
- The source code should not become a mess. It should be reliable code.
- Use comments in a useful way! Quoting the function name and argument names
is NOT useful. Do explain what they are for.
- Porting to another platform should be made easy, without having to change
too much platform-independent code.
- Use the object-oriented spirit: Put data and code together. Minimize the
knowledge spread to other parts of the code.
NVIM IS... FLEXIBLE *design-flexible*
Vim should make it easy for users to work in their preferred styles rather
than coercing its users into particular patterns of work. This can be for
items with a large impact or for details. The defaults are carefully chosen
such that most users will enjoy using Vim as it is. Commands and options can
be used to adjust Vim to the desire of the user and its environment.
NVIM IS... NOT *design-not*
Nvim is not an operating system; instead it should be composed with other
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
include the kitchen sink... but you can use it for plumbing."
==============================================================================
2. Design decisions *design-decisions*
JARGON *dev-jargon*
API client ~
All external UIs and remote plugins (as opposed to regular Vim plugins) are
"clients" in general; but we call something an "API client" if its purpose is
to abstract or wrap the RPC API for the convenience of other applications
(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
using an HTTP client like curl, but boto3 wraps that in a convenient python
interface). For example, the Nvim lua-client is an API client:
https://github.com/neovim/lua-client
Host ~
A plugin "host" is both a client (of the Nvim API) and a server (of an
external platform, e.g. python). It is a remote plugin that hosts other
plugins.
Remote plugin ~
Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
process and communicates with Nvim via the |api|.
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.
To avoid confusion, other items that are sometimes called window have been
given another name. Here is an overview of the related items:
screen The whole display. For the GUI it's something like 1024x768
pixels. The Vim shell can use the whole screen or part of it.
shell The Vim application. This can cover the whole screen (e.g.,
when running in a console) or part of it (xterm or GUI).
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 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.
API *dev-api*
Use this pattern to name new API functions:
nvim_{thing}_{action}_{arbitrary-qualifiers}
If the function acts on an object then {thing} is the name of that object
(e.g. "buf" or "win"). If the function operates in a "global" context then
{thing} is usually omitted (but consider "namespacing" your global operations
with a {thing} that groups functions under a common concept).
Use existing common {action} names if possible:
add Append to, or insert into, a collection
get Get a thing (or subset of things by some query)
set Set a thing
del Delete a thing (or group of things)
list Get all things
Use consistent names for {thing} in all API functions. E.g. a buffer is called
"buf" everywhere, not "buffer" in some places and "buf" in others.
Example: `nvim_get_current_line` acts on the global editor state; the common
{action} "get" is used but {thing} is omitted.
Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first
parameter) and uses the common {action} "add".
Example: `nvim_list_bufs` operates in a global context (first parameter is
_not_ a Buffer). The common {action} "list" indicates that it lists all
bufs (plural) in the global context.
vim:tw=78:ts=8:ft=help:norl:
|
