diff options
| -rw-r--r-- | .editorconfig | 2 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 13 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/intro.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 197 | ||||
| -rw-r--r-- | runtime/doc/motion.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 9 | ||||
| -rw-r--r-- | runtime/doc/quickref.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/terminal.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/ui.txt | 36 | ||||
| -rw-r--r-- | runtime/doc/vvars.txt | 58 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 9 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/options.lua | 7 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/vvars.lua | 60 | ||||
| -rw-r--r-- | runtime/lua/vim/lsp/completion.lua | 2 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 9 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 2 | ||||
| -rw-r--r-- | src/nvim/options.lua | 8 | ||||
| -rw-r--r-- | src/nvim/vvars.lua | 58 |
19 files changed, 267 insertions, 223 deletions
diff --git a/.editorconfig b/.editorconfig index 6e551f77ad..0937a15167 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,7 +10,7 @@ insert_final_newline = true [*.{c,h,in,lua}] max_line_length = 100 -[src/nvim/eval.lua] +[src/nvim/{eval,vvars}.lua] max_line_length = 68 [*.py] diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 8a230380bd..4d368c6426 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1416,7 +1416,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* • {tabpage} |tab-ID| to focus nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window. Also changes tabpage, if necessary. + Sets the current window (and tabpage, implicitly). Attributes: ~ not allowed when |textlock| is active or in the |cmdwin| @@ -2450,6 +2450,9 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Return: ~ Array of lines, or empty array for unloaded buffer. + See also: ~ + • |nvim_buf_get_text()| + nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* Returns a `(row,col)` tuple representing the position of the named mark. "End of line" column position is returned as |v:maxcol| (big number). See @@ -2508,10 +2511,8 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* *nvim_buf_get_text()* nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, {opts}) - Gets a range from the buffer. - - This differs from |nvim_buf_get_lines()| in that it allows retrieving only - portions of a line. + Gets a range from the buffer (may be partial lines, unlike + |nvim_buf_get_lines()|). Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive. @@ -2605,7 +2606,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) Indexing is zero-based, end-exclusive. Negative indices are interpreted as length+1+index: -1 refers to the index past the end. So to change or - delete the last element use start=-2 and end=-1. + delete the last line use start=-2 and end=-1. To insert lines at a given index, set `start` and `end` to the same index. To delete a range of lines, set `replacement` to an empty array. diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 3a579ab194..d5e7554cbe 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -743,6 +743,12 @@ InsertLeavePre Just before leaving Insert mode. Also when *InsertLeave* InsertLeave Just after leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. +LspAttach See |LspAttach| +LspDetach See |LspDetach| +LspNotify See |LspNotify| +LspProgress See |LspProgress| +LspRequest See |LspRequest| +LspTokenUpdate See |LspTokenUpdate| *MenuPopup* MenuPopup Just before showing the popup menu (under the right mouse button). Useful for adjusting the @@ -1128,9 +1134,8 @@ VimLeave Before exiting Vim, just after writing the Not triggered if |v:dying| is 2 or more. *VimLeavePre* VimLeavePre Before exiting Vim, just before writing the - .shada file. This is executed only once, - if there is a match with the name of what - happens to be the current buffer when exiting. + |shada| file. Executed only once, if the + pattern matches the current buffer on exit. Mostly useful with a "*" pattern. > :autocmd VimLeavePre * call CleanupStuff() < Use |v:dying| to detect an abnormal exit. diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 5cb969a531..f58d845e30 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -451,7 +451,7 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type > FROM mode TO mode Normal Visual Select Insert Replace Cmd-line Ex > - Normal v V ^V *4 *1 R gR : / ? ! Q + Normal v V ^V *4 *1 R gR : / ? ! gQ Visual *2 ^G c C -- : -- Select *5 ^O ^G *6 -- -- -- Insert <Esc> -- -- <Insert> -- -- diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 3a2de6bc70..50b2559dac 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -65,26 +65,75 @@ Follow these steps to get LSP features: 5. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-attach| - *lsp-config* +============================================================================== +DEFAULTS *lsp-defaults* -Configurations for LSP clients is done via |vim.lsp.config()|. +When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see +|vim.diagnostic.config()| to customize). It also sets various default options, +listed below, if (1) the language server supports the functionality and (2) +the options are empty or were set by the builtin runtime (ftplugin) files. The +options are not restored when the LSP client is stopped or detached. -When an LSP client starts, it resolves a configuration by merging -configurations, in increasing priority, from the following: +- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger + completion. +- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like + go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|, + |CTRL-W_}| to utilize the language server. +- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via + |gq| if the language server supports it. + - To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|. +- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or + a custom keymap for `K` exists. -1. Configuration defined for the `'*'` name. + *grr* *gra* *grn* *gri* *i_CTRL-S* +Some keymaps are created unconditionally when Nvim starts: +- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()| +- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()| +- "grr" is mapped in Normal mode to |vim.lsp.buf.references()| +- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()| +- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()| +- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()| +If not wanted, these keymaps can be removed at any time using +|vim.keymap.del()| or |:unmap| (see also |gr-default|). + + *lsp-defaults-disable* +To override or delete any of the above defaults, set or unset the options on +|LspAttach|: >lua + + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(args) + -- Unset 'formatexpr' + vim.bo[args.buf].formatexpr = nil + -- Unset 'omnifunc' + vim.bo[args.buf].omnifunc = nil + -- Unmap K + vim.keymap.del('n', 'K', { buffer = args.buf }) + end, + }) +< +============================================================================== +CONFIG *lsp-config* + +You can configure LSP behavior statically via vim.lsp.config(), and +dynamically via |lsp-attach| or |Client:on_attach()|. + +Use |vim.lsp.config()| to define, and selectively enable, LSP configurations. +This is basically a wrapper around |vim.lsp.start()| which allows you to share +and merge configs (which may be provided by Nvim or third-party plugins). + +When an LSP client starts, it resolves its configuration by merging from the +following (in increasing priority): + +1. Configuration defined for the `'*'` name. 2. Configuration from the result of merging all tables returned by `lsp/<name>.lua` files in 'runtimepath' for a server of name `name`. - 3. Configurations defined anywhere else. Note: The merge semantics of configurations follow the behaviour of |vim.tbl_deep_extend()|. -Example: - -Given: >lua +Example: given the following configs... >lua -- Defined in init.lua vim.lsp.config('*', { capabilities = { @@ -97,7 +146,7 @@ Given: >lua root_markers = { '.git' }, }) - -- Defined in ../lsp/clangd.lua + -- Defined in <rtp>/lsp/clangd.lua return { cmd = { 'clangd' }, root_markers = { '.clangd', 'compile_commands.json' }, @@ -109,20 +158,20 @@ Given: >lua filetypes = { 'c' }, }) < -Results in the configuration: >lua +...the merged result is: >lua { -- From the clangd configuration in <rtp>/lsp/clangd.lua cmd = { 'clangd' }, -- From the clangd configuration in <rtp>/lsp/clangd.lua - -- Overrides the * configuration in init.lua + -- Overrides the "*" configuration in init.lua root_markers = { '.clangd', 'compile_commands.json' }, -- From the clangd configuration in init.lua -- Overrides the clangd configuration in <rtp>/lsp/clangd.lua filetypes = { 'c' }, - -- From the * configuration in init.lua + -- From the "*" configuration in init.lua capabilities = { textDocument = { semanticTokens = { @@ -132,71 +181,26 @@ Results in the configuration: >lua } } < - *lsp-defaults* -When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see -|vim.diagnostic.config()| to customize). It also sets various default options, -listed below, if (1) the language server supports the functionality and (2) -the options are empty or were set by the builtin runtime (ftplugin) files. The -options are not restored when the LSP client is stopped or detached. - -- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger - completion. -- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like - go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|, - |CTRL-W_}| to utilize the language server. -- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via - |gq| if the language server supports it. - - To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|. -- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or - a custom keymap for `K` exists. - - *grr* *gra* *grn* *gri* *i_CTRL-S* -Some keymaps are created unconditionally when Nvim starts: -- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()| -- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()| -- "grr" is mapped in Normal mode to |vim.lsp.buf.references()| -- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()| -- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()| -- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()| - -If not wanted, these keymaps can be removed at any time using -|vim.keymap.del()| or |:unmap| (see also |gr-default|). - - *lsp-defaults-disable* -To override or delete any of the above defaults, set or unset the options on -|LspAttach|: >lua - - vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - -- Unset 'formatexpr' - vim.bo[args.buf].formatexpr = nil - -- Unset 'omnifunc' - vim.bo[args.buf].omnifunc = nil - -- Unmap K - vim.keymap.del('n', 'K', { buffer = args.buf }) - end, - }) -< *lsp-attach* -To use other LSP features, set keymaps and other buffer options on -|LspAttach|. Not all language servers provide the same capabilities. Use -capability checks to ensure you only use features supported by the language -server. Example: >lua +To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set +keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language +servers provide the same capabilities; check `supports_method()` in your +LspAttach handler. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) local client = vim.lsp.get_client_by_id(args.data.client_id) if client:supports_method('textDocument/implementation') then - -- Create a keymap for vim.lsp.buf.implementation + -- Create a keymap for vim.lsp.buf.implementation ... end + -- Enable auto-completion. if client:supports_method('textDocument/completion') then - -- Enable auto-completion vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true}) end + -- Format the current buffer on save. if client:supports_method('textDocument/formatting') then - -- Format the current buffer on save vim.api.nvim_create_autocmd('BufWritePre', { buffer = args.buf, callback = function() @@ -207,13 +211,10 @@ server. Example: >lua end, }) < -To learn what capabilities are available you can run the following command in -a buffer with a started LSP client: >vim +To see the capabilities for a given server, try this in a LSP-enabled buffer: >vim :lua =vim.lsp.get_clients()[1].server_capabilities -Full list of features provided by default can be found in |lsp-buf|. - ================================================================================ FAQ *lsp-faq* @@ -537,14 +538,31 @@ the exact definition): EVENTS *lsp-events* LspAttach *LspAttach* - After an LSP client attaches to a buffer. The |autocmd-pattern| is the - name of the buffer. When used from Lua, the client ID is passed to the - callback in the "data" table. See |lsp-attach| for an example. + After an LSP client performs "initialize" and attaches to a buffer. The + |autocmd-pattern| is the buffer name. The client ID is passed in the + Lua handler |event-data| argument. + + Note: If the LSP server performs dynamic registration, capabilities may be + registered any time _after_ LspAttach. In that case you may want to handle + the "registerCapability" event. Example: >lua + + vim.lsp.handlers['client/registerCapability'] = (function(overridden) + return function(err, res, ctx) + local result = overridden(err, res, ctx) + local client = vim.lsp.get_client_by_id(ctx.client_id) + if not client then + return + end + -- Call your custom on_attach logic... + -- my_on_attach(client, vim.api.nvim_get_current_buf()) + return result + end + end)(vim.lsp.handlers['client/registerCapability']) LspDetach *LspDetach* - Just before an LSP client detaches from a buffer. The |autocmd-pattern| - is the name of the buffer. When used from Lua, the client ID is passed - to the callback in the "data" table. Example: >lua + Just before an LSP client detaches from a buffer. The |autocmd-pattern| is + the buffer name. The client ID is passed in the Lua handler |event-data| + argument. Example: >lua vim.api.nvim_create_autocmd('LspDetach', { callback = function(args) @@ -566,8 +584,8 @@ LspNotify *LspNotify* This event is triggered after each successful notification sent to an LSP server. - When used from Lua, the client_id, LSP method, and parameters are sent - in the "data" table. Example: >lua + The client_id, LSP method, and parameters are sent in the Lua handler + |event-data| table argument. Example: >lua vim.api.nvim_create_autocmd('LspNotify', { callback = function(args) @@ -592,9 +610,9 @@ LspProgress *LspProgress* If the server sends a "work done progress", the `pattern` is set to `kind` (one of `begin`, `report` or `end`). - When used from Lua, the event contains a `data` table with `client_id` and - `params` properties. `params` will contain the request params sent by the - server (see `lsp.ProgressParams`). + The Lua handler |event-data| argument has `client_id` and `params` + properties, where `params` is the request params sent by the server (see + `lsp.ProgressParams`). Example: >vim autocmd LspProgress * redrawstatus @@ -611,11 +629,10 @@ LspRequest *LspRequest* is requested using `client.cancel_request(request_id)`, then this event will trigger with {type} == `cancel`. - When used from Lua, the client ID, request ID, and request are sent in - the "data" table. See {requests} in |vim.lsp.Client| for details on the - {request} value. If the request type is `complete`, the request will be - deleted from the client's pending requests table immediately after - calling the event's callbacks. Example: >lua + The Lua handler |event-data| argument has the client ID, request ID, and + request (described at |vim.lsp.Client|, {requests} field). If the request + type is `complete`, the request will be deleted from the client's pending + requests table after processing the event handlers. Example: >lua vim.api.nvim_create_autocmd('LspRequest', { callback = function(args) @@ -641,11 +658,9 @@ LspRequest *LspRequest* LspTokenUpdate *LspTokenUpdate* When a visible semantic token is sent or updated by the LSP server, or when an existing token becomes visible for the first time. The - |autocmd-pattern| is the name of the buffer. When used from Lua, the - token and client ID are passed to the callback in the "data" table. The - token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|. - Example: - >lua + |autocmd-pattern| is the buffer name. The Lua handler |event-data| + argument has the client ID and token (see + |vim.lsp.semantic_tokens.get_at_pos()|). Example: >lua vim.api.nvim_create_autocmd('LspTokenUpdate', { callback = function(args) @@ -1842,6 +1857,8 @@ activate "auto-completion" when you type any of the server-defined `triggerCharacters`. Example: activate LSP-driven auto-completion: >lua + -- Works best with completeopt=noselect. + vim.cmd[[set completeopt+=menuone,noselect,popup]] vim.lsp.start({ name = 'ts_ls', cmd = …, diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 48fa723800..52838d0cc7 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -852,7 +852,7 @@ unrelated. 'a - 'z lowercase marks, valid within one file 'A - 'Z uppercase marks, also called file marks, valid between files -'0 - '9 numbered marks, set from .shada file +'0 - '9 numbered marks, set from |shada| file Lowercase marks 'a to 'z are remembered as long as the file remains in the buffer list. If you remove the file from the buffer list, all its marks are diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 7aca0268c6..01d5efee4a 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -2349,12 +2349,13 @@ A jump table for the options with a short description can be found at |Q_op|. when 'autoindent' is on. To insert a real tab when 'expandtab' is on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|. - *'exrc'* *'ex'* *'noexrc'* *'noex'* + *'exrc'* *'ex'* *'noexrc'* *'noex'* *project-config* *workspace-config* 'exrc' 'ex' boolean (default off) global - Automatically execute .nvim.lua, .nvimrc, and .exrc files in the - current directory, if the file is in the |trust| list. Use |:trust| to - manage trusted files. See also |vim.secure.read()|. + Enables project-local configuration. Nvim will execute any .nvim.lua, + .nvimrc, or .exrc file found in the |current-directory|, if the file is + in the |trust| list. Use |:trust| to manage trusted files. See also + |vim.secure.read()|. Compare 'exrc' to |editorconfig|: - 'exrc' can execute any code; editorconfig only specifies settings. diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 86147cfc2b..163f74da22 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -842,7 +842,7 @@ Short explanation of each option: *option-list* 'selection' 'sel' what type of selection to use 'selectmode' 'slm' when to use Select mode instead of Visual mode 'sessionoptions' 'ssop' options for |:mksession| -'shada' 'sd' use .shada file upon startup and exiting +'shada' 'sd' use |shada| file upon startup and exiting 'shell' 'sh' name of shell to use for external commands 'shellcmdflag' 'shcf' flag to shell to execute one command 'shellpipe' 'sp' string to put output of ":make" in error file diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt index 10fa40cf54..618510fc4f 100644 --- a/runtime/doc/terminal.txt +++ b/runtime/doc/terminal.txt @@ -198,6 +198,7 @@ doesn't interfere). - fish: https://fishshell.com/docs/current/relnotes.html#improved-terminal-support - kitty: https://sw.kovidgoyal.net/kitty/shell-integration/ +- powershell: https://learn.microsoft.com/en-us/windows/terminal/tutorials/shell-integration#powershell-pwshexe - vscode: https://code.visualstudio.com/docs/terminal/shell-integration To configure bash to mark the start of each prompt, set $PROMPT_COMMAND: >bash @@ -209,7 +210,7 @@ To configure bash to mark the start of each prompt, set $PROMPT_COMMAND: >bash The |]]| and |[[| motions jump to the next/previous prompts, if your shell emits OSC 133 as described above. - *terminal-shell-prompt-signs* + *shell-prompt-signs* To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()| from a |TermRequest| handler: >lua diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 31335b4fbb..bb4e2dbec5 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -272,9 +272,9 @@ Grid Events (line-based) *ui-linegrid* Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs. Deactivates |ui-grid-old| implicitly. -The biggest change compared to |ui-grid-old| is to use a single `grid_line` -event to update the contents of a screen line (whereas the old protocol used -a combination of cursor, highlight and text events) +Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to +update a screen-line (whereas the old protocol emitted separate cursor, +highlight and text events per screen-line). Most of these events take a `grid` index as first parameter. Grid 1 is the global grid used by default for the entire editor screen state. The @@ -351,8 +351,7 @@ numerical highlight ids to the actual attributes. affected by redefined ids, so UIs do not need to keep track of this themselves. - `info` is an empty array by default, and will be used by the - |ui-hlstate| extension explained below. + `info` is an empty array unless |ui-hlstate| is enabled. ["hl_group_set", name, hl_id] ~ The built-in highlight group `name` was set to use the attributes `hl_id` @@ -540,20 +539,23 @@ is not active. New UIs should implement |ui-linegrid| instead. +-------------------------+ < ============================================================================== -Detailed highlight state Extension *ui-hlstate* +Highlight Events *ui-hlstate* Activated by the `ext_hlstate` |ui-option|. Activates |ui-linegrid| implicitly. -By default Nvim will only describe grid cells using the final calculated -highlight attributes, as described by the dict keys in |ui-event-highlight_set|. -The `ext_hlstate` extension allows to the UI to also receive a semantic -description of the highlights active in a cell. In this mode highlights will be -predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|. -The `info` parameter in `hl_attr_define` will contain a semantic description -of the highlights. As highlight groups can be combined, this will be an array -of items, with the item with highest priority last. Each item is a dictionary -with the following possible keys: +If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in +|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells +using the final calculated highlight attributes described at +|ui-event-highlight_set|. + +`ext_hlstate` provides a semantic description of active highlights for each +grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define| +and |ui-event-grid_line|. + +The `info` parameter in `hl_attr_define` contains a semantic description of +the highlights. Because highlight groups can be combined, this is an array +where the highest-priority item is last. Each item is a dict with these keys: `kind`: always present. One of the following values: "ui": Builtin UI highlight. |highlight-groups| @@ -671,6 +673,10 @@ Activated by the `ext_popupmenu` |ui-option|. This UI extension delegates presentation of the |popupmenu-completion| and command-line 'wildmenu'. +The UI decides how to present the menu. For example, depending on the last +`mode_change` event, command-line wildmenu may be presented horizontally, +while insert-mode completion would show a vertical popupmenu. + ["popupmenu_show", items, selected, row, col, grid] ~ Show |popupmenu-completion|. `items` is an array of completion items to show; each item is an array of the form [word, kind, menu, info] as diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index 848942a21f..18b09be3a2 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -153,45 +153,43 @@ v:event an aborting condition (e.g. |c_Esc| or |c_CTRL-C| for |CmdlineLeave|). chan |channel-id| - info Dict of arbitrary event data. + changed_window Is |v:true| if the event fired while + changing window (or tab) on |DirChanged|. cmdlevel Level of cmdline. cmdtype Type of cmdline, |cmdline-char|. + col Column count of popup menu on |CompleteChanged|, + relative to screen. + complete_type See |complete_info_mode| + complete_word The selected word, or empty if completion + was abandoned/discarded. + completed_item Current selected item on |CompleteChanged|, + or `{}` if no item selected. cwd Current working directory. + height Height of popup menu on |CompleteChanged| inclusive Motion is |inclusive|, else exclusive. - scope Event-specific scope name. + info Dict of arbitrary event data. operator Current |operator|. Also set for Ex commands (unlike |v:operator|). For example if |TextYankPost| is triggered by the |:yank| Ex command then `v:event.operator` is "y". + reason |CompleteDone| reason. regcontents Text stored in the register as a |readfile()|-style list of lines. - regname Requested register (e.g "x" for "xyy) - or the empty string for an unnamed - operation. + regname Requested register (e.g "x" for "xyy), or + empty string for an unnamed operation. regtype Type of register as returned by |getregtype()|. - visual Selection is visual (as opposed to, - e.g., via motion). - completed_item Current selected complete item on - |CompleteChanged|, Is `{}` when no complete - item selected. - height Height of popup menu on |CompleteChanged| - width Width of popup menu on |CompleteChanged| row Row count of popup menu on |CompleteChanged|, relative to screen. - col Col count of popup menu on |CompleteChanged|, - relative to screen. + scope Event-specific scope name. + scrollbar |v:true| if popup menu has a scrollbar, or + |v:false| if not. size Total number of completion items on |CompleteChanged|. - scrollbar Is |v:true| if popup menu have scrollbar, or - |v:false| if not. - changed_window Is |v:true| if the event fired while - changing window (or tab) on |DirChanged|. status Job status or exit code, -1 means "unknown". |TermClose| - reason Reason for completion being done. |CompleteDone| - complete_word The word that was selected, empty if abandoned complete. - complete_type See |complete_info_mode| + visual Selection is visual (as opposed to e.g. a motion range). + width Width of popup menu on |CompleteChanged| windows List of window IDs that changed on |WinResized| *v:exception* *exception-variable* @@ -567,13 +565,19 @@ v:servername *$NVIM* $NVIM is set by |terminal| and |jobstart()|, and is thus a hint that the current environment is a subprocess of Nvim. - Example: >vim - if $NVIM - echo nvim_get_chan_info(v:parent) - endif -< - Note the contents of $NVIM may change in the future. + Example: a child Nvim process can detect and make requests to + its parent Nvim: >lua + + if vim.env.NVIM then + local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true}) + if ok and chan then + local client = vim.api.nvim_get_chan_info(chan).client + local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 }) + vim.print(('got "%s" from parent Nvim'):format(rv)) + end + end +< *v:shell_error* *shell_error-variable* v:shell_error diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 69cb424254..ece3c1854b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -485,10 +485,7 @@ function vim.api.nvim_buf_get_offset(buffer, index) end --- @return any function vim.api.nvim_buf_get_option(buffer, name) end ---- Gets a range from the buffer. ---- ---- This differs from `nvim_buf_get_lines()` in that it allows retrieving only ---- portions of a line. +--- Gets a range from the buffer (may be partial lines, unlike `nvim_buf_get_lines()`). --- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. @@ -698,7 +695,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted --- as length+1+index: -1 refers to the index past the end. So to change ---- or delete the last element use start=-2 and end=-1. +--- or delete the last line use start=-2 and end=-1. --- --- To insert lines at a given index, set `start` and `end` to the same index. --- To delete a range of lines, set `replacement` to an empty array. @@ -2089,7 +2086,7 @@ function vim.api.nvim_set_current_line(line) end --- @param tabpage integer `tab-ID` to focus function vim.api.nvim_set_current_tabpage(tabpage) end ---- Sets the current window. Also changes tabpage, if necessary. +--- Sets the current window (and tabpage, implicitly). --- --- @param window integer `window-ID` to focus function vim.api.nvim_set_current_win(window) end diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 775dda59f7..5e138c1a4a 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -2010,9 +2010,10 @@ vim.o.et = vim.o.expandtab vim.bo.expandtab = vim.o.expandtab vim.bo.et = vim.bo.expandtab ---- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the ---- current directory, if the file is in the `trust` list. Use `:trust` to ---- manage trusted files. See also `vim.secure.read()`. +--- Enables project-local configuration. Nvim will execute any .nvim.lua, +--- .nvimrc, or .exrc file found in the `current-directory`, if the file is +--- in the `trust` list. Use `:trust` to manage trusted files. See also +--- `vim.secure.read()`. --- --- Compare 'exrc' to `editorconfig`: --- - 'exrc' can execute any code; editorconfig only specifies settings. diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index a44ad6c7d9..9df5a0b5f2 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -160,45 +160,43 @@ vim.v.errors = ... --- an aborting condition (e.g. `c_Esc` or --- `c_CTRL-C` for `CmdlineLeave`). --- chan `channel-id` ---- info Dict of arbitrary event data. +--- changed_window Is `v:true` if the event fired while +--- changing window (or tab) on `DirChanged`. --- cmdlevel Level of cmdline. --- cmdtype Type of cmdline, `cmdline-char`. +--- col Column count of popup menu on `CompleteChanged`, +--- relative to screen. +--- complete_type See `complete_info_mode` +--- complete_word The selected word, or empty if completion +--- was abandoned/discarded. +--- completed_item Current selected item on `CompleteChanged`, +--- or `{}` if no item selected. --- cwd Current working directory. +--- height Height of popup menu on `CompleteChanged` --- inclusive Motion is `inclusive`, else exclusive. ---- scope Event-specific scope name. +--- info Dict of arbitrary event data. --- operator Current `operator`. Also set for Ex --- commands (unlike `v:operator`). For --- example if `TextYankPost` is triggered --- by the `:yank` Ex command then --- `v:event.operator` is "y". +--- reason `CompleteDone` reason. --- regcontents Text stored in the register as a --- `readfile()`-style list of lines. ---- regname Requested register (e.g "x" for "xyy) ---- or the empty string for an unnamed ---- operation. +--- regname Requested register (e.g "x" for "xyy), or +--- empty string for an unnamed operation. --- regtype Type of register as returned by --- `getregtype()`. ---- visual Selection is visual (as opposed to, ---- e.g., via motion). ---- completed_item Current selected complete item on ---- `CompleteChanged`, Is `{}` when no complete ---- item selected. ---- height Height of popup menu on `CompleteChanged` ---- width Width of popup menu on `CompleteChanged` --- row Row count of popup menu on `CompleteChanged`, --- relative to screen. ---- col Col count of popup menu on `CompleteChanged`, ---- relative to screen. +--- scope Event-specific scope name. +--- scrollbar `v:true` if popup menu has a scrollbar, or +--- `v:false` if not. --- size Total number of completion items on --- `CompleteChanged`. ---- scrollbar Is `v:true` if popup menu have scrollbar, or ---- `v:false` if not. ---- changed_window Is `v:true` if the event fired while ---- changing window (or tab) on `DirChanged`. --- status Job status or exit code, -1 means "unknown". `TermClose` ---- reason Reason for completion being done. `CompleteDone` ---- complete_word The word that was selected, empty if abandoned complete. ---- complete_type See `complete_info_mode` +--- visual Selection is visual (as opposed to e.g. a motion range). +--- width Width of popup menu on `CompleteChanged` --- windows List of window IDs that changed on `WinResized` --- @type vim.v.event vim.v.event = ... @@ -590,15 +588,21 @@ vim.v.searchforward = ... --- *$NVIM* --- $NVIM is set by `terminal` and `jobstart()`, and is thus --- a hint that the current environment is a subprocess of Nvim. ---- Example: --- ---- ```vim ---- if $NVIM ---- echo nvim_get_chan_info(v:parent) ---- endif ---- ``` +--- Example: a child Nvim process can detect and make requests to +--- its parent Nvim: +--- +--- ```lua --- ---- Note the contents of $NVIM may change in the future. +--- if vim.env.NVIM then +--- local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true}) +--- if ok and chan then +--- local client = vim.api.nvim_get_chan_info(chan).client +--- local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 }) +--- vim.print(('got "%s" from parent Nvim'):format(rv)) +--- end +--- end +--- ``` --- @type string vim.v.servername = ... diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua index dcb7b5fa9b..6aedac8fd9 100644 --- a/runtime/lua/vim/lsp/completion.lua +++ b/runtime/lua/vim/lsp/completion.lua @@ -6,6 +6,8 @@ --- --- Example: activate LSP-driven auto-completion: --- ```lua +--- -- Works best with completeopt=noselect. +--- vim.cmd[[set completeopt+=menuone,noselect,popup]] --- vim.lsp.start({ --- name = 'ts_ls', --- cmd = …, diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 1cd9d2df76..f8ebf4b838 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -238,6 +238,8 @@ Boolean nvim_buf_detach(uint64_t channel_id, Buffer buffer, Error *err) /// Out-of-bounds indices are clamped to the nearest valid value, unless /// `strict_indexing` is set. /// +/// @see |nvim_buf_get_text()| +/// /// @param channel_id /// @param buffer Buffer id, or 0 for current buffer /// @param start First line index @@ -294,7 +296,7 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id, /// /// Indexing is zero-based, end-exclusive. Negative indices are interpreted /// as length+1+index: -1 refers to the index past the end. So to change -/// or delete the last element use start=-2 and end=-1. +/// or delete the last line use start=-2 and end=-1. /// /// To insert lines at a given index, set `start` and `end` to the same index. /// To delete a range of lines, set `replacement` to an empty array. @@ -685,10 +687,7 @@ void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, In }); } -/// Gets a range from the buffer. -/// -/// This differs from |nvim_buf_get_lines()| in that it allows retrieving only -/// portions of a line. +/// Gets a range from the buffer (may be partial lines, unlike |nvim_buf_get_lines()|). /// /// Indexing is zero-based. Row indices are end-inclusive, and column indices /// are end-exclusive. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 96cc8b68ae..70f5ebacb7 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -872,7 +872,7 @@ Window nvim_get_current_win(void) return curwin->handle; } -/// Sets the current window. Also changes tabpage, if necessary. +/// Sets the current window (and tabpage, implicitly). /// /// @param window |window-ID| to focus /// @param[out] err Error details, if any diff --git a/src/nvim/options.lua b/src/nvim/options.lua index e9f8051ed3..d150303033 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -2663,9 +2663,10 @@ local options = { abbreviation = 'ex', defaults = false, desc = [=[ - Automatically execute .nvim.lua, .nvimrc, and .exrc files in the - current directory, if the file is in the |trust| list. Use |:trust| to - manage trusted files. See also |vim.secure.read()|. + Enables project-local configuration. Nvim will execute any .nvim.lua, + .nvimrc, or .exrc file found in the |current-directory|, if the file is + in the |trust| list. Use |:trust| to manage trusted files. See also + |vim.secure.read()|. Compare 'exrc' to |editorconfig|: - 'exrc' can execute any code; editorconfig only specifies settings. @@ -2678,6 +2679,7 @@ local options = { scope = { 'global' }, secure = true, short_desc = N_('read .nvimrc and .exrc in the current directory'), + tags = { 'project-config', 'workspace-config' }, type = 'boolean', varname = 'p_exrc', }, diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua index 52af56e607..cb84df015c 100644 --- a/src/nvim/vvars.lua +++ b/src/nvim/vvars.lua @@ -175,45 +175,43 @@ M.vars = { an aborting condition (e.g. |c_Esc| or |c_CTRL-C| for |CmdlineLeave|). chan |channel-id| - info Dict of arbitrary event data. + changed_window Is |v:true| if the event fired while + changing window (or tab) on |DirChanged|. cmdlevel Level of cmdline. cmdtype Type of cmdline, |cmdline-char|. + col Column count of popup menu on |CompleteChanged|, + relative to screen. + complete_type See |complete_info_mode| + complete_word The selected word, or empty if completion + was abandoned/discarded. + completed_item Current selected item on |CompleteChanged|, + or `{}` if no item selected. cwd Current working directory. + height Height of popup menu on |CompleteChanged| inclusive Motion is |inclusive|, else exclusive. - scope Event-specific scope name. + info Dict of arbitrary event data. operator Current |operator|. Also set for Ex commands (unlike |v:operator|). For example if |TextYankPost| is triggered by the |:yank| Ex command then `v:event.operator` is "y". + reason |CompleteDone| reason. regcontents Text stored in the register as a |readfile()|-style list of lines. - regname Requested register (e.g "x" for "xyy) - or the empty string for an unnamed - operation. + regname Requested register (e.g "x" for "xyy), or + empty string for an unnamed operation. regtype Type of register as returned by |getregtype()|. - visual Selection is visual (as opposed to, - e.g., via motion). - completed_item Current selected complete item on - |CompleteChanged|, Is `{}` when no complete - item selected. - height Height of popup menu on |CompleteChanged| - width Width of popup menu on |CompleteChanged| row Row count of popup menu on |CompleteChanged|, relative to screen. - col Col count of popup menu on |CompleteChanged|, - relative to screen. + scope Event-specific scope name. + scrollbar |v:true| if popup menu has a scrollbar, or + |v:false| if not. size Total number of completion items on |CompleteChanged|. - scrollbar Is |v:true| if popup menu have scrollbar, or - |v:false| if not. - changed_window Is |v:true| if the event fired while - changing window (or tab) on |DirChanged|. status Job status or exit code, -1 means "unknown". |TermClose| - reason Reason for completion being done. |CompleteDone| - complete_word The word that was selected, empty if abandoned complete. - complete_type See |complete_info_mode| + visual Selection is visual (as opposed to e.g. a motion range). + width Width of popup menu on |CompleteChanged| windows List of window IDs that changed on |WinResized| ]=], }, @@ -678,13 +676,19 @@ M.vars = { *$NVIM* $NVIM is set by |terminal| and |jobstart()|, and is thus a hint that the current environment is a subprocess of Nvim. - Example: >vim - if $NVIM - echo nvim_get_chan_info(v:parent) - endif - < - Note the contents of $NVIM may change in the future. + Example: a child Nvim process can detect and make requests to + its parent Nvim: >lua + + if vim.env.NVIM then + local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true}) + if ok and chan then + local client = vim.api.nvim_get_chan_info(chan).client + local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 }) + vim.print(('got "%s" from parent Nvim'):format(rv)) + end + end + < ]=], }, shell_error = { |