commit 58df501913c17cb3a79f41548088d0f0bcf3a305 parent 54cde0674b41ffd84a97b8e8f93167c00ef26c96 Author: Justin M. Keyes <justinkz@gmail.com> Date: Wed, 18 Jun 2025 13:39:35 +0200 docs: api, pack, events, develop Diffstat:
27 files changed, 175 insertions(+), 204 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt @@ -231,21 +231,19 @@ As Nvim evolves the API may change in compliance with this CONTRACT: - New functions and events may be added. - Any such extensions are OPTIONAL: old clients may ignore them. -- Function signatures will NOT CHANGE (after release), except as follows: - - Functions introduced in the development (unreleased) version MAY CHANGE. - (Clients can dynamically check `api_prerelease`, etc. |api-metadata|) - - New items may be ADDED to map/list parameters/results of functions and - events. - - Any such new items are OPTIONAL: old clients may ignore them. - - Existing items will not be removed (after release). - - Return type may change from void to non-void. Old clients MAY ignore the +- New functions MAY CHANGE before release. Clients can dynamically check + `api_prerelease`, |api-metadata|. +- Function signatures will NOT CHANGE after release, except as follows: + - Map/list parameters/results may be EXTENDED (new fields may be added). + - Such new fields are OPTIONAL: old clients MAY ignore them. + - Existing fields will not be removed. + - Return type MAY CHANGE from void to non-void. Old clients MAY ignore the new return value. - - An `opts` parameter may be added, which is not required in the request. - - Unlimited optional parameters may be added following an `opts` - parameter. + - An optional `opts` parameter may be ADDED. + - Optional parameters may be ADDED following an `opts` parameter. - Event parameters will not be removed or reordered (after release). - Events may be EXTENDED: new parameters may be added. -- Deprecated functions will not be removed until Nvim version 2.0 +- Deprecated functions will not be removed until Nvim 2.0. "Private" interfaces are NOT covered by this contract: diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt @@ -73,7 +73,8 @@ Or use `:execute`: > Note that special characters (e.g., "%", "<cword>") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be expanded when the Event is recognized, and the {cmd} is executed. The only -exception is that "<sfile>" is expanded when the autocmd is defined. Example: +exception is that "<sfile>" (unlike "<script>") is expanded when the autocmd +is defined. Example: > :au BufNewFile,BufRead *.html so <sfile>:h/html.vim @@ -261,7 +262,7 @@ BufLeave Before leaving to another buffer. Also when Not used for ":qa" or ":q" when exiting Vim. *BufModifiedSet* BufModifiedSet After the `'modified'` value of a buffer has - been changed. + been changed. Special-case of |OptionSet|. *BufNew* BufNew After creating a new buffer (except during startup, see |VimEnter|) or renaming an @@ -497,22 +498,11 @@ CompleteDone After Insert mode completion is done. Either abandoned for other reason. *CursorHold* -CursorHold When the user doesn't press a key for the time - specified with 'updatetime'. Not triggered - until the user has pressed a key (i.e. doesn't - fire every 'updatetime' ms if you leave Vim to - make some coffee. :) See |CursorHold-example| - for previewing tags. - This event is only triggered in Normal mode. - It is not triggered when waiting for a command - argument to be typed, or a movement after an - operator. - While recording the CursorHold event is not - triggered. |q| - *<CursorHold>* - Internally the autocommand is triggered by the - <CursorHold> key. In an expression mapping - |getchar()| may see this character. +CursorHold When there is no user input for 'updatetime' + duration, in Normal-mode. Not triggered while + waiting for a command argument or movement + after an operator, nor while |recording| + a macro. See |CursorHold-example|. Note: Interactive commands cannot be used for this event. There is no hit-enter prompt, @@ -837,6 +827,10 @@ OptionSet After setting an option (except during always use |:noautocmd| to prevent triggering OptionSet. + Note: Not triggered by the 'modified' option; + the |BufModifiedSet| event may be used to + handle that. + Non-recursive: |:set| in the autocommand does not trigger OptionSet again. diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt @@ -177,85 +177,85 @@ Put this in `uppercase.vim` and run: >bash ============================================================================== 5. Using a prompt buffer *prompt-buffer* -If you want to type input for the job in a Vim window you have a few options: -- Use a normal buffer and handle all possible commands yourself. - This will be complicated, since there are so many possible commands. -- Use a terminal window. This works well if what you type goes directly to - the job and the job output is directly displayed in the window. - See |terminal|. -- Use a window with a prompt buffer. This works well when entering lines for - the job in Vim while displaying (possibly filtered) output from the job. +Prompt buffers provide a "prompt" interface: they are like regular buffers, +except only the last section of the buffer is editable, and the user can +"submit" the prompt by hitting Enter. Useful for implementing: + +- chat UI +- REPL or shell plugins +- advanced "picker" plugins A prompt buffer is created by setting 'buftype' to "prompt". You would -normally only do that in a newly created buffer. +normally only do that in a newly created buffer: >vim + + :set buftype=prompt -The user can edit and enter text at the very last line of the buffer. Pressing -Enter in the prompt line invokes the |prompt_setcallback()| callback. Use -Shift+Enter to add a new line without submitting the prompt, or paste -multiline text using any |put| or |paste| command. The callback is typically -expected to process the prompt and show results by appending to the buffer, -below the prompt (and above the next prompt). +The user can edit and enter text at the end of the buffer. Pressing Enter in +the prompt section invokes the |prompt_setcallback()| callback, which is +typically expected to process the prompt and show results by appending to the +buffer. To input multiline text, use Shift+Enter to add a new line without +submitting the prompt, or just |put| or |paste| multiline text. -Only the text after the last prompt (starting from the |':| mark), is -user-editable. The rest of the buffer is not modifiable with Normal mode -commands. It can be modified by functions such as |append()|. Using other -commands may mess up the buffer. +Only the "prompt" part of the buffer user-editable, given by the |':| mark. +The rest of the buffer is not modifiable with Normal mode commands, though it +can be modified by functions such as |append()|. Using other commands may +mess up the buffer. -After setting 'buftype' to "prompt" Vim does not automatically start Insert -mode, use `:startinsert` if you want to enter Insert mode, so that the user -can start typing a line. +After setting `buftype=prompt`: +- Nvim unsets the 'comments' option. +- Nvim does not automatically start Insert mode (use `:startinsert` if you + want to enter Insert mode) -The text of the prompt can be set with the |prompt_setprompt()| function. If -no prompt is set with |prompt_setprompt()|, "% " is used. You can get the -effective prompt text for a buffer, with |prompt_getprompt()|. +The prompt prefix defaults to "% ", but can be set with |prompt_setprompt()|. +You can get the effective prompt prefix for with |prompt_getprompt()|. The user can go to Normal mode and navigate through the buffer. This can be useful to see older output or copy text. -The CTRL-W key can be used to start a window command, such as CTRL-W w to -switch to the next window. This also works in Insert mode (use Shift-CTRL-W -to delete a word). When leaving the window Insert mode will be stopped. When -coming back to the prompt window Insert mode will be restored. +By default during prompt insert-mode, the CTRL-W key can be used to start +a window command, such as CTRL-W w to switch to the next window. (Use +Shift-CTRL-W to delete a word). When leaving the window Insert mode will be +stopped. When coming back to the prompt window Insert mode will be restored. Any command that starts Insert mode, such as "a", "i", "A" and "I", will move the cursor to the last line. "A" will move to the end of the line, "I" to the start of the line. -Here is an example for Unix. It starts a shell in the background and prompts -for the next shell command. Output from the shell is displayed above the -prompt. >vim - - " Function handling a line of text that has been typed. - func TextEntered(text) - " Send the text to a shell with Enter appended. - call chansend(g:shell_job, [a:text, '']) - endfunc - - " Function handling output from the shell: Add it above the prompt. - func GotOutput(channel, msg, name) - call append(line("$") - 1, a:msg) - endfunc - - " Function handling the shell exits: close the window. - func JobExit(job, status, event) - quit! - endfunc - - " Start a shell in the background. - let shell_job = jobstart(["/bin/sh"], #{ - \ on_stdout: function('GotOutput'), - \ on_stderr: function('GotOutput'), - \ on_exit: function('JobExit'), - \ }) - - new - set buftype=prompt - let buf = bufnr('') - call prompt_setcallback(buf, function("TextEntered")) - call prompt_setprompt(buf, "shell command: ") - - " start accepting shell commands - startinsert +Example: start a shell in the background and prompt for the next shell +command, displaying shell output above the prompt: >vim + + " Handles a line of user input. + func OnSubmit(text) + " Send the text to a shell with Enter appended. + call chansend(g:shell_job, [a:text, '']) + endfunc + + " Handles output from the shell. + func OnOutput(channel, msg, name) + " Add shell output above the prompt. + call append(line('$') - 1, a:msg) + endfunc + + " Handles the shell exit. + func JobExit(job, status, event) + quit! + endfunc + + " Start a shell in the background. + let shell_job = jobstart(['/bin/sh'], #{ + \ on_stdout: function('OnOutput'), + \ on_stderr: function('OnOutput'), + \ on_exit: function('JobExit'), + \ }) + + new + set buftype=prompt + let buf = bufnr('') + call prompt_setcallback(buf, function('OnSubmit')) + call prompt_setprompt(buf, 'shell command: ') + + " Start accepting shell commands. + startinsert < - vim:tw=78:ts=8:noet:ft=help:norl: + vim:tw=78:ts=8:et:sw=4:ft=help:norl: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt @@ -426,6 +426,9 @@ Use existing common {verb} names (actions) if possible: - add: Appends or inserts into a collection - attach: Listens to something to get events from it (TODO: rename to "on"?) - call: Calls a function + - callback Continuation callback: a single function parameter (not + a field) that returns the result of an async function. Use + "on_…" for all other callbacks and event handlers. - cancel: Cancels or dismisses an event or interaction, typically user-initiated and without error. (Compare "abort", which cancels and signals error/failure.) @@ -444,6 +447,8 @@ Use existing common {verb} names (actions) if possible: - has: Checks for the presence of an item, feature, etc. - inspect: Presents a high-level, often interactive, view - is_enabled: Checks if functionality is enabled. + - on_…: Handles events or async results, or registers such + a handler. |dev-name-events| - open: Opens something (a buffer, window, …) - parse: Parses something into a structured form - set: Sets a thing (or group of things) @@ -477,7 +482,6 @@ everywhere, not "buffer" in some places and "buf" in others. Do NOT use these deprecated nouns: - buffer Use "buf" instead - - callback Use on_foo instead - command Use "cmd" instead - window Use "win" instead @@ -669,6 +673,7 @@ External UIs are expected to implement these common features: - Support the text decorations/attributes given by |ui-event-hl_attr_define|. The "url" attr should be presented as a clickable hyperlink. - Handle the "restart" UI event so that |:restart| works. +- Detect capslock and show an indicator if capslock is active. vim:tw=78:ts=8:sw=4:et:ft=help:norl: diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt @@ -17,6 +17,8 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes specific to the terminal UI. Help tags with the "gui-" prefix refer to UI features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|. + Type |gO| to see the table of contents. + ============================================================================== Third-party GUIs *third-party-guis* *vscode* @@ -34,8 +36,6 @@ a Nvim GUI. - VimR (macOS) https://github.com/qvacua/vimr - Others https://github.com/neovim/neovim/wiki/Related-projects#gui - Type |gO| to see the table of contents. - ============================================================================== Starting the GUI *gui-config* *gui-start* diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt @@ -859,16 +859,13 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) describing the failure reason, and `result` is nil. commands *vim.lsp.commands* - Registry (a table) for client-side handlers, for custom server-commands - that are not in the LSP specification. + Map of client-defined handlers implementing custom (off-spec) commands + which a server may invoke. Each key is a unique command name; each value + is a function which is called when an LSP action (code action, code + lenses, …) requests it by name. - If an LSP response contains a command which is not found in - `vim.lsp.commands`, the command will be executed via the LSP server using - `workspace/executeCommand`. - - Each key in the table is a unique command name, and each value is a - function which is called when an LSP action (code action, code lenses, - …) triggers the command. + If an LSP response requests a command not defined client-side, Nvim will + forward it to the server as `workspace/executeCommand`. • Argument 1 is the `Command`: > Command title: String @@ -1381,13 +1378,8 @@ Lua module: vim.lsp.client *lsp-client* { PORT = 8080; HOST = '0.0.0.0'; } < • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`) - Client commands. Map of command names to - user-defined functions. Commands passed to - `start()` take precedence over the global - command registry. Each key must be a unique - command name, and the value is a function which - is called if any LSP action (code action, code - lenses, …) triggers the command. + Map of client-defined commands overriding the + global |vim.lsp.commands|. • {detached}? (`boolean`, default: `true`) Daemonize the server process so that it runs in a separate process group from Nvim. Nvim will shutdown the diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt @@ -30,16 +30,17 @@ The purpose of this guide is to introduce the different ways of interacting with Nvim through Lua (the "API"). This API consists of three different layers: -1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as -well as |user-function|s in Vimscript. These are accessed through |vim.cmd()| -and |vim.fn| respectively, which are discussed under |lua-guide-vimscript| -below. +1. The "Vim API" inherited from Vim: |Ex-commands| and |vimscript-functions| + as well as |user-function|s in Vimscript. These are accessed through + |vim.cmd()| and |vim.fn| respectively, which are discussed under + |lua-guide-vimscript| below. 2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|. -These functions are accessed through |vim.api|. + These functions are accessed through |vim.api|. 3. The "Lua API" written in and specifically for Lua. These are any other -functions accessible through `vim.*` not mentioned already; see |lua-stdlib|. + functions accessible through `vim.*` not mentioned already; see + |lua-stdlib|. This distinction is important, as API functions inherit behavior from their original layer: For example, Nvim API functions always need all arguments to @@ -223,7 +224,7 @@ Vimscript are automatically converted: vim.fn.jobstart('ls', { on_stdout = print_stdout }) < -This works for both |builtin-functions| and |user-function|s. +This works for both |vimscript-functions| and |user-function|s. Note that hashes (`#`) are not valid characters for identifiers in Lua, so, e.g., |autoload| functions have to be called with this syntax: @@ -232,9 +233,9 @@ e.g., |autoload| functions have to be called with this syntax: < ------------------------------------------------------------------------------ See also: -• |builtin-functions|: alphabetic list of all Vimscript functions -• |function-list|: list of all Vimscript functions grouped by topic -• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'| +• |vimscript-functions|: descriptions of all Vimscript functions +• |function-list|: Vimscript functions grouped by topic +• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'| ============================================================================== Variables *lua-guide-variables* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt @@ -3177,12 +3177,12 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* Examples: >lua -- Map "x" to a Lua function: - vim.keymap.set('n', 'x', function() print("real lua function") end) + vim.keymap.set('n', 'x', function() print('real lua function') end) -- Map "<leader>x" to multiple modes for the current buffer: vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true }) -- Map <Tab> to an expression (|:map-<expr>|): vim.keymap.set('i', '<Tab>', function() - return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" + return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>' end, { expr = true }) -- Map "[%%" to a <Plug> mapping: vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt @@ -1178,10 +1178,10 @@ A jump table for the options with a short description can be found at |Q_op|. help help buffer (do not set this manually) nofile buffer is not related to a file, will not be written nowrite buffer will not be written + prompt buffer where only the last section can be edited, for + use by plugins. |prompt-buffer| quickfix list of errors |:cwindow| or locations |:lwindow| terminal |terminal-emulator| buffer - prompt buffer where only the last line can be edited, meant - to be used by a plugin, see |prompt-buffer| This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt @@ -265,24 +265,24 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. about each searched file. *:pa* *:packadd* *E919* -:pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath' - and source any plugin files found. The directory must - match: - pack/*/opt/{name} ~ - The directory is added to 'runtimepath' if it wasn't - there yet. - If the directory pack/*/opt/{name}/after exists it is +:pa[ckadd][!] {name} |pack-add| Search for an optional plugin directory in + 'packpath', source any plugin files found, and add it + to 'runtimepath'. The directory must match: > + pack/*/opt/{name} +< If the directory pack/*/opt/{name}/after exists it is added at the end of 'runtimepath'. - If loading packages from "pack/*/start" was skipped, - then this directory is searched first: - pack/*/start/{name} ~ + Note: Use |vim.pack.add()) to install from a URL. + If loading packages from "pack/*/start" was skipped, + then this directory is searched first: > + pack/*/start/{name} +< Note that {name} is the directory name, not the name - of the .vim file. All files matching the patterns - pack/*/opt/{name}/plugin/**/*.vim ~ - pack/*/opt/{name}/plugin/**/*.lua ~ - will be sourced. This allows for using subdirectories + of the .vim file. All files matching the patterns > + pack/*/opt/{name}/plugin/**/*.vim + pack/*/opt/{name}/plugin/**/*.lua +< will be sourced. This allows for using subdirectories below "plugin", just like with plugins in 'runtimepath'. @@ -293,17 +293,14 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. "pack/*/opt/{name}", this command will also look for "{name}/ftdetect/*.vim" files. - When the optional ! is added no plugin files or - ftdetect scripts are loaded, only the matching + When the optional "!" is given, no plugin/ files or + ftdetect/ scripts are loaded, only the matching directories are added to 'runtimepath'. This is useful in your |init.vim|. The plugins will then be - loaded during |initialization|, see |load-plugins| (note - that the loading order will be reversed, because each - directory is inserted before others). In this case, the - ftdetect scripts will be loaded during |initialization|, - before the |load-plugins| step. - - Also see |pack-add|. + loaded during the |load-plugins| |initialization| step + (note that the loading order will be reversed because + each directory is inserted before others), after + loading the ftdetect scripts. *:packl* *:packloadall* :packl[oadall][!] Load all packages in the "start" directory under each diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL -Nvim UI protocol *UI* *ui* +Nvim UI protocol *UI* *ui* *api-ui-events* Type |gO| to see the table of contents. diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt @@ -588,7 +588,7 @@ after the substitute() call. FUNCTIONS *function-list* There are many functions. We will mention them here, grouped by what they are -used for. You can find an alphabetical list here: |builtin-function-details|. +used for. You can find an alphabetical list here: |vimscript-functions|. Use CTRL-] on the function name to jump to detailed help on it. String manipulation: *string-functions* diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt @@ -1813,7 +1813,7 @@ functions. Scripts can also define |user-function|s. See |function-list| to browse functions by topic. The alphabetic list of all builtin functions and details are in a separate -help file: |builtin-functions|. +help file: |vimscript-functions|. ============================================================================== 5. Defining functions *user-function* diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt @@ -4,13 +4,13 @@ NVIM REFERENCE MANUAL -Vimscript functions *vimscript-functions* *builtin-functions* *builtin.txt* +Vimscript functions *vimscript-functions* *builtin.txt* For functions grouped by what they are used for see |function-list|. Type |gO| to see the table of contents. ============================================================================== -1. Details *builtin-function-details* +1. Details *vimscript-functions-details* abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to @@ -3165,8 +3165,7 @@ getchar([{expr} [, {opts}]]) *getchar()* Return zero otherwise. If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. - If you prefer always getting a string use |getcharstr()|, or - specify |FALSE| as "number" in {opts}. + To always get a string, specify "number" as |FALSE| in {opts}. Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua @@ -619,10 +619,10 @@ vim.bo.bl = vim.bo.buflisted --- help help buffer (do not set this manually) --- nofile buffer is not related to a file, will not be written --- nowrite buffer will not be written +--- prompt buffer where only the last section can be edited, for +--- use by plugins. `prompt-buffer` --- quickfix list of errors `:cwindow` or locations `:lwindow` --- terminal `terminal-emulator` buffer ---- prompt buffer where only the last line can be edited, meant ---- to be used by a plugin, see `prompt-buffer` --- --- This option is used together with 'bufhidden' and 'swapfile' to --- specify special kinds of buffers. See `special-buffers`. diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua @@ -2828,8 +2828,7 @@ function vim.fn.getchangelist(buf) end --- Return zero otherwise. --- If {expr} is 1, only check if a character is available, it is --- not consumed. Return zero if no character available. ---- If you prefer always getting a string use |getcharstr()|, or ---- specify |FALSE| as "number" in {opts}. +--- To always get a string, specify "number" as |FALSE| in {opts}. --- --- Without {expr} and when {expr} is 0 a whole character or --- special key is returned. If it is a single character, the diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua @@ -21,12 +21,12 @@ local keymap = {} --- --- ```lua --- -- Map "x" to a Lua function: ---- vim.keymap.set('n', 'x', function() print("real lua function") end) +--- vim.keymap.set('n', 'x', function() print('real lua function') end) --- -- Map "<leader>x" to multiple modes for the current buffer: --- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true }) --- -- Map <Tab> to an expression (|:map-<expr>|): --- vim.keymap.set('i', '<Tab>', function() ---- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" +--- return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>' --- end, { expr = true }) --- -- Map "[%%" to a <Plug> mapping: --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua @@ -1653,14 +1653,12 @@ function lsp.with(handler, override_config) end end ---- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP ---- specification. +--- Map of client-defined handlers implementing custom (off-spec) commands which a server may +--- invoke. Each key is a unique command name; each value is a function which is called when an LSP +--- action (code action, code lenses, …) requests it by name. --- ---- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will ---- be executed via the LSP server using `workspace/executeCommand`. ---- ---- Each key in the table is a unique command name, and each value is a function which is called ---- when an LSP action (code action, code lenses, …) triggers the command. +--- If an LSP response requests a command not defined client-side, Nvim will forward it to the +--- server as `workspace/executeCommand`. --- --- - Argument 1 is the `Command`: --- ``` @@ -1686,7 +1684,7 @@ end --- end --- ``` --- ---- @type table<string,function> +--- @type table<string,fun(command: lsp.Command, ctx: table)> lsp.commands = setmetatable({}, { __newindex = function(tbl, key, value) assert(type(key) == 'string', 'The key for commands in `vim.lsp.commands` must be a string') diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua @@ -63,10 +63,7 @@ local validate = vim.validate --- ``` --- @field cmd_env? table --- ---- Client commands. Map of command names to user-defined functions. Commands passed to `start()` ---- take precedence over the global command registry. Each key must be a unique command name, and ---- the value is a function which is called if any LSP action (code action, code lenses, …) triggers ---- the command. +--- Map of client-defined commands overriding the global |vim.lsp.commands|. --- @field commands? table<string,fun(command: lsp.Command, ctx: table)> --- --- Daemonize the server process so that it runs in a separate process group from Nvim. diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua @@ -858,13 +858,13 @@ local CONFIG = { '\t\t NVIM REFERENCE MANUAL', '', '', - 'Vimscript functions\t*vimscript-functions* *builtin-functions* *builtin.txt*', + 'Vimscript functions\t\t\t*vimscript-functions* *builtin.txt*', '', 'For functions grouped by what they are used for see |function-list|.', '', '\t\t\t\t Type |gO| to see the table of contents.', '==============================================================================', - '1. Details *builtin-function-details*', + '1. Details *vimscript-functions-details*', '', }, footer = { diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua @@ -88,8 +88,9 @@ local new_layout = { -- Map of new:old pages, to redirect renamed pages. local redirects = { ['credits'] = 'backers', - ['tui'] = 'term', ['terminal'] = 'nvim_terminal_emulator', + ['tui'] = 'term', + ['api-ui-events'] = 'ui', } -- TODO: These known invalid |links| require an update to the relevant docs. @@ -1343,7 +1344,10 @@ This document moved to: |%s| local redirect_to = ('%s/%s'):format(to_dir, get_helppage(redirect_from)) local redirect_html, _ = gen_one(redirect_from, redirect_text, redirect_to, false, commit or '?', parser_path) - assert(redirect_html:find(helpfile_tag)) + assert( + redirect_html:find(vim.pesc(helpfile_tag)), + ('not found in redirect html: %s'):format(helpfile_tag) + ) tofile(redirect_to, redirect_html) print( diff --git a/src/nvim/CMakeLists.txt b/src/nvim/CMakeLists.txt @@ -157,8 +157,7 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Darwin") target_link_libraries(nvim_bin PRIVATE "-framework CoreServices") # Actually export symbols - symbols may not be visible even though - # ENABLE_EXPORTS is set to true. See - # https://github.com/neovim/neovim/issues/25295 + # ENABLE_EXPORTS is set. https://github.com/neovim/neovim/issues/25295 target_link_options(nvim_bin PRIVATE "-Wl,-export_dynamic") elseif(CMAKE_SYSTEM_NAME MATCHES "OpenBSD") target_link_libraries(main_lib INTERFACE pthread c++abi) diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua @@ -3564,8 +3564,7 @@ M.funcs = { Return zero otherwise. If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. - If you prefer always getting a string use |getcharstr()|, or - specify |FALSE| as "number" in {opts}. + To always get a string, specify "number" as |FALSE| in {opts}. Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the diff --git a/src/nvim/options.lua b/src/nvim/options.lua @@ -903,10 +903,10 @@ local options = { help help buffer (do not set this manually) nofile buffer is not related to a file, will not be written nowrite buffer will not be written + prompt buffer where only the last section can be edited, for + use by plugins. |prompt-buffer| quickfix list of errors |:cwindow| or locations |:lwindow| terminal |terminal-emulator| buffer - prompt buffer where only the last line can be edited, meant - to be used by a plugin, see |prompt-buffer| This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. diff --git a/test/functional/lua/system_spec.lua b/test/functional/lua/system_spec.lua @@ -74,23 +74,12 @@ describe('vim.system', function() end) it('can set environment', function() - eq( - 'TESTVAL', - system( - { n.testprg('printenv-test'), 'TEST' }, - { env = { TEST = 'TESTVAL' }, text = true } - ).stdout - ) - end) + local function test_env(opt) + eq('TESTVAL', system({ n.testprg('printenv-test'), 'TEST' }, opt).stdout) + end - it('can set environment with clear_env = true', function() - eq( - 'TESTVAL', - system( - { n.testprg('printenv-test'), 'TEST' }, - { clear_env = true, env = { TEST = 'TESTVAL' }, text = true } - ).stdout - ) + test_env({ env = { TEST = 'TESTVAL' }, text = true }) + test_env({ clear_env = true, env = { TEST = 'TESTVAL' }, text = true }) end) it('can set environment with clear_env = true and env = nil', function() diff --git a/test/functional/vimscript/eval_spec.lua b/test/functional/vimscript/eval_spec.lua @@ -5,7 +5,7 @@ -- null_spec.lua -- operators_spec.lua -- --- Tests for the Vimscript |builtin-functions| library should live in: +-- Tests for the Vimscript |vimscript-functions| library should live in: -- test/functional/vimscript/<funcname>_spec.lua -- test/functional/vimscript/functions_spec.lua diff --git a/test/functional/vimscript/functions_spec.lua b/test/functional/vimscript/functions_spec.lua @@ -1,4 +1,4 @@ --- Tests for misc Vimscript |builtin-functions|. +-- Tests for misc Vimscript |vimscript-functions|. -- -- If a function is non-trivial, consider moving its spec to: -- test/functional/vimscript/<funcname>_spec.lua