GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-15 08:41:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc

Browse Source
This commit is contained in:
Justin M. Keyes
2025-03-09 23:56:22 +01:00
parent 041a939eeb
commit f96606371c
19 changed files with 276 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.editorconfig
View File

@ -10,7 +10,7 @@ insert_final_newline = true
[*.{c,h,in,lua}] [*.{c,h,in,lua}]
max_line_length = 100 max_line_length = 100
[src/nvim/eval.lua] [src/nvim/{eval,vvars}.lua]
max_line_length = 68 max_line_length = 68
[*.py] [*.py]

13
runtime/doc/api.txt
View File

@ -1416,7 +1416,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
• {tabpage} |tab-ID| to focus • {tabpage} |tab-ID| to focus
nvim_set_current_win({window}) *nvim_set_current_win()* 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: ~ Attributes: ~
not allowed when |textlock| is active or in the |cmdwin| not allowed when |textlock| is active or in the |cmdwin|
@ -2450,6 +2450,9 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Return: ~ Return: ~
Array of lines, or empty array for unloaded buffer. 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()* nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
Returns a `(row,col)` tuple representing the position of the named 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 "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()*
nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{opts}) {opts})
Gets a range from the buffer. Gets a range from the buffer (may be partial lines, unlike
|nvim_buf_get_lines()|).
This differs from |nvim_buf_get_lines()| in that it allows retrieving only
portions of a line.
Indexing is zero-based. Row indices are end-inclusive, and column indices Indexing is zero-based. Row indices are end-inclusive, and column indices
are end-exclusive. 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 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 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 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. To delete a range of lines, set `replacement` to an empty array.

11
runtime/doc/autocmd.txt
View File

