opensourcemirror
/
neovim
mirror of https://github.com/neovim/neovim.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc 

- develop.txt is for design/guidelines; architecture/concepts should
  live elsewhere (currently src/nvim/README.md)
- move dev-jargon to intro.txt
- replace https://neovim.io/community (deprecated) with
  https://neovim.io/#chat
- <Cmd> avoids CmdlineEnter/Leave
  https://github.com/vim/vim/issues/2889
This commit is contained in:
Justin M. Keyes 2018-11-16 02:00:04 +01:00
parent 3348eea429
commit 30857030e8
12 changed files with 134 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -52,9 +52,9 @@ jobs:
- stage: normal builds
os: linux
compiler: clang-4.0
# Use Lua so that ASAN can test our embedded Lua support. 8fec4d53d0f6
env: >
CLANG_SANITIZER=ASAN_UBSAN
# Use Lua so that ASAN can test our embedded Lua support. 8fec4d53d0f6
CMAKE_FLAGS="$CMAKE_FLAGS -DPREFER_LUA=ON"
ASAN_SYMBOLIZE=asan_symbolize-4.0
- os: linux

2
man/nvim.1
View File

@ -24,7 +24,7 @@ Start
.Nm
followed by any number of options and/or files:
.Pp
.Dl nvim [options] [filelist]
.Dl nvim [options] [file ...]
.Pp
Commands in
.Nm

96
runtime/doc/api.txt
View File

@ -478,6 +478,9 @@ nvim_err_writeln({str}) *nvim_err_writeln()*
nvim_list_bufs() *nvim_list_bufs()*
Gets the current list of buffer handles
Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
|nvim_buf_is_loaded()| to check if a buffer is loaded.
Return: ~
List of buffer handles
@ -529,6 +532,30 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
Parameters: ~
{tabpage} Tabpage handle
nvim_create_namespace({name}) *nvim_create_namespace()*
create a new namespace, or get one with an exisiting name
Namespaces are currently used for buffer highlighting and
virtual text, see |nvim_buf_add_highlight| and
|nvim_buf_set_virtual_text|.
Namespaces can have a name of be anonymous. If `name` is a
non-empty string, and a namespace already exists with that
name,the existing namespace id is returned. If an empty string
is used, a new anonymous namespace is returned.
Parameters: ~
{name} Name of the namespace or empty string
Return: ~
the namespace id
nvim_get_namespaces() *nvim_get_namespaces()*
Get existing named namespaces
Return: ~
dict that maps from names to namespace ids.
nvim_subscribe({event}) *nvim_subscribe()*
Subscribes to event broadcasts
@ -1082,35 +1109,36 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
(row, col) tuple
*nvim_buf_add_highlight()*
nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
{col_start}, {col_end})
Adds a highlight to buffer.
Useful for plugins that dynamically generate highlights to a
buffer (like a semantic highlighter or linter). The function
adds a single highlight to a buffer. Unlike matchaddpos()
adds a single highlight to a buffer. Unlike |matchaddpos()|
highlights follow changes to line numbering (as lines are
inserted/removed above the highlighted line), like signs and
marks do.
`src_id` is useful for batch deletion/updating of a set of
highlights. When called with `src_id = 0`, an unique source id
is generated and returned. Successive calls can pass that
`src_id` to associate new highlights with the same source
group. All highlights in the same group can be cleared with
`nvim_buf_clear_highlight`. If the highlight never will be
manually deleted, pass `src_id = -1`.
Namespaces are used for batch deletion/updating of a set of
highlights. To create a namespace, use |nvim_create_namespace|
which returns a namespace id. Pass it in to this function as
`ns_id` to add highlights to the namespace. All highlights in
the same namespace can then be cleared with single call to
|nvim_buf_clear_highlight|. If the highlight never will be
deleted by an API call, pass `ns_id = -1`.
If `hl_group` is the empty string no highlight is added, but a
new `src_id` is still returned. This is useful for an external
plugin to synchrounously request an unique `src_id` at
initialization, and later asynchronously add and clear
highlights in response to buffer changes.
As a shorthand, `ns_id = 0` can be used to create a new
namespace for the highlight, the allocated id is then
returned. If `hl_group` is the empty string no highlight is
added, but a new `ns_id` is still returned. This is supported
for backwards compatibility, new code should use
|nvim_create_namespace| to create a new empty namespace.
Parameters: ~
{buffer} Buffer handle
{src_id} Source group to use or 0 to use a new group,
or -1 for ungrouped highlight
{ns_id} namespace to use or -1 for ungrouped
highlight
{hl_group} Name of the highlight group to use
{line} Line to highlight (zero-indexed)
{col_start} Start of (byte-indexed) column range to
@ -1119,10 +1147,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
highlight, or -1 to highlight to end of line
Return: ~
The src_id that was used
The ns_id that was used
*nvim_buf_clear_highlight()*
nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end})
Clears highlights and virtual text from a given source id and
range of lines
@ -1131,15 +1159,13 @@ nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
Parameters: ~
{buffer} Buffer handle
{src_id} Highlight source group to clear, or -1 to
clear all.
{ns_id} Namespace to clear, or -1 to clear all.
{line_start} Start of range of lines to clear
{line_end} End of range of lines to clear (exclusive)
or -1 to clear to end of file.
*nvim_buf_set_virtual_text()*
nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
{opts})
nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
Set the virtual text (annotation) for a buffer line.
By default (and currently the only option) the text will be
@ -1149,13 +1175,22 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
the right of the ordinary text, this will contain the |lcs-
eol| char if set, otherwise just be a space.
The same src_id can be used for both virtual text and
highlights added by nvim_buf_add_highlight. Virtual text is
cleared using nvim_buf_clear_highlight.
Namespaces are used to support batch deletion/updating of
virtual text. To create a namespace, use
|nvim_create_namespace|. Virtual text is cleared using
|nvim_buf_clear_highlight|. The same `ns_id` can be used for
both virtual text and highlights added by
|nvim_buf_add_highlight|, both can then be cleared with a
single call to |nvim_buf_clear_highlight|. If the virtual text
never will be cleared by an API call, pass `src_id = -1`.
As a shorthand, `ns_id = 0` can be used to create a new
namespace for the virtual text, the allocated id is then
returned.
Parameters: ~
{buffer} Buffer handle
{src_id} Source group to use or 0 to use a new group, or
{ns_id} Namespace to use or 0 to create a namespace, or
-1 for a ungrouped annotation
{line} Line to annotate with virtual text (zero-
indexed)
@ -1166,7 +1201,7 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
{opts} Optional parameters. Currently not used.
Return: ~
The src_id that was used
The ns_id that was used
==============================================================================
@ -1181,6 +1216,13 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()*
Return: ~
Buffer handle
nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
Sets the current buffer in a window, without side-effects
Parameters: ~
{window} Window handle
{buffer} Buffer handle
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
Gets the cursor position in the window

