diff options
| -rw-r--r-- | .travis.yml | 2 | ||||
| -rw-r--r-- | man/nvim.1 | 2 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 96 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 18 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 48 | ||||
| -rw-r--r-- | runtime/doc/help.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/intro.txt | 39 | ||||
| -rw-r--r-- | runtime/doc/map.txt | 3 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 3 | ||||
| -rw-r--r-- | src/nvim/version.c | 2 | ||||
| -rw-r--r-- | test/functional/api/vim_spec.lua | 2 | ||||
| -rw-r--r-- | test/functional/ui/screen.lua | 23 |
12 files changed, 134 insertions, 105 deletions
diff --git a/.travis.yml b/.travis.yml index 51ce0c2038..8b06dbcd97 100644 --- a/.travis.yml +++ b/.travis.yml @@ -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 diff --git a/man/nvim.1 b/man/nvim.1 index 2621036e26..b9f47cc851 100644 --- a/man/nvim.1 +++ b/man/nvim.1 @@ -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 diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index e16b6b7e75..66fb5bda82 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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 diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index a2772e2485..4702656c41 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -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 diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index cd81236f32..bcf43142ad 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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 diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index c2ad25aeda..edecc655dd 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -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 diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index b74079e74e..fee7d9aa69 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -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: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 30e7f644b3..fa5e10b5e5 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -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. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 54b27477e0..4da61a30ef 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -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) diff --git a/src/nvim/version.c b/src/nvim/version.c index d23a007109..966ecfd719 100644 --- a/src/nvim/version.c +++ b/src/nvim/version.c @@ -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"), diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua index dde4dab7ac..6261458f2a 100644 --- a/test/functional/api/vim_spec.lua +++ b/test/functional/api/vim_spec.lua @@ -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() diff --git a/test/functional/ui/screen.lua b/test/functional/ui/screen.lua index e5b522e775..75eb5bb4e3 100644 --- a/test/functional/ui/screen.lua +++ b/test/functional/ui/screen.lua @@ -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 |