commit 56a4ef3c213d87bfba5f361376bd23eefdf6c6ec parent dc67ba948eec0a5628eff0b15ce87a7d27f58bb3 Author: Justin M. Keyes <justinkz@gmail.com> Date: Fri, 11 Jul 2025 08:33:29 -0400 docs: lsp, ui events, dev guidance, osc7 fix #34981 Diffstat:
32 files changed, 229 insertions(+), 223 deletions(-)
diff --git a/runtime/doc/api-ui-events.txt b/runtime/doc/api-ui-events.txt @@ -882,6 +882,12 @@ must handle. clearing the screen (messages sent by other "msg_" events below should not be affected). + Guidance: The "clear messages" behavior is UI-specific. If the UI + presents messages in a new window, it may choose to clear messages + after a few seconds. If the UI presents messages in a persistent area + (e.g. cmdline), it should clear messages at the start of the next + batch (typically, the next event-loop cycle). + ["msg_showmode", content] ~ Shows 'showmode' and |recording| messages. `content` has the same format as in "msg_show". This event is sent with empty `content` to diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt @@ -1311,6 +1311,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with the internal representation. + Note: ~ + • Lua can use |vim.keycode()| instead. + Attributes: ~ Since: 0.1.0 diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt @@ -353,7 +353,7 @@ Where possible, these patterns apply to _both_ Lua and the API: - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()| - Any function signature that accepts a callback (example: |table.foreach()|) should place it as the LAST parameter (after opts), if possible (or ALWAYS - for "continuation callbacks"—functions called exactly once). + for |continuation|s——functions called exactly once). - Improves readability by placing the less "noisy" arguments near the start. - Consistent with luv. - Useful for future async lib which transforms functions of the form @@ -426,9 +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. + - callback |continuation|: Function parameter (NOT a field) that + returns the result of an async function. Use the "on_…" + naming-convention 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.) @@ -499,6 +499,14 @@ Use this format to name API (RPC) events: > Example: > nvim_buf_changedtick_event < + *continuation* +A "continuation" is implemented as a callback function that returns the result +of an async function and is called exactly once. Often accepts `err` as the +first parameter, to avoid erroring on the main thread. Example: > + foo(…, callback: fun(err, …)) +Use the name `callback` only for a continuation. All other callbacks and event +handlers should be named with the |dev-name-events| "on_…" convention. + *dev-api-name* Use this format to name new RPC |API| functions: > nvim_{topic}_{verb}_{arbitrary-qualifiers} diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt @@ -1242,10 +1242,10 @@ MULTIPLE WINDOWS AND BUFFERS *window-exit* *:confirm* *:conf* :conf[irm] {command} Execute {command}, and use a dialog when an operation has to be confirmed. Can be used on the - |:edit|, |:q|, |:qa| and |:w| commands (the latter to - override a read-only setting), and any commands that - can fail because of unsaved changes, such as |:only|, - |:buffer|, |:bdelete|, etc. + |:edit|, |:restart|, |:q|, |:qa| and |:w| commands + (the latter to override a read-only setting), and any + commands that can fail because of unsaved changes, + such as |:only|, |:buffer|, |:bdelete|, etc. Examples: > :confirm w foo diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt @@ -112,7 +112,6 @@ API (EXTENSIBILITY/SCRIPTING/PLUGINS) |channel| Nvim asynchronous IO |vimscript| Vimscript reference |vimscript-functions| Vimscript functions -|testing.txt| Vimscript testing functions |remote-plugin| Nvim remote plugins |health| Health checking diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt @@ -28,26 +28,19 @@ Follow these steps to get LSP features: upstream installation instructions. You can find language servers here: https://microsoft.github.io/language-server-protocol/implementors/servers/ -2. Use |vim.lsp.config()| to define a configuration for an LSP client - (see https://github.com/neovim/nvim-lspconfig for examples). +2. Define a new config |lsp-new-config| (or install https://github.com/neovim/nvim-lspconfig). Example: >lua vim.lsp.config['luals'] = { -- Command and arguments to start the server. cmd = { 'lua-language-server' }, - -- Filetypes to automatically attach to. filetypes = { 'lua' }, - - -- Sets the "root directory" to the parent directory of the file in the - -- current buffer that contains either a ".luarc.json" or a - -- ".luarc.jsonc" file. Files that share a root directory will reuse - -- the connection to the same LSP server. + -- Sets the "workspace" to the directory where any of these files is found. + -- Files that share a root directory will reuse the LSP server connection. -- Nested lists indicate equal priority, see |vim.lsp.Config|. root_markers = { { '.luarc.json', '.luarc.jsonc' }, '.git' }, - - -- Specific settings to send to the server. The schema for this is - -- defined by the server. For example the schema for lua-language-server - -- can be found here https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json + -- Specific settings to send to the server. The schema is server-defined. + -- Example: https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json settings = { Lua = { runtime = { @@ -57,7 +50,7 @@ Follow these steps to get LSP features: } } -3. Use |vim.lsp.enable()| to enable a configuration. +3. Use |vim.lsp.enable()| to enable the config. Example: >lua vim.lsp.enable('luals') < @@ -130,21 +123,46 @@ 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): +Use |vim.lsp.config()| to define or modify LSP configurations, and +|vim.lsp.enable()| to auto-activate them. This is basically a wrapper around +|vim.lsp.start()| which allows you to share and merge configs (provided by +Nvim, plugins, and your local config). + + *lsp-new-config* +To create a new config you can either use `vim.lsp.config()` or create +a `lsp/<config-name>.lua` file. + +EXAMPLE: DEFINE A CONFIG AS CODE ~ + +1. Run `:lua vim.lsp.config('foo', {cmd={'true'}})` +2. Run `:lua vim.lsp.enable('foo')` +3. Run `:checkhealth vim.lsp`, check "Enabled Configurations". 😎 + +EXAMPLE: DEFINE A CONFIG AS A FILE ~ + +1. Create a file `lsp/foo.lua` somewhere on your 'runtimepath'. > + :exe 'edit' stdpath('config') .. '/lsp/foo.lua' +2. Add this code to the file (or copy an example from + https://github.com/neovim/nvim-lspconfig): > + return { + cmd = { 'true' }, + } +3. Save the file (with `++p` to ensure its parent directory is created). > + :write ++p +4. Enable the config. > + :lua vim.lsp.enable('foo') +5. Run `:checkhealth vim.lsp`, check "Enabled Configurations". 🌈 + + *lsp-config-merge* +When an LSP client starts, it resolves its configuration by merging the +following sources (merge semantics defined by |vim.tbl_deep_extend()|), in +order of 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('*', { diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt @@ -191,7 +191,7 @@ IMPORTING LUA MODULES *lua-module-load* Modules are searched for under the directories specified in 'runtimepath' and |packages-runtimepath|, in the order they appear in the output of this command >vim - :echo nvim_list_runtime_paths() + :echo nvim_list_runtime_paths() < Any "." in the module name is treated as a directory separator when searching. For a module `foo.bar`, each directory is searched for `lua/foo/bar.lua`, then @@ -230,6 +230,11 @@ Note: plugins using shell, which will not work with paths containing semicolons, it is better to not have them in 'runtimepath' at all. + *lua-script-location* +To get its own location, Lua scripts/modules can use |debug.getinfo()|: > + debug.getinfo(1, 'S').source:sub(2) +< + ============================================================================== COMMANDS *lua-commands* @@ -1784,6 +1789,10 @@ SystemObj:write({data}) *SystemObj:write()* vim.system({cmd}, {opts}, {on_exit}) *vim.system()* Runs a system command or throws an error if {cmd} cannot be run. + The command runs directly (not in 'shell') so shell builtins such as + "echo" in cmd.exe, cmdlets in powershell, or "help" in bash, will not work + unless you actually invoke a shell: `vim.system({'bash', '-c', 'help'})`. + Examples: >lua local on_exit = function(obj) print(obj.code) diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt @@ -63,10 +63,7 @@ DIAGNOSTICS EDITOR -• |vim.secure.read()| now removes the choice "(a)llow" from the prompt reply for - files unlisted in the user's trust database, and thus requires the user to - choose (v)iew then run `:trust`. Previously the user would be able to press - the single key 'a' to execute the arbitrary execution immediately. +• todo EVENTS @@ -174,6 +171,8 @@ EDITOR commands. • 'wildchar' now enables completion in search contexts using |/|, |?|, |:g|, |:v| and |:vimgrep| commands. +• For security, 'exrc' no longer shows an "(a)llow" choice. Instead you must + "(v)iew" then run `:trust`. EVENTS @@ -277,7 +276,7 @@ TERMINAL TREESITTER -• todo +• |:EditQuery| command gained tab-completion, works with injected languages. TUI diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt @@ -2566,7 +2566,8 @@ A jump table for the options with a short description can be found at |Q_op|. Unset 'exrc' to stop further searching of 'exrc' files in parent directories, similar to |editorconfig.root|. - To get its own location, Lua exrc files can use |debug.getinfo()|. + To get its own location, a Lua exrc file can use |debug.getinfo()|. + See |lua-script-location|. Compare 'exrc' to |editorconfig|: - 'exrc' can execute any code; editorconfig only specifies settings. @@ -2576,7 +2577,7 @@ A jump table for the options with a short description can be found at |Q_op|. 1. Enable 'exrc'. 2. Place LSP configs at ".nvim/lsp/*.lua" in your project root. 3. Create ".nvim.lua" in your project root directory with this line: >lua - vim.cmd[[set runtimepath+=.nvim]] + vim.cmd[[set runtimepath+=.nvim]] < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt @@ -191,7 +191,7 @@ Using Vim scripts *using-scripts* For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. - *:so* *:source* *load-vim-script* + *:so* *:source* :so[urce] {file} Runs |Ex-commands| or Lua code (".lua" files) from {file}. Triggers the |SourcePre| autocommand. diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt @@ -138,35 +138,43 @@ exposes via the |TermRequest| event. OSC 7: change working directory *terminal-osc7* -To handle OSC 7 emitted from :terminal processes, this code will :cd to the -directory indicated in the request. >lua +Shells can emit the "OSC 7" sequence to announce when the current directory +(CWD) changed. + +You can configure your shell init (e.g. ~/.bashrc) to emit OSC 7, or your +terminal may attempt to do it for you. + +To configure bash to emit OSC 7: >bash + function print_osc7() { + printf '\033]7;file://%s\033\\' "$PWD" + } + PROMPT_COMMAND='print_osc7' + +Having ensured that your shell emits OSC 7, you can now handle it in Nvim. The +following code will run :lcd whenever your shell CWD changes in a :terminal +buffer: >lua vim.api.nvim_create_autocmd({ 'TermRequest' }, { desc = 'Handles OSC 7 dir change requests', callback = function(ev) - if string.sub(ev.data.sequence, 1, 4) == '\x1b]7;' then - local dir = string.gsub(ev.data.sequence, '\x1b]7;file://[^/]*', '') + local val, n = string.gsub(ev.data.sequence, '\027]7;file://[^/]*', '') + if n > 0 then + -- OSC 7: dir-change + local dir = val if vim.fn.isdirectory(dir) == 0 then vim.notify('invalid dir: '..dir) return end - vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir) - if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then - vim.cmd.cd(dir) + vim.b[ev.buf].osc7_dir = dir + if vim.api.nvim_get_current_buf() == ev.buf then + vim.cmd.lcd(dir) end end end }) - vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, { - callback = function(ev) - if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then - vim.cmd.cd(vim.b.osc7_dir) - end - end - }) -To try it out, select the above code and source it with `:'<,'>lua` (or -`g==`), then run this command in a :terminal buffer: > +To try it out, select the above code and source it with `:'<,'>lua`, then run +this command in a :terminal buffer: > printf "\033]7;file://./foo/bar\033\\" @@ -191,7 +199,7 @@ Shells can emit semantic escape sequences (OSC 133) to mark where each prompt starts and ends. The start of a prompt is marked by sequence `OSC 133 ; A ST`, and the end by `OSC 133 ; B ST`. -You can configure your shell "rc" (e.g. ~/.bashrc) to emit OSC 133 sequences, +You can configure your shell init (e.g. ~/.bashrc) to emit OSC 133 sequences, or your terminal may attempt to do it for you (assuming your shell config doesn't interfere). diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt @@ -1,54 +0,0 @@ -*testing.txt* Nvim - - - VIM REFERENCE MANUAL by Bram Moolenaar - - -Testing Vim and Vim script *testing-support* - -Expression evaluation is explained in |eval.txt|. This file goes into details -about writing tests in Vim script. This can be used for testing Vim itself -and for testing plugins. - -1. Testing Vim |testing| -2. Test functions |test-functions-details| -3. Assert functions |assert-functions-details| - -============================================================================== -1. Testing Vim *testing* - -Vim can be tested after building it, usually with "make test". -The tests are located in the directory "src/testdir". - - *new-style-testing* -New tests should be added as new style tests. The test scripts are named -test_<feature>.vim (replace <feature> with the feature under test). These use -functions such as |assert_equal()| to keep the test commands and the expected -result in one place. - -Find more information in the file src/testdir/README.txt. - -============================================================================== -2. Test functions *test-functions-details* - -See |test_garbagecollect_now()|. - -============================================================================== -3. Assert functions *assert-functions-details* - -See: - - |assert_beeps()| - - |assert_equal()| - - |assert_equalfile()| - - |assert_exception()| - - |assert_fails()| - - |assert_false()| - - |assert_inrange()| - - |assert_match()| - - |assert_nobeep()| - - |assert_notequal()| - - |assert_notmatch()| - - |assert_report()| - - |assert_true()| - - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt @@ -1321,10 +1321,8 @@ add_predicate({name}, {handler}, {opts}) edit({lang}) *vim.treesitter.query.edit()* Opens a live editor to query the buffer you started from. - Can also be shown with `:EditQuery`. *:EditQuery* - - `:EditQuery <tab>` completes the treesitter parser names in the runtime - path. + Can also be shown with the *:EditQuery* command. `:EditQuery <tab>` + completes available parsers. If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in the source buffer. The query editor is a scratch diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt @@ -31,7 +31,7 @@ script. There are a lot of them, thus this is a long chapter. Table of contents: |usr_toc.txt| ============================================================================== -*41.1* Introduction *vim-script-intro* *script* +*41.1* Introduction *vimscript-intro* Your first experience with Vim scripts is the vimrc file. Vim reads it when it starts up and executes the commands. You can set options to values you diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt @@ -248,10 +248,15 @@ gx Opens the current filepath or URL (decided by :sh[ell] Removed. |vim-differences| *:terminal* *:te* -:te[rminal][!] [{cmd}] Run {cmd} in a non-interactive 'shell' in a new - |terminal-emulator| buffer. Without {cmd}, start an +:te[rminal][!] [cmd] Run [cmd] in a non-interactive 'shell' in a new + |terminal-emulator| buffer. Without [cmd], start an interactive 'shell'. + By default the current window is used. To open in + a split window, use |:horizontal| or |:vertical|: > + :hor te + :vert te +< Type |i| to enter |Terminal-mode|, then keys are sent to the job running in the terminal. Type <C-\><C-N> to leave Terminal-mode. |CTRL-\_CTRL-N|. Type <C-\><C-O> @@ -260,7 +265,7 @@ gx Opens the current filepath or URL (decided by Fails if changes have been made to the current buffer, unless 'hidden' is set. - If {cmd} is omitted, and the 'shell' job exits with no + If [cmd] is omitted, and the 'shell' job exits with no error, the buffer is closed automatically |default-autocmds|. diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt @@ -3774,7 +3774,7 @@ This is not allowed when the textlock is active: - etc. ============================================================================== -Vim script library *vim-script-library* +Vim script library *vimscript-library* Vim comes bundled with a Vim script library, that can be used by runtime, script authors. Currently, it only includes very few functions, but it may diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt @@ -2098,35 +2098,35 @@ expand({string} [, {nosuf} [, {list}]]) *expand()* done like for the |cmdline-special| variables with their associated modifiers. Here is a short overview: - % current file name - # alternate file name - #n alternate file name n - <cfile> file name under the cursor - <afile> autocmd file name - <abuf> autocmd buffer number (as a String!) - <amatch> autocmd matched name + % Current file name + # Alternate file name + #n Alternate file name n + <cfile> File name under the cursor + <afile> Autocmd file name + <abuf> Autocmd buffer number (as a String!) + <amatch> Autocmd matched name <cexpr> C expression under the cursor - <sfile> deprecated, use <script> or <stack> - <slnum> sourced script line number or function + <sfile> Deprecated, use <script> or <stack> + <slnum> Sourced script line number or function line number - <sflnum> script file line number, also when in + <sflnum> Script file line number, also when in a function <SID> "<SNR>123_" where "123" is the current script ID |<SID>| - <script> sourced script file, or script file + <script> Sourced script file, or script file where the current function was defined. - Use |debug.getinfo()| in Lua scripts. - <stack> call stack - <cword> word under the cursor + For Lua see |lua-script-location|. + <stack> Call stack + <cword> Word under the cursor <cWORD> WORD under the cursor - <client> the {clientid} of the last received + <client> The {clientid} of the last received message Modifiers: - :p expand to full path - :h head (last path component removed) - :t tail (last path component only) - :r root (one extension removed) - :e extension only + :p Expand to full path + :h Head (last path component removed) + :t Tail (last path component only) + :r Root (one extension removed) + :e Extension only Example: >vim let &tags = expand("%:p:h") .. "/tags" diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt @@ -257,8 +257,8 @@ and 'winminwidth' are relevant. *:hor* *:horizontal* :hor[izontal] {cmd} - Execute {cmd}. Currently only makes a difference for - the following commands: + Execute {cmd} in a horizontal split window. Supports these + commands: - `:wincmd =`: equalize windows only horizontally. - |:terminal|: open a |terminal| buffer in a split window. - |:checkhealth|: open a healthcheck buffer in a split window. diff --git a/runtime/lua/vim/_core/server.lua b/runtime/lua/vim/_core/server.lua @@ -1,17 +1,18 @@ local M = {} ---- Called by builtin serverlist(). Returns all running servers. ---- in stdpath("run"). Does not include named pipes or TCP servers. +--- Called by builtin serverlist(). Returns all running servers in stdpath("run"). +--- +--- - TODO: track TCP servers, somehow. +--- - TODO: support Windows named pipes. --- --- @param listed string[] Already listed servers ---- @return string[] A list of currently running servers in stdpath("run") +--- @return string[] # List of servers found on the current machine in stdpath("run"). function M.serverlist(listed) - -- TODO: also get named pipes on Windows local socket_paths = vim.fs.find(function(name, _) return name:match('nvim.*') end, { path = vim.fn.stdpath('run'), type = 'socket', limit = math.huge }) - local running_sockets = {} + local found = {} ---@type string[] for _, socket in ipairs(socket_paths) do -- Don't list servers twice if not vim.list_contains(listed, socket) then @@ -20,14 +21,14 @@ function M.serverlist(listed) -- Check that the server is responding -- TODO: do we need a timeout or error handling here? if vim.fn.rpcrequest(chan, 'nvim_get_chan_info', 0).id then - table.insert(running_sockets, socket) + table.insert(found, socket) end vim.fn.chanclose(chan) end end end - return running_sockets + return found end return M diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua @@ -2045,6 +2045,10 @@ function vim.api.nvim_put(lines, type, after, follow) end --- Replaces terminal codes and `keycodes` ([<CR>], [<Esc>], ...) in a string with --- the internal representation. --- +--- +--- Note: +--- Lua can use |vim.keycode()| instead. +--- --- @see replace_termcodes --- @see cpoptions --- @param str string String to be converted. diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua @@ -2239,7 +2239,8 @@ vim.bo.et = vim.bo.expandtab --- Unset 'exrc' to stop further searching of 'exrc' files in parent --- directories, similar to `editorconfig.root`. --- ---- To get its own location, Lua exrc files can use `debug.getinfo()`. +--- To get its own location, a Lua exrc file can use `debug.getinfo()`. +--- See `lua-script-location`. --- --- Compare 'exrc' to `editorconfig`: --- - 'exrc' can execute any code; editorconfig only specifies settings. @@ -2251,7 +2252,7 @@ vim.bo.et = vim.bo.expandtab --- 3. Create ".nvim.lua" in your project root directory with this line: --- --- ```lua ---- vim.cmd[[set runtimepath+=.nvim]] +--- vim.cmd[[set runtimepath+=.nvim]] --- ``` --- --- This option cannot be set from a `modeline` or in the `sandbox`, for diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua @@ -1855,35 +1855,35 @@ function vim.fn.exp(expr) end --- done like for the |cmdline-special| variables with their --- associated modifiers. Here is a short overview: --- ---- % current file name ---- # alternate file name ---- #n alternate file name n ---- <cfile> file name under the cursor ---- <afile> autocmd file name ---- <abuf> autocmd buffer number (as a String!) ---- <amatch> autocmd matched name +--- % Current file name +--- # Alternate file name +--- #n Alternate file name n +--- <cfile> File name under the cursor +--- <afile> Autocmd file name +--- <abuf> Autocmd buffer number (as a String!) +--- <amatch> Autocmd matched name --- <cexpr> C expression under the cursor ---- <sfile> deprecated, use <script> or <stack> ---- <slnum> sourced script line number or function +--- <sfile> Deprecated, use <script> or <stack> +--- <slnum> Sourced script line number or function --- line number ---- <sflnum> script file line number, also when in +--- <sflnum> Script file line number, also when in --- a function --- <SID> "<SNR>123_" where "123" is the --- current script ID |<SID>| ---- <script> sourced script file, or script file +--- <script> Sourced script file, or script file --- where the current function was defined. ---- Use |debug.getinfo()| in Lua scripts. ---- <stack> call stack ---- <cword> word under the cursor +--- For Lua see |lua-script-location|. +--- <stack> Call stack +--- <cword> Word under the cursor --- <cWORD> WORD under the cursor ---- <client> the {clientid} of the last received +--- <client> The {clientid} of the last received --- message --- Modifiers: ---- :p expand to full path ---- :h head (last path component removed) ---- :t tail (last path component only) ---- :r root (one extension removed) ---- :e extension only +--- :p Expand to full path +--- :h Head (last path component removed) +--- :t Tail (last path component only) +--- :r Root (one extension removed) +--- :e Extension only --- --- Example: >vim --- let &tags = expand("%:p:h") .. "/tags" diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua @@ -471,6 +471,10 @@ end --- Runs a system command or throws an error if {cmd} cannot be run. --- +--- The command runs directly (not in 'shell') so shell builtins such as "echo" in cmd.exe, cmdlets +--- in powershell, or "help" in bash, will not work unless you actually invoke a shell: +--- `vim.system({'bash', '-c', 'help'})`. +--- --- Examples: --- --- ```lua diff --git a/runtime/lua/vim/net.lua b/runtime/lua/vim/net.lua @@ -40,17 +40,11 @@ function M.request(url, opts, on_response) table.insert(args, url) local function on_exit(res) - local err_msg = nil - local response = nil - - if res.code ~= 0 then - err_msg = (res.stderr ~= '' and res.stderr) - or string.format('Request failed with exit code %d', res.code) - else - response = { - body = opts.outpath and true or res.stdout, - } - end + local s = 'Request failed with exit code %d' + local err_msg = res.code ~= 0 + and ((res.stderr ~= '' and res.stderr) or string.format(s, res.code)) + or nil + local response = res.code == 0 and { body = opts.outpath and true or res.stdout } or nil if on_response then on_response(err_msg, response) diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua @@ -1104,7 +1104,7 @@ do err_msg = is_valid(name, value, validator, msg, false) end elseif type(name) == 'table' then -- Form 2 - vim.deprecate('vim.validate', 'vim.validate(name, value, validator, optional_or_msg)', '1.0') + vim.deprecate('vim.validate{<table>}', 'vim.validate(<params>)', '1.0') err_msg = validate_spec(name) else error('invalid arguments') diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua @@ -1163,9 +1163,8 @@ end --- Opens a live editor to query the buffer you started from. --- ---- Can also be shown with `:EditQuery`. [:EditQuery]() ---- ---- `:EditQuery <tab>` completes the treesitter parser names in the runtime path. +--- Can also be shown with the [:EditQuery]() command. `:EditQuery <tab>` completes available +--- parsers. --- --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in --- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find diff --git a/scripts/vim-patch.sh b/scripts/vim-patch.sh @@ -207,7 +207,7 @@ preprocess_patch() { 2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/runtime/\<\%('"${na_rt}"'\)\>@exe "norm! d/\\v(^diff)|%$\r"' +w +q "$file" # Remove unwanted Vim doc files. - local na_doc='channel\.txt\|if_cscop\.txt\|netbeans\.txt\|os_\w\+\.txt\|print\.txt\|term\.txt\|todo\.txt\|vim9\.txt\|tags' + local na_doc='channel\.txt\|if_cscop\.txt\|netbeans\.txt\|os_\w\+\.txt\|print\.txt\|term\.txt\|testing\.txt\|todo\.txt\|vim9\.txt\|tags' 2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/runtime/doc/\<\%('"${na_doc}"'\)\>@exe "norm! d/\\v(^diff)|%$\r"' +w +q "$file" # Remove "Last change ..." changes in doc files. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c @@ -466,12 +466,14 @@ error: /// Replaces terminal codes and |keycodes| ([<CR>], [<Esc>], ...) in a string with /// the internal representation. /// +/// @note Lua can use |vim.keycode()| instead. +/// @see replace_termcodes +/// @see cpoptions +/// /// @param str String to be converted. /// @param from_part Legacy Vim parameter. Usually true. /// @param do_lt Also translate [<lt>]. Ignored if `special` is false. /// @param special Replace |keycodes|, e.g. [<CR>] becomes a "\r" char. -/// @see replace_termcodes -/// @see cpoptions String nvim_replace_termcodes(String str, Boolean from_part, Boolean do_lt, Boolean special) FUNC_API_SINCE(1) FUNC_API_RET_ALLOC { diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua @@ -2405,35 +2405,35 @@ M.funcs = { done like for the |cmdline-special| variables with their associated modifiers. Here is a short overview: - % current file name - # alternate file name - #n alternate file name n - <cfile> file name under the cursor - <afile> autocmd file name - <abuf> autocmd buffer number (as a String!) - <amatch> autocmd matched name + % Current file name + # Alternate file name + #n Alternate file name n + <cfile> File name under the cursor + <afile> Autocmd file name + <abuf> Autocmd buffer number (as a String!) + <amatch> Autocmd matched name <cexpr> C expression under the cursor - <sfile> deprecated, use <script> or <stack> - <slnum> sourced script line number or function + <sfile> Deprecated, use <script> or <stack> + <slnum> Sourced script line number or function line number - <sflnum> script file line number, also when in + <sflnum> Script file line number, also when in a function <SID> "<SNR>123_" where "123" is the current script ID |<SID>| - <script> sourced script file, or script file + <script> Sourced script file, or script file where the current function was defined. - Use |debug.getinfo()| in Lua scripts. - <stack> call stack - <cword> word under the cursor + For Lua see |lua-script-location|. + <stack> Call stack + <cword> Word under the cursor <cWORD> WORD under the cursor - <client> the {clientid} of the last received + <client> The {clientid} of the last received message Modifiers: - :p expand to full path - :h head (last path component removed) - :t tail (last path component only) - :r root (one extension removed) - :e extension only + :p Expand to full path + :h Head (last path component removed) + :t Tail (last path component only) + :r Root (one extension removed) + :e Extension only Example: >vim let &tags = expand("%:p:h") .. "/tags" diff --git a/src/nvim/globals.h b/src/nvim/globals.h @@ -421,20 +421,20 @@ EXTERN int sc_col; // column for shown command // First NO_SCREEN, then NO_BUFFERS, then 0 when startup finished. EXTERN int starting INIT( = NO_SCREEN); -// true when planning to exit. Might keep running if there is a changed buffer. +// Planning to exit. Might keep running if there is a changed buffer. EXTERN bool exiting INIT( = false); -// true when planning to restart. +// Planning to restart. EXTERN bool restarting INIT( = false); -// internal value of v:dying +// Internal value of v:dying EXTERN int v_dying INIT( = 0); -// is stdin a terminal? +// Is stdin a terminal? EXTERN bool stdin_isatty INIT( = true); -// is stdout a terminal? +// Is stdout a terminal? EXTERN bool stdout_isatty INIT( = true); -// is stderr a terminal? +// Is stderr a terminal? EXTERN bool stderr_isatty INIT( = true); -/// filedesc set by embedder for reading first buffer like `cmd | nvim -` +/// Filedesc set by embedder for reading first buffer like `cmd | nvim -`. EXTERN int stdin_fd INIT( = -1); // true when doing full-screen output, otherwise only writing some messages. diff --git a/src/nvim/options.lua b/src/nvim/options.lua @@ -2847,7 +2847,8 @@ local options = { Unset 'exrc' to stop further searching of 'exrc' files in parent directories, similar to |editorconfig.root|. - To get its own location, Lua exrc files can use |debug.getinfo()|. + To get its own location, a Lua exrc file can use |debug.getinfo()|. + See |lua-script-location|. Compare 'exrc' to |editorconfig|: - 'exrc' can execute any code; editorconfig only specifies settings. @@ -2857,7 +2858,7 @@ local options = { 1. Enable 'exrc'. 2. Place LSP configs at ".nvim/lsp/*.lua" in your project root. 3. Create ".nvim.lua" in your project root directory with this line: >lua - vim.cmd[[set runtimepath+=.nvim]] + vim.cmd[[set runtimepath+=.nvim]] < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. diff --git a/test/functional/core/server_spec.lua b/test/functional/core/server_spec.lua @@ -187,22 +187,22 @@ describe('server', function() -- After serverstop() the servers should NOT be in the list. eq(_n, eval('len(serverlist())')) - -- serverlist({ peer = true }) returns servers from other Nvim sessions. + -- serverlist({peer=true}) returns servers from other Nvim sessions. if t.is_os('win') then return end - local client_address = n.new_pipename() + local peer_addr = n.new_pipename() local client = n.new_session( true, - { args = { '-u', 'NONE', '--listen', client_address, '--embed' }, merge = false } + { args = { '--clean', '--listen', peer_addr, '--embed' }, merge = false } ) n.set_session(client) - eq(client_address, fn.serverlist()[1]) + eq(peer_addr, fn.serverlist()[1]) n.set_session(current_server) new_servs = fn.serverlist({ peer = true }) - eq(true, vim.list_contains(new_servs, client_address)) + eq(true, vim.list_contains(new_servs, peer_addr)) client:close() end) end)