18
runtime/doc/autocmd.txt
View File

@ -526,20 +526,18 @@ CmdlineChanged After a change was made to the text in the
command line. Be careful not to mess up
the command line, it may cause Vim to lock up.
*CmdlineEnter*
CmdlineEnter After moving the cursor to the command line,
where the user can type a command or search
string.
<afile> is set to a single character,
indicating the type of command-line.
|cmdline-char|
CmdlineEnter After entering the command-line (including
non-interactive use of ":" in a mapping: use
|<Cmd>| instead to avoid this).
<afile> is set to the |cmdline-char|.
Sets these |v:event| keys:
cmdlevel
cmdtype
*CmdlineLeave*
CmdlineLeave Before leaving the command line.
<afile> is set to a single character,
indicating the type of command-line.
|cmdline-char|
CmdlineLeave Before leaving the command-line (including
non-interactive use of ":" in a mapping: use
|<Cmd>| instead to avoid this).
<afile> is set to the |cmdline-char|.
Sets these |v:event| keys:
abort (mutable)
cmdlevel

48
runtime/doc/develop.txt
View File

@ -6,19 +6,20 @@
Development of Nvim *development*
Nvim is open source software. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
This reference describes design constraints and guidelines, for developing
Nvim applications or Nvim itself.
Architecture and internal concepts are covered in src/nvim/README.md
See src/nvim/README.md for an overview of the source code.
Nvim is free and open source. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
Type |gO| to see the table of contents.
==============================================================================
Design goals *design-goals*
Most important things come first (roughly).
Note that some items conflict; this is intentional. A balance must be found.
Most important things come first (roughly). Some items conflict; this is
intentional. A balance must be found.
NVIM IS... IMPROVED *design-improved*
@ -81,41 +82,6 @@ include the kitchen sink... but it's good for plumbing."
Developer guidelines *dev*
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.
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.
frame Windows are kept in a tree of frames. Each frame contains
a column, row, or window ("leaf" frame).
PROVIDERS *dev-provider*
A goal of Nvim is to allow extension of the editor without special knowledge

1
runtime/doc/help.txt
View File

@ -150,6 +150,7 @@ GUI ~
Interfaces ~
|if_cscop.txt| using Cscope with Vim
|if_lua.txt| Lua interface
|if_pyth.txt| Python interface
|if_ruby.txt| Ruby interface
|sign.txt| debugging signs

39
runtime/doc/intro.txt
View File