@ -743,6 +743,12 @@ InsertLeavePre Just before leaving Insert mode. Also when
*InsertLeave* *InsertLeave*
InsertLeave Just after leaving Insert mode. Also when InsertLeave Just after leaving Insert mode. Also when
using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. 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*
MenuPopup Just before showing the popup menu (under the MenuPopup Just before showing the popup menu (under the
right mouse button). Useful for adjusting 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. Not triggered if |v:dying| is 2 or more.
*VimLeavePre* *VimLeavePre*
VimLeavePre Before exiting Vim, just before writing the VimLeavePre Before exiting Vim, just before writing the
.shada file. This is executed only once, |shada| file. Executed only once, if the
if there is a match with the name of what pattern matches the current buffer on exit.
happens to be the current buffer when exiting.
Mostly useful with a "*" pattern. > Mostly useful with a "*" pattern. >
:autocmd VimLeavePre * call CleanupStuff() :autocmd VimLeavePre * call CleanupStuff()
< Use |v:dying| to detect an abnormal exit. < Use |v:dying| to detect an abnormal exit.

2
runtime/doc/intro.txt
View File

@ -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 FROM mode TO mode
Normal Visual Select Insert Replace Cmd-line Ex > 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 -- : -- Visual *2 ^G c C -- : --
Select *5 ^O ^G *6 -- -- -- Select *5 ^O ^G *6 -- -- --
Insert <Esc> -- -- <Insert> -- -- Insert <Esc> -- -- <Insert> -- --

215
runtime/doc/lsp.txt
View File

@ -65,74 +65,9 @@ Follow these steps to get LSP features:
5. (Optional) Configure keymaps and autocommands to use LSP features. 5. (Optional) Configure keymaps and autocommands to use LSP features.
|lsp-attach| |lsp-attach|
*lsp-config* ==============================================================================
DEFAULTS *lsp-defaults*
Configurations for LSP clients is done via |vim.lsp.config()|.
When an LSP client starts, it resolves a configuration by merging
configurations, in increasing priority, from the following:
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
-- Defined in init.lua
vim.lsp.config('*', {
capabilities = {
textDocument = {
semanticTokens = {
multilineTokenSupport = true,
}
}
},
root_markers = { '.git' },
})
-- Defined in ../lsp/clangd.lua
return {
cmd = { 'clangd' },
root_markers = { '.clangd', 'compile_commands.json' },
filetypes = { 'c', 'cpp' },
}
-- Defined in init.lua
vim.lsp.config('clangd', {
filetypes = { 'c' },
})
<
Results in the configuration: >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
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
capabilities = {
textDocument = {
semanticTokens = {
multilineTokenSupport = true,
}
}
}
}
<
*lsp-defaults*
When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
|vim.diagnostic.config()| to customize). It also sets various default options, |vim.diagnostic.config()| to customize). It also sets various default options,
listed below, if (1) the language server supports the functionality and (2) listed below, if (1) the language server supports the functionality and (2)
@ -176,27 +111,96 @@ To override or delete any of the above defaults, set or unset the options on
vim.keymap.del('n', 'K', { buffer = args.buf }) vim.keymap.del('n', 'K', { buffer = args.buf })
end, 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 the following configs... >lua
-- Defined in init.lua
vim.lsp.config('*', {
capabilities = {
textDocument = {
semanticTokens = {
multilineTokenSupport = true,
}
}
},
root_markers = { '.git' },
})
-- Defined in <rtp>/lsp/clangd.lua
return {
cmd = { 'clangd' },
root_markers = { '.clangd', 'compile_commands.json' },
filetypes = { 'c', 'cpp' },
}
-- Defined in init.lua
vim.lsp.config('clangd', {
filetypes = { 'c' },
})
<
...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
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
capabilities = {
textDocument = {
semanticTokens = {
multilineTokenSupport = true,
}
}
}
}
< <
*lsp-attach* *lsp-attach*
To use other LSP features, set keymaps and other buffer options on To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set
|LspAttach|. Not all language servers provide the same capabilities. Use keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language
capability checks to ensure you only use features supported by the language servers provide the same capabilities; check `supports_method()` in your
server. Example: >lua LspAttach handler. Example: >lua
vim.api.nvim_create_autocmd('LspAttach', { vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args) callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id) local client = vim.lsp.get_client_by_id(args.data.client_id)
if client:supports_method('textDocument/implementation') then if client:supports_method('textDocument/implementation') then
-- Create a keymap for vim.lsp.buf.implementation -- Create a keymap for vim.lsp.buf.implementation ...
end end
-- Enable auto-completion.
if client:supports_method('textDocument/completion') then if client:supports_method('textDocument/completion') then
-- Enable auto-completion
vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true}) vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
end end
-- Format the current buffer on save.
if client:supports_method('textDocument/formatting') then if client:supports_method('textDocument/formatting') then
-- Format the current buffer on save
vim.api.nvim_create_autocmd('BufWritePre', { vim.api.nvim_create_autocmd('BufWritePre', {
buffer = args.buf, buffer = args.buf,
callback = function() callback = function()
@ -207,13 +211,10 @@ server. Example: >lua
end, end,
}) })
< <
To learn what capabilities are available you can run the following command in To see the capabilities for a given server, try this in a LSP-enabled buffer: >vim
a buffer with a started LSP client: >vim
:lua =vim.lsp.get_clients()[1].server_capabilities :lua =vim.lsp.get_clients()[1].server_capabilities
Full list of features provided by default can be found in |lsp-buf|.
================================================================================ ================================================================================
FAQ *lsp-faq* FAQ *lsp-faq*
@ -537,14 +538,31 @@ the exact definition):
EVENTS *lsp-events* EVENTS *lsp-events*
LspAttach *LspAttach* LspAttach *LspAttach*
After an LSP client attaches to a buffer. The |autocmd-pattern| is the After an LSP client performs "initialize" and attaches to a buffer. The
name of the buffer. When used from Lua, the client ID is passed to the |autocmd-pattern| is the buffer name. The client ID is passed in the
callback in the "data" table. See |lsp-attach| for an example. 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* LspDetach *LspDetach*
Just before an LSP client detaches from a buffer. The |autocmd-pattern| Just before an LSP client detaches from a buffer. The |autocmd-pattern| is
is the name of the buffer. When used from Lua, the client ID is passed the buffer name. The client ID is passed in the Lua handler |event-data|
to the callback in the "data" table. Example: >lua argument. Example: >lua
vim.api.nvim_create_autocmd('LspDetach', { vim.api.nvim_create_autocmd('LspDetach', {
callback = function(args) callback = function(args)
@ -566,8 +584,8 @@ LspNotify *LspNotify*
This event is triggered after each successful notification sent to an This event is triggered after each successful notification sent to an
LSP server. LSP server.
When used from Lua, the client_id, LSP method, and parameters are sent The client_id, LSP method, and parameters are sent in the Lua handler
in the "data" table. Example: >lua |event-data| table argument. Example: >lua
vim.api.nvim_create_autocmd('LspNotify', { vim.api.nvim_create_autocmd('LspNotify', {
callback = function(args) callback = function(args)
@ -592,9 +610,9 @@ LspProgress *LspProgress*
If the server sends a "work done progress", the `pattern` is set to `kind` If the server sends a "work done progress", the `pattern` is set to `kind`
(one of `begin`, `report` or `end`). (one of `begin`, `report` or `end`).
When used from Lua, the event contains a `data` table with `client_id` and The Lua handler |event-data| argument has `client_id` and `params`
`params` properties. `params` will contain the request params sent by the properties, where `params` is the request params sent by the server (see
server (see `lsp.ProgressParams`). `lsp.ProgressParams`).
Example: >vim Example: >vim
autocmd LspProgress * redrawstatus autocmd LspProgress * redrawstatus
@ -611,11 +629,10 @@ LspRequest *LspRequest*
is requested using `client.cancel_request(request_id)`, then this event is requested using `client.cancel_request(request_id)`, then this event
will trigger with {type} == `cancel`. will trigger with {type} == `cancel`.
When used from Lua, the client ID, request ID, and request are sent in The Lua handler |event-data| argument has the client ID, request ID, and
the "data" table. See {requests} in |vim.lsp.Client| for details on the request (described at |vim.lsp.Client|, {requests} field). If the request
{request} value. If the request type is `complete`, the request will be type is `complete`, the request will be deleted from the client's pending
deleted from the client's pending requests table immediately after requests table after processing the event handlers. Example: >lua
calling the event's callbacks. Example: >lua
vim.api.nvim_create_autocmd('LspRequest', { vim.api.nvim_create_autocmd('LspRequest', {
callback = function(args) callback = function(args)
@ -641,11 +658,9 @@ LspRequest *LspRequest*
LspTokenUpdate *LspTokenUpdate* LspTokenUpdate *LspTokenUpdate*
When a visible semantic token is sent or updated by the LSP server, or 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 when an existing token becomes visible for the first time. The
|autocmd-pattern| is the name of the buffer. When used from Lua, the |autocmd-pattern| is the buffer name. The Lua handler |event-data|
token and client ID are passed to the callback in the "data" table. The argument has the client ID and token (see
token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|. |vim.lsp.semantic_tokens.get_at_pos()|). Example: >lua
Example:
>lua
vim.api.nvim_create_autocmd('LspTokenUpdate', { vim.api.nvim_create_autocmd('LspTokenUpdate', {
callback = function(args) callback = function(args)
@ -1842,6 +1857,8 @@ activate "auto-completion" when you type any of the server-defined
`triggerCharacters`. `triggerCharacters`.
Example: activate LSP-driven auto-completion: >lua Example: activate LSP-driven auto-completion: >lua
-- Works best with completeopt=noselect.
vim.cmd[[set completeopt+=menuone,noselect,popup]]
vim.lsp.start({ vim.lsp.start({
name = 'ts_ls', name = 'ts_ls',
cmd = …, cmd = …,

2
runtime/doc/motion.txt
View File

@ -852,7 +852,7 @@ unrelated.
'a - 'z lowercase marks, valid within one file 'a - 'z lowercase marks, valid within one file
'A - 'Z uppercase marks, also called file marks, valid between files '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 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 buffer list. If you remove the file from the buffer list, all its marks are

9
runtime/doc/options.txt
View File

@ -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 when 'autoindent' is on. To insert a real tab when 'expandtab' is
on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|. 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) 'exrc' 'ex' boolean (default off)
global global
Automatically execute .nvim.lua, .nvimrc, and .exrc files in the Enables project-local configuration. Nvim will execute any .nvim.lua,
current directory, if the file is in the |trust| list. Use |:trust| to .nvimrc, or .exrc file found in the |current-directory|, if the file is
manage trusted files. See also |vim.secure.read()|. in the |trust| list. Use |:trust| to manage trusted files. See also
|vim.secure.read()|.
Compare 'exrc' to |editorconfig|: Compare 'exrc' to |editorconfig|:
- 'exrc' can execute any code; editorconfig only specifies settings. - 'exrc' can execute any code; editorconfig only specifies settings.

2
runtime/doc/quickref.txt
View File

@ -842,7 +842,7 @@ Short explanation of each option: *option-list*
'selection' 'sel' what type of selection to use 'selection' 'sel' what type of selection to use
'selectmode' 'slm' when to use Select mode instead of Visual mode 'selectmode' 'slm' when to use Select mode instead of Visual mode
'sessionoptions' 'ssop' options for |:mksession| '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 'shell' 'sh' name of shell to use for external commands
'shellcmdflag' 'shcf' flag to shell to execute one command 'shellcmdflag' 'shcf' flag to shell to execute one command
'shellpipe' 'sp' string to put output of ":make" in error file 'shellpipe' 'sp' string to put output of ":make" in error file

3
runtime/doc/terminal.txt
View File

@ -198,6 +198,7 @@ doesn't interfere).
- fish: https://fishshell.com/docs/current/relnotes.html#improved-terminal-support - fish: https://fishshell.com/docs/current/relnotes.html#improved-terminal-support
- kitty: https://sw.kovidgoyal.net/kitty/shell-integration/ - 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 - vscode: https://code.visualstudio.com/docs/terminal/shell-integration
To configure bash to mark the start of each prompt, set $PROMPT_COMMAND: >bash 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 The |]]| and |[[| motions jump to the next/previous prompts, if your shell
emits OSC 133 as described above. 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()| To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()|
from a |TermRequest| handler: >lua from a |TermRequest| handler: >lua

36
runtime/doc/ui.txt
View File

@ -272,9 +272,9 @@ Grid Events (line-based) *ui-linegrid*
Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs. Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs.
Deactivates |ui-grid-old| implicitly. Deactivates |ui-grid-old| implicitly.
The biggest change compared to |ui-grid-old| is to use a single `grid_line` Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to
event to update the contents of a screen line (whereas the old protocol used update a screen-line (whereas the old protocol emitted separate cursor,
a combination of cursor, highlight and text events) highlight and text events per screen-line).
Most of these events take a `grid` index as first parameter. Grid 1 is the 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 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 affected by redefined ids, so UIs do not need to keep track of this
themselves. themselves.
`info` is an empty array by default, and will be used by the `info` is an empty array unless |ui-hlstate| is enabled.
|ui-hlstate| extension explained below.
["hl_group_set", name, hl_id] ~ ["hl_group_set", name, hl_id] ~
The built-in highlight group `name` was set to use the attributes `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|. Activated by the `ext_hlstate` |ui-option|.
Activates |ui-linegrid| implicitly. Activates |ui-linegrid| implicitly.
By default Nvim will only describe grid cells using the final calculated If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in
highlight attributes, as described by the dict keys in |ui-event-highlight_set|. |ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells
The `ext_hlstate` extension allows to the UI to also receive a semantic using the final calculated highlight attributes described at
description of the highlights active in a cell. In this mode highlights will be |ui-event-highlight_set|.
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 `ext_hlstate` provides a semantic description of active highlights for each
of the highlights. As highlight groups can be combined, this will be an array grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define|
of items, with the item with highest priority last. Each item is a dictionary and |ui-event-grid_line|.
with the following possible keys:
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: `kind`: always present. One of the following values:
"ui": Builtin UI highlight. |highlight-groups| "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 This UI extension delegates presentation of the |popupmenu-completion| and
command-line 'wildmenu'. 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] ~ ["popupmenu_show", items, selected, row, col, grid] ~
Show |popupmenu-completion|. `items` is an array of completion items 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 to show; each item is an array of the form [word, kind, menu, info] as

58
runtime/doc/vvars.txt
View File

@ -153,45 +153,43 @@ v:event
an aborting condition (e.g. |c_Esc| or an aborting condition (e.g. |c_Esc| or
|c_CTRL-C| for |CmdlineLeave|). |c_CTRL-C| for |CmdlineLeave|).
chan |channel-id| 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. cmdlevel Level of cmdline.
cmdtype Type of cmdline, |cmdline-char|. 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. cwd Current working directory.
height Height of popup menu on |CompleteChanged|
inclusive Motion is |inclusive|, else exclusive. inclusive Motion is |inclusive|, else exclusive.
scope Event-specific scope name. info Dict of arbitrary event data.
operator Current |operator|. Also set for Ex operator Current |operator|. Also set for Ex
commands (unlike |v:operator|). For commands (unlike |v:operator|). For
example if |TextYankPost| is triggered example if |TextYankPost| is triggered
by the |:yank| Ex command then by the |:yank| Ex command then
`v:event.operator` is "y". `v:event.operator` is "y".
reason |CompleteDone| reason.
regcontents Text stored in the register as a regcontents Text stored in the register as a
|readfile()|-style list of lines. |readfile()|-style list of lines.
regname Requested register (e.g "x" for "xyy) regname Requested register (e.g "x" for "xyy), or
or the empty string for an unnamed empty string for an unnamed operation.
operation.
regtype Type of register as returned by regtype Type of register as returned by
|getregtype()|. |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|, row Row count of popup menu on |CompleteChanged|,
relative to screen. relative to screen.
col Col count of popup menu on |CompleteChanged|, scope Event-specific scope name.
relative to screen. scrollbar |v:true| if popup menu has a scrollbar, or
|v:false| if not.
size Total number of completion items on size Total number of completion items on
|CompleteChanged|. |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| status Job status or exit code, -1 means "unknown". |TermClose|
reason Reason for completion being done. |CompleteDone| visual Selection is visual (as opposed to e.g. a motion range).
complete_word The word that was selected, empty if abandoned complete. width Width of popup menu on |CompleteChanged|
complete_type See |complete_info_mode|
windows List of window IDs that changed on |WinResized| windows List of window IDs that changed on |WinResized|
*v:exception* *exception-variable* *v:exception* *exception-variable*
@ -567,13 +565,19 @@ v:servername
*$NVIM* *$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus $NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim. 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* *shell_error-variable*
v:shell_error v:shell_error

9
runtime/lua/vim/_meta/api.lua generated
View File

@ -485,10 +485,7 @@ function vim.api.nvim_buf_get_offset(buffer, index) end
--- @return any --- @return any
function vim.api.nvim_buf_get_option(buffer, name) end function vim.api.nvim_buf_get_option(buffer, name) end
--- Gets a range from the buffer. --- Gets a range from the buffer (may be partial lines, unlike `nvim_buf_get_lines()`).
---
--- This differs from `nvim_buf_get_lines()` in that it allows retrieving only
--- portions of a line.
--- ---
--- Indexing is zero-based. Row indices are end-inclusive, and column indices --- Indexing is zero-based. Row indices are end-inclusive, and column indices
--- are end-exclusive. --- 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 --- 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 --- 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 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. --- 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 --- @param tabpage integer `tab-ID` to focus
function vim.api.nvim_set_current_tabpage(tabpage) end 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 --- @param window integer `window-ID` to focus
function vim.api.nvim_set_current_win(window) end function vim.api.nvim_set_current_win(window) end

7
runtime/lua/vim/_meta/options.lua generated
View File

@ -2010,9 +2010,10 @@ vim.o.et = vim.o.expandtab
vim.bo.expandtab = vim.o.expandtab vim.bo.expandtab = vim.o.expandtab
vim.bo.et = vim.bo.expandtab vim.bo.et = vim.bo.expandtab
--- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the --- Enables project-local configuration. Nvim will execute any .nvim.lua,
--- current directory, if the file is in the `trust` list. Use `:trust` to --- .nvimrc, or .exrc file found in the `current-directory`, if the file is
--- manage trusted files. See also `vim.secure.read()`. --- in the `trust` list. Use `:trust` to manage trusted files. See also
--- `vim.secure.read()`.
--- ---
--- Compare 'exrc' to `editorconfig`: --- Compare 'exrc' to `editorconfig`:
--- - 'exrc' can execute any code; editorconfig only specifies settings. --- - 'exrc' can execute any code; editorconfig only specifies settings.

60
runtime/lua/vim/_meta/vvars.lua generated
View File

@ -160,45 +160,43 @@ vim.v.errors = ...
--- an aborting condition (e.g. `c_Esc` or --- an aborting condition (e.g. `c_Esc` or
--- `c_CTRL-C` for `CmdlineLeave`). --- `c_CTRL-C` for `CmdlineLeave`).
--- chan `channel-id` --- 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. --- cmdlevel Level of cmdline.
--- cmdtype Type of cmdline, `cmdline-char`. --- 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. --- cwd Current working directory.
--- height Height of popup menu on `CompleteChanged`
--- inclusive Motion is `inclusive`, else exclusive. --- inclusive Motion is `inclusive`, else exclusive.
--- scope Event-specific scope name. --- info Dict of arbitrary event data.
--- operator Current `operator`. Also set for Ex --- operator Current `operator`. Also set for Ex
--- commands (unlike `v:operator`). For --- commands (unlike `v:operator`). For
--- example if `TextYankPost` is triggered --- example if `TextYankPost` is triggered
--- by the `:yank` Ex command then --- by the `:yank` Ex command then
--- `v:event.operator` is "y". --- `v:event.operator` is "y".
--- reason `CompleteDone` reason.
--- regcontents Text stored in the register as a --- regcontents Text stored in the register as a
--- `readfile()`-style list of lines. --- `readfile()`-style list of lines.
--- regname Requested register (e.g "x" for "xyy) --- regname Requested register (e.g "x" for "xyy), or
--- or the empty string for an unnamed --- empty string for an unnamed operation.
--- operation.
--- regtype Type of register as returned by --- regtype Type of register as returned by
--- `getregtype()`. --- `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`, --- row Row count of popup menu on `CompleteChanged`,
--- relative to screen. --- relative to screen.
--- col Col count of popup menu on `CompleteChanged`, --- scope Event-specific scope name.
--- relative to screen. --- scrollbar `v:true` if popup menu has a scrollbar, or
--- `v:false` if not.
--- size Total number of completion items on --- size Total number of completion items on
--- `CompleteChanged`. --- `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` --- status Job status or exit code, -1 means "unknown". `TermClose`
--- reason Reason for completion being done. `CompleteDone` --- visual Selection is visual (as opposed to e.g. a motion range).
--- complete_word The word that was selected, empty if abandoned complete. --- width Width of popup menu on `CompleteChanged`
--- complete_type See `complete_info_mode`
--- windows List of window IDs that changed on `WinResized` --- windows List of window IDs that changed on `WinResized`
--- @type vim.v.event --- @type vim.v.event
vim.v.event = ... vim.v.event = ...
@ -590,15 +588,21 @@ vim.v.searchforward = ...
--- *$NVIM* --- *$NVIM*
--- $NVIM is set by `terminal` and `jobstart()`, and is thus --- $NVIM is set by `terminal` and `jobstart()`, and is thus
--- a hint that the current environment is a subprocess of Nvim. --- a hint that the current environment is a subprocess of Nvim.
--- Example:
--- ---
--- ```vim --- Example: a child Nvim process can detect and make requests to
--- if $NVIM --- its parent Nvim:
--- echo nvim_get_chan_info(v:parent) ---
--- endif --- ```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
--- ``` --- ```
---
--- Note the contents of $NVIM may change in the future.
--- @type string --- @type string
vim.v.servername = ... vim.v.servername = ...

2
runtime/lua/vim/lsp/completion.lua
View File

@ -6,6 +6,8 @@
--- ---
--- Example: activate LSP-driven auto-completion: --- Example: activate LSP-driven auto-completion:
--- ```lua --- ```lua
--- -- Works best with completeopt=noselect.
--- vim.cmd[[set completeopt+=menuone,noselect,popup]]
--- vim.lsp.start({ --- vim.lsp.start({
--- name = 'ts_ls', --- name = 'ts_ls',
--- cmd = …, --- cmd = …,

9
src/nvim/api/buffer.c
View File

@ -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 /// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set. /// `strict_indexing` is set.
/// ///
/// @see |nvim_buf_get_text()|
///
/// @param channel_id /// @param channel_id
/// @param buffer Buffer id, or 0 for current buffer /// @param buffer Buffer id, or 0 for current buffer
/// @param start First line index /// @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 /// 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 /// 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 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. /// 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. /// Gets a range from the buffer (may be partial lines, unlike |nvim_buf_get_lines()|).
///
/// This differs from |nvim_buf_get_lines()| in that it allows retrieving only
/// portions of a line.
/// ///
/// Indexing is zero-based. Row indices are end-inclusive, and column indices /// Indexing is zero-based. Row indices are end-inclusive, and column indices
/// are end-exclusive. /// are end-exclusive.

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

@ -872,7 +872,7 @@ Window nvim_get_current_win(void)
return curwin->handle; 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 window |window-ID| to focus
/// @param[out] err Error details, if any /// @param[out] err Error details, if any

8
src/nvim/options.lua
View File

@ -2663,9 +2663,10 @@ local options = {
abbreviation = 'ex', abbreviation = 'ex',
defaults = false, defaults = false,
desc = [=[ desc = [=[
Automatically execute .nvim.lua, .nvimrc, and .exrc files in the Enables project-local configuration. Nvim will execute any .nvim.lua,
current directory, if the file is in the |trust| list. Use |:trust| to .nvimrc, or .exrc file found in the |current-directory|, if the file is
manage trusted files. See also |vim.secure.read()|. in the |trust| list. Use |:trust| to manage trusted files. See also
|vim.secure.read()|.
Compare 'exrc' to |editorconfig|: Compare 'exrc' to |editorconfig|:
- 'exrc' can execute any code; editorconfig only specifies settings. - 'exrc' can execute any code; editorconfig only specifies settings.
@ -2678,6 +2679,7 @@ local options = {
scope = { 'global' }, scope = { 'global' },
secure = true, secure = true,
short_desc = N_('read .nvimrc and .exrc in the current directory'), short_desc = N_('read .nvimrc and .exrc in the current directory'),
tags = { 'project-config', 'workspace-config' },
type = 'boolean', type = 'boolean',
varname = 'p_exrc', varname = 'p_exrc',
}, },

58
src/nvim/vvars.lua
View File

@ -175,45 +175,43 @@ M.vars = {
an aborting condition (e.g. |c_Esc| or an aborting condition (e.g. |c_Esc| or
|c_CTRL-C| for |CmdlineLeave|). |c_CTRL-C| for |CmdlineLeave|).
chan |channel-id| 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. cmdlevel Level of cmdline.
cmdtype Type of cmdline, |cmdline-char|. 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. cwd Current working directory.
height Height of popup menu on |CompleteChanged|
inclusive Motion is |inclusive|, else exclusive. inclusive Motion is |inclusive|, else exclusive.
scope Event-specific scope name. info Dict of arbitrary event data.
operator Current |operator|. Also set for Ex operator Current |operator|. Also set for Ex
commands (unlike |v:operator|). For commands (unlike |v:operator|). For
example if |TextYankPost| is triggered example if |TextYankPost| is triggered
by the |:yank| Ex command then by the |:yank| Ex command then
`v:event.operator` is "y". `v:event.operator` is "y".
reason |CompleteDone| reason.
regcontents Text stored in the register as a regcontents Text stored in the register as a
|readfile()|-style list of lines. |readfile()|-style list of lines.
regname Requested register (e.g "x" for "xyy) regname Requested register (e.g "x" for "xyy), or
or the empty string for an unnamed empty string for an unnamed operation.
operation.
regtype Type of register as returned by regtype Type of register as returned by
|getregtype()|. |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|, row Row count of popup menu on |CompleteChanged|,
relative to screen. relative to screen.
col Col count of popup menu on |CompleteChanged|, scope Event-specific scope name.
relative to screen. scrollbar |v:true| if popup menu has a scrollbar, or
|v:false| if not.
size Total number of completion items on size Total number of completion items on
|CompleteChanged|. |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| status Job status or exit code, -1 means "unknown". |TermClose|
reason Reason for completion being done. |CompleteDone| visual Selection is visual (as opposed to e.g. a motion range).
complete_word The word that was selected, empty if abandoned complete. width Width of popup menu on |CompleteChanged|
complete_type See |complete_info_mode|
windows List of window IDs that changed on |WinResized| windows List of window IDs that changed on |WinResized|
]=], ]=],
}, },
@ -678,13 +676,19 @@ M.vars = {
*$NVIM* *$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus $NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim. 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 = { shell_error = {