@ -94,7 +94,7 @@ For the most recent information about sponsoring look on the Vim web site:
Neovim development is funded separately from Vim:
https://neovim.io/sponsors/
https://neovim.io/#sponsor
==============================================================================
Credits *credits* *author* *Bram* *Moolenaar*
@ -702,18 +702,15 @@ window. You may make the window as small as you like, but if it gets too
small not a single line will fit in it. Make it at least 40 characters wide
to be able to read most messages on the last line.
On most Unix systems, resizing the window is recognized and handled correctly
by Vim.
==============================================================================
Definitions *definitions*
Definitions *definitions* *jargon*
buffer Contains lines of text, usually read from a file.
screen The whole area that Vim uses to work in. This can be
a terminal emulator window. Also called "the Vim
window".
buffer Contains lines of text, usually from a file.
screen The whole area that Nvim uses to display things.
window A view on a buffer. There can be multiple windows for
one buffer.
frame Windows are kept in a tree of frames. Each frame
contains a column, row, or window ("leaf" frame).
A screen contains one or more windows, separated by status lines and with the
command line at the bottom.
@ -746,7 +743,7 @@ A difference is made between four types of lines:
lines with wrapping, line breaks, etc. applied. They
can only be as long as the width of the window allows,
longer lines are wrapped or truncated.
screen lines The lines of the screen that Vim uses. Consists of
screen lines The lines of the screen that Nvim uses. Consists of
the window lines of all windows, with status lines
and the command line added. They can only be as long
as the width of the screen allows. When the command
@ -770,5 +767,27 @@ buffer lines logical lines window lines screen lines ~
5. ddd 13. (command line)
6. ~
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|.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

3
runtime/doc/map.txt
View File

@ -286,6 +286,9 @@ current mode (instead of always going to normal-mode). Visual-mode is
preserved, so tricks with |gv| are not needed. Commands can be invoked
directly in cmdline-mode (which otherwise would require timer hacks).
Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
Unlike <expr> mappings, there are no special restrictions on the <Cmd>
command: it is executed as if an (unrestricted) |autocmd| was invoked or an
async event event was processed.

3
src/nvim/api/vim.c
View File

@ -743,6 +743,9 @@ void nvim_err_writeln(String str)
/// Gets the current list of buffer handles
///
/// Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
/// Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
///
/// @return List of buffer handles
ArrayOf(Buffer) nvim_list_bufs(void)
FUNC_API_SINCE(1)

2
src/nvim/version.c
View File

@ -2173,7 +2173,7 @@ void intro_message(int colon)
N_(NVIM_VERSION_LONG),
"",
N_("Nvim is open source and freely distributable"),
N_("https://neovim.io/community"),
N_("https://neovim.io/#chat"),
"",
N_("type :help nvim<Enter> if you are new! "),
N_("type :checkhealth<Enter> to optimize Nvim"),

2
test/functional/api/vim_spec.lua
View File

@ -1237,7 +1237,7 @@ describe('API', function()
describe('nvim_list_uis', function()
it('returns empty if --headless', function()
-- --embed implies --headless.
-- Test runner defaults to --headless.
eq({}, nvim("list_uis"))
end)
it('returns attached UIs', function()

23
test/functional/ui/screen.lua
View File

@ -494,7 +494,7 @@ function Screen:_wait(check, flags)
if warn_immediate and immediate_seen then
print([[
Warning: A screen test has immediate success. Try to avoid this unless the
warning: Screen test succeeded immediately. Try to avoid this unless the
purpose of the test really requires it.]])
if intermediate_seen then
print([[
@ -503,8 +503,7 @@ Use screen:snapshot_util() or screen:redraw_debug() to find them, and add them
to the test if they make sense.
]])
else
print([[If necessary, silence this warning by
supplying the 'unchanged' argument to screen:expect.]])
print([[If necessary, silence this warning with 'unchanged' argument of screen:expect.]])
end
did_warn = true
end
@ -512,19 +511,17 @@ supplying the 'unchanged' argument to screen:expect.]])
if failure_after_success then
print([[
Warning: Screen changes were received after the expected state. This indicates
warning: Screen changes were received after the expected state. This indicates
indeterminism in the test. Try adding screen:expect(...) (or wait()) between
asynchronous (feed(), nvim_input()) and synchronous API calls.
- Use Screen:redraw_debug() to investigate the problem. It might find
relevant intermediate states that should be added to the test to make it
more robust.
- If the point of the test is to assert the state after some user input
sent with feed(...), also adding an screen:expect(...) before the feed(...)
will help ensure the input is sent to nvim when nvim is in a predictable
state. This is preferable to using wait(), as it is more closely emulates
real user interaction.
- Use screen:redraw_debug() to investigate; it may find relevant intermediate
states that should be added to the test to make it more robust.
- If the purpose of the test is to assert state after some user input sent
with feed(), adding screen:expect() before the feed() will help to ensure
the input is sent when Nvim is in a predictable state. This is preferable
to wait(), for being closer to real user interaction.
- wait() can trigger redraws and consequently generate more indeterminism.
In that case try removing every wait().
Try removing wait().
]])
did_warn = true
end