From 4aeeaa80273eda1cf4fdb5de4b8ea65a16cefbaf Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 10 Mar 2026 18:44:23 +0100 Subject: [PATCH 1/4] docs: usr_25.txt formatting fix https://github.com/neovim/neovim.github.io/issues/453 --- runtime/doc/usr_25.txt | 164 ++++++++++++++++++++--------------------- 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt index 048db4ec69..7470e5c454 100644 --- a/runtime/doc/usr_25.txt +++ b/runtime/doc/usr_25.txt @@ -35,29 +35,29 @@ characters. You need to execute the following command: > :set textwidth=30 -Now you start typing (ruler added): +Now you start typing (ruler added): > 1 2 3 12345678901234567890123456789012345 - I taught programming for a whi ~ + I taught programming for a whi If you type "l" next, this makes the line longer than the 30-character limit. -When Vim sees this, it inserts a line break and you get the following: +When Vim sees this, it inserts a line break and you get the following: > 1 2 3 12345678901234567890123456789012345 - I taught programming for a ~ - whil ~ + I taught programming for a + whil -Continuing on, you can type in the rest of the paragraph: +Continuing on, you can type in the rest of the paragraph: > 1 2 3 12345678901234567890123456789012345 - I taught programming for a ~ - while. One time, I was stopped ~ - by the Fort Worth police, ~ - because my homework was too ~ - hard. True story. ~ + I taught programming for a + while. One time, I was stopped + by the Fort Worth police, + because my homework was too + hard. True story. You do not have to type newlines; Vim puts them in automatically. @@ -71,15 +71,15 @@ REFORMATTING The Vim editor is not a word processor. In a word processor, if you delete something at the beginning of the paragraph, the line breaks are reworked. In Vim they are not; so if you delete the word "programming" from the first line, -all you get is a short line: +all you get is a short line: > 1 2 3 12345678901234567890123456789012345 - I taught for a ~ - while. One time, I was stopped ~ - by the Fort Worth police, ~ - because my homework was too ~ - hard. True story. ~ + I taught for a + while. One time, I was stopped + by the Fort Worth police, + because my homework was too + hard. True story. This does not look good. To get the paragraph into shape you use the "gq" operator. @@ -89,15 +89,15 @@ line, type: > v4jgq "v" to start Visual mode, "4j" to move to the end of the paragraph and then -the "gq" operator. The result is: +the "gq" operator. The result is: > 1 2 3 12345678901234567890123456789012345 - I taught for a while. One ~ - time, I was stopped by the ~ - Fort Worth police, because my ~ - homework was too hard. True ~ - story. ~ + I taught for a while. One + time, I was stopped by the + Fort Worth police, because my + homework was too hard. True + story. Note: there is a way to do automatic formatting for specific types of text layouts, see |auto-format|. @@ -145,13 +145,13 @@ use for centering. If [width] is not specified, it defaults to the value of :1,5center 40 -results in the following: +results in the following: > - I taught for a while. One ~ - time, I was stopped by the ~ - Fort Worth police, because my ~ - homework was too hard. True ~ - story. ~ + I taught for a while. One + time, I was stopped by the + Fort Worth police, because my + homework was too hard. True + story. RIGHT ALIGNMENT @@ -160,13 +160,13 @@ Similarly, the ":right" command right-justifies the text: > :1,5right 37 -gives this result: +gives this result: > - I taught for a while. One ~ - time, I was stopped by the ~ - Fort Worth police, because my ~ - homework was too hard. True ~ - story. ~ + I taught for a while. One + time, I was stopped by the + Fort Worth police, because my + homework was too hard. True + story. LEFT ALIGNMENT @@ -183,13 +183,13 @@ example, use these commands: > :1left 5 :2,5left -This results in the following: +This results in the following: > - I taught for a while. One ~ - time, I was stopped by the ~ - Fort Worth police, because my ~ - homework was too hard. True ~ - story. ~ + I taught for a while. One + time, I was stopped by the + Fort Worth police, because my + homework was too hard. True + story. JUSTIFYING TEXT *justify* *:Justify* *Justify()* *package-justify* @@ -243,10 +243,10 @@ example, type this: > :set shiftwidth=4 -When used on the second line of the example text, this is what you get: +When used on the second line of the example text, this is what you get: > - the first line ~ - the second line ~ + the first line + the second line "4>>" will increase the indent of four lines. @@ -307,18 +307,18 @@ into the visible text if necessary. Let's attempt to show this with one line of text. The cursor is on the "w" of "which". The "current window" above the line indicates the text that is currently visible. The "window"s below the text indicate the text that is -visible after the command left of it. +visible after the command left of it. > - `|<-- current window -->|` - some long text, part of which is visible in the window ~ - ze `|<-- window -->|` - zH `|<-- window -->|` - 4zh `|<-- window -->|` - zh `|<-- window -->|` - zl `|<-- window -->|` - 4zl `|<-- window -->|` - zL `|<-- window -->|` - zs `|<-- window -->|` + |<-- current window -->| + some long text, part of which is visible in the window + ze |<-- window -->| + zH |<-- window -->| + 4zh |<-- window -->| + zh |<-- window -->| + zl |<-- window -->| + 4zl |<-- window -->| + zL |<-- window -->| + zs |<-- window -->| MOVING WITH WRAP OFF @@ -326,7 +326,7 @@ MOVING WITH WRAP OFF When 'wrap' is off and the text has scrolled horizontally, you can use the following commands to move the cursor to a character you can see. Thus text left and right of the window is ignored. These never cause the text to -scroll: +scroll: > g0 to first visible character in this line g^ to first non-blank visible character in this line @@ -334,8 +334,8 @@ scroll: gM to middle of the text in this line g$ to last visible character in this line - `|<-- window -->|` - some long text, part of which is visible in one line ~ + |<-- window -->| + some long text, part of which is visible in one line g0 g^ gm gM g$ @@ -443,11 +443,11 @@ paragraph to be joined. ============================================================================== *25.5* Editing tables -Suppose you are editing a table with four columns: +Suppose you are editing a table with four columns: > - nice table test 1 test 2 test 3 ~ - input A 0.534 ~ - input B 0.913 ~ + nice table test 1 test 2 test 3 + input A 0.534 + input B 0.913 You need to enter numbers in the third column. You could move to the second line, use "A", enter a lot of spaces and type the text. @@ -462,11 +462,11 @@ called "virtual space". Editing a table is a lot easier this way. /test 3 Now press "j" and you are right where you can enter the value for "input A". -Typing "0.693" results in: +Typing "0.693" results in: > - nice table test 1 test 2 test 3 ~ - input A 0.534 0.693 ~ - input B 0.913 ~ + nice table test 1 test 2 test 3 + input A 0.534 0.693 + input B 0.913 Vim has automatically filled the gap in front of the new text for you. Now, to enter the next field in this column use "Bj". "B" moves back to the start @@ -494,11 +494,11 @@ placed before the "test 1" column. Do this in seven steps: 6. Move the cursor to "test 1", where the new column must be placed. 7. Press "P". -The result should be: +The result should be: > - nice table test 3 test 1 test 2 test 3 ~ - input A 0.693 0.534 0.693 ~ - input B 0.913 ~ + nice table test 3 test 1 test 2 test 3 + input A 0.693 0.534 0.693 + input B 0.913 Notice that the whole "test 1" column was shifted right, also the line where the "test 3" column didn't have text. @@ -514,25 +514,25 @@ The disadvantage of using 'virtualedit' is that it "feels" different. You can't recognize tabs or spaces beyond the end of line when moving the cursor around. Another method can be used: Virtual Replace mode. Suppose you have a line in a table that contains both tabs and other -characters. Use "rx" on the first tab: +characters. Use "rx" on the first tab: > - inp 0.693 0.534 0.693 ~ + inp 0.693 0.534 0.693 | rx | V - inpx0.693 0.534 0.693 ~ + inpx0.693 0.534 0.693 -The layout is messed up. To avoid that, use the "gr" command: +The layout is messed up. To avoid that, use the "gr" command: > - inp 0.693 0.534 0.693 ~ + inp 0.693 0.534 0.693 | grx | V - inpx 0.693 0.534 0.693 ~ + inpx 0.693 0.534 0.693 What happens is that the "gr" command makes sure the new character takes the right amount of screen space. Extra spaces or tabs are inserted to fill the @@ -541,25 +541,25 @@ blanks added to make the text after it keep its place. In this case a tab is inserted. When you need to replace more than one character, you use the "R" command to go to Replace mode (see |04.9|). This messes up the layout and replaces -the wrong characters: +the wrong characters: > - inp 0 0.534 0.693 ~ + inp 0 0.534 0.693 | R0.786 | V - inp 0.78634 0.693 ~ + inp 0.78634 0.693 -The "gR" command uses Virtual Replace mode. This preserves the layout: +The "gR" command uses Virtual Replace mode. This preserves the layout: > - inp 0 0.534 0.693 ~ + inp 0 0.534 0.693 | gR0.786 | V - inp 0.786 0.534 0.693 ~ + inp 0.786 0.534 0.693 REFORMATTING TABS IN TABLES From b8a976afdaf0080498e85530fae65a3165f201d5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 12 Feb 2026 14:16:47 +0100 Subject: [PATCH 2/4] docs: api, messages, lsp, trust gen_vimdoc.lua: In prepare for the upcoming release, comment-out the "Experimental" warning for prerelease features. --- CONTRIBUTING.md | 61 ++++---- LICENSE.txt | 7 +- MAINTAIN.md | 16 +- runtime/doc/api.txt | 56 ++++--- runtime/doc/dev.txt | 12 +- runtime/doc/dev_test.txt | 4 + runtime/doc/editing.txt | 23 +-- runtime/doc/gui.txt | 42 +++--- runtime/doc/lsp.txt | 75 ++++++---- runtime/doc/lua.txt | 101 +++++++++++-- runtime/doc/message.txt | 44 +++--- runtime/doc/news.txt | 24 +-- runtime/doc/options.txt | 9 +- runtime/doc/pack.txt | 6 +- runtime/doc/treesitter.txt | 7 +- runtime/doc/various.txt | 8 +- runtime/doc/vvars.txt | 21 +-- runtime/example_init.lua | 59 ++++---- runtime/lua/man.lua | 7 +- runtime/lua/vim/_core/defaults.lua | 10 +- runtime/lua/vim/_core/shared.lua | 8 +- runtime/lua/vim/_core/ui2.lua | 6 +- runtime/lua/vim/_meta/api.lua | 39 ++--- runtime/lua/vim/_meta/options.lua | 3 +- runtime/lua/vim/_meta/vvars.lua | 22 +-- runtime/lua/vim/iter.lua | 23 +++ runtime/lua/vim/lsp.lua | 6 +- runtime/lua/vim/lsp/client.lua | 35 +++-- runtime/lua/vim/lsp/completion.lua | 17 +-- runtime/lua/vim/pack.lua | 5 +- runtime/lua/vim/secure.lua | 7 +- runtime/lua/vim/treesitter/query.lua | 6 +- src/gen/gen_vimdoc.lua | 14 +- src/nvim/api/win_config.c | 39 ++--- src/nvim/file_search.c | 1 + src/nvim/file_search.h | 2 +- src/nvim/lua/executor.c | 4 +- src/nvim/options.lua | 10 +- src/nvim/path.c | 4 +- src/nvim/vvars.lua | 21 +-- test/functional/core/path_spec.lua | 1 + test/functional/core/server_spec.lua | 4 +- test/functional/lua/diagnostic_spec.lua | 140 ++++++++---------- test/functional/lua/ui_spec.lua | 8 +- .../functional/plugin/lsp/completion_spec.lua | 4 +- test/functional/treesitter/parser_spec.lua | 69 ++++----- test/functional/treesitter/select_spec.lua | 16 +- 47 files changed, 614 insertions(+), 492 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99cfb17a49..40d0bd713b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,13 +55,26 @@ Developer guidelines Pull requests (PRs) --------------------- -- Fork the repository first. -- To avoid duplicate work, create a draft pull request. +### Guidelines + +- Don't ask to be assigned to an issue, just send a (reasonably complete) PR and + mark it as Draft until it is ready for review. - Your PR must include [test coverage][run-tests]. - Avoid cosmetic changes to unrelated files in the same commit. - Use a [feature branch][git-feature-branch] instead of the master branch. -- Use a _rebase workflow_ for all PRs. - - After addressing review comments, it's fine to force-push. +- Use a _rebase workflow_. After addressing review comments, it's fine to force-push. + +### AI-assisted work + +Using AI for contributions is acceptable, given the following: + +- YOU review the output before sending a non-Draft PR. Do NOT request review + until YOU have checked the AI generated PR and verify the following: +- REMOVE verbosity and blathering from documentation, comments, PR description, + commit message, etc. All resources, including names, should be CONCISE and + CLEAR. They should contain USEFUL information and nothing more. +- REMOVE and DEDUPLICATE redundant code, tests, explanations, etc. Explicitness + and clarity are GOOD but verbosity, over-explanation, and redundancy is BAD. ### Merging to master @@ -74,16 +87,22 @@ For maintainers: when a PR is ready to merge to master, Pull requests have two stages: Draft and Ready for review. -1. [Create a Draft PR][pr-draft] while you are _not_ requesting feedback as - you are still working on the PR. - - You can skip this if your PR is ready for review. -2. [Change your PR to ready][pr-ready] when the PR is ready for review. +1. [Create a Draft PR][pr-draft] while you are _not_ requesting feedback and + still working on the PR. +2. [Change your PR to Ready][pr-ready] when the PR is ready for review. - You can convert back to Draft at any time. Do __not__ add labels like `[RFC]` or `[WIP]` in the title to indicate the -state of your PR: this just adds noise. Non-Draft PRs are assumed to be open -for comments; if you want feedback from specific people, `@`-mention them in -a comment. +state of your PR: this just adds noise. + +### PR description + +For bugfixes, your PR title should be essentially the same as (1) the +"Problem" statement and (2) the test-case name. For example [PR #38048](https://github.com/neovim/neovim/pull/38048): + +- Title: `fix(lua): extra CR (\r) in nvim -l output` +- Problem: `nvim -l prints an extra \r to stdout: ...` +- Test name: `it('outputs the EOF as LF (not CRLF) #36853' ...` ### Commit messages @@ -291,24 +310,6 @@ If you need to modify or debug the documentation flow, these are the main files: Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return types, etc. See [:help dev-lua-doc][dev-lua-doc]. -- The template for function documentation is: - ```lua - --- {Brief} - --- - --- {Long explanation} - --- - --- @param arg1 type {description} - --- @param arg2 type {description} - --- ... - --- - --- @return type {description} - ``` -- If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`. -- If a function in your Lua module should _not_ be documented, add `@nodoc`. -- If the function is internal or otherwise non-public add `@private`. - - Private functions usually should be underscore-prefixed (named "_foo", not "foo"). Prefixing with an underscore implies `@nodoc`. -- Mark deprecated functions with `@deprecated`. - Third-party dependencies ------------------------ @@ -350,10 +351,8 @@ as context, use the `-W` argument as well. [549]: https://github.com/neovim/neovim/issues/549 [1820]: https://github.com/neovim/neovim/pull/1820 -[3174]: https://github.com/neovim/neovim/issues/3174 [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html [Cirrus CI]: https://cirrus-ci.com/github/neovim/neovim -[Clang report]: https://neovim.io/doc/reports/clang/ [GitHub Actions]: https://github.com/neovim/neovim/actions [Vim]: https://github.com/vim/vim [clangd]: https://clangd.llvm.org diff --git a/LICENSE.txt b/LICENSE.txt index 56df068fad..7d06aaf8bc 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -192,15 +192,20 @@ The externally maintained libraries used by Neovim are: - Lua: MIT license - LuaJIT: a Just-In-Time Compiler for Lua. Copyright Mike Pall. MIT license. - Luv: Apache 2.0 license + - gettext + - libiconv - libmpack: MIT license - libtermkey: MIT license - libuv. Copyright Joyent, Inc. and other Node contributors. Node.js license. - libvterm: MIT license + - lua-bitop: MIT license - lua-cjson: MIT license - lua-compat: MIT license + - lua-inspect: MIT license + - lua-lpeg: MIT license - tree-sitter: MIT license - - unibilium: LGPL v3 - xdiff: LGPL v2 + - (Deprecated) unibilium: LGPL v3 ==== diff --git a/MAINTAIN.md b/MAINTAIN.md index 3df2a808b8..57f8dba183 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -113,8 +113,13 @@ Exceptions to this policy may be made (for experimental subsystems or when there is broad consensus among maintainers). The rationale for the exception should be stated explicitly and publicly. -Third-party dependencies ------------------------- +Dependencies +------------ + +### Third-party dependencies + +(Note: keep this in sync with the "external" section of `LICENSE.txt`). +(TODO: declare deps in `sbom.json`, CycloneDX SBOM format). "Bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`. Some can be auto-bumped by `scripts/bump_deps.lua`. @@ -138,7 +143,8 @@ Some can be auto-bumped by `scripts/bump_deps.lua`. ### Vendored dependencies -These dependencies are "vendored" (inlined), we must update the sources manually: +"Vendored" (inlined) dependencies are part of the repo tree and we must update +the sources manually: * `src/mpack/`: [libmpack](https://github.com/libmpack/libmpack) * send improvements upstream! @@ -162,7 +168,7 @@ These dependencies are "vendored" (inlined), we must update the sources manually * `src/bit.c`: only for PUC lua: port of `require'bit'` from luajit https://bitop.luajit.org/ * `runtime/lua/coxpcall.lua`: coxpcall (only needed for PUC lua, builtin to luajit) -Other dependencies +Operational dependencies -------------------------- * GitHub users: @@ -178,7 +184,7 @@ Other dependencies * neovim.io * packspec.org * pkgjson.org -* DNS for the above domains is managed in https://cloudflare.com (not the domain registrar) +* The above domains are registered and managed in https://cloudflare.com Refactoring diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 3d17864047..6c260e16db 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1694,8 +1694,6 @@ nvim__complete_set({index}, {opts}) *nvim__complete_set()* • bufnr: (number) buffer id in floating window nvim__exec_lua_fast({code}, {args}) *nvim__exec_lua_fast()* - WARNING: This feature is experimental/unstable. - EXPERIMENTAL: this API may change or be removed in the future. Like |nvim_exec_lua()|, but can be called during |api-fast| contexts. @@ -1709,6 +1707,7 @@ nvim__exec_lua_fast({code}, {args}) *nvim__exec_lua_fast()* Attributes: ~ |api-fast| |RPC| only + Since: 0.12.0 Parameters: ~ • {code} (`string`) Lua code to execute @@ -3704,8 +3703,6 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* • {height} (`integer`) Popupmenu height, must be greater than zero. nvim_ui_send({content}) *nvim_ui_send()* - WARNING: This feature is experimental/unstable. - Sends arbitrary data to a UI. Use this instead of |nvim_chan_send()| or `io.stdout:write()`, if you really want to write to the |TUI| host terminal. @@ -3714,6 +3711,9 @@ nvim_ui_send({content}) *nvim_ui_send()* UIs are expected to write the received data to a connected TTY if one exists. + Attributes: ~ + Since: 0.12.0 + Parameters: ~ • {content} (`string`) Content to write to the TTY @@ -3768,28 +3768,23 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) Win_config Functions *api-win_config* nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - Opens a new split window, or a floating window if `relative` is specified, - or an external window (managed by the UI) if `external` is specified. - - Floats are windows that are drawn above the split layout, at some anchor - position in some other window. Floats can be drawn internally or by - external GUI with the |ui-multigrid| extension. External windows are only - supported with multigrid GUIs, and are displayed as separate top-level - windows. - - For a general overview of floats, see |api-floatwin|. - - The `width` and `height` of the new window must be specified when opening - a floating window, but are optional for normal windows. - - If `relative` and `external` are omitted, a normal "split" window is - created. The `win` property determines which window will be split. If no - `win` is provided or `win == 0`, a window will be created adjacent to the - current window. If -1 is provided, a top-level split will be created. - `vertical` and `split` are only valid for normal windows, and are used to - control split direction. For `vertical`, the exact direction is determined - by 'splitright' and 'splitbelow'. Split windows cannot have `bufpos`, - `row`, `col`, `border`, `title`, `footer` properties. + Opens a new split window, floating window, or external window. + • Specify `relative` to create a floating window. Floats are drawn over + the split layout, relative to a position in some other window. See + |api-floatwin|. + • Floats must specify `width` and `height`. + • Specify `external` to create an external window. External windows are + displayed as separate top-level windows managed by the |ui-multigrid| UI + (not Nvim). + • If `relative` and `external` are omitted, a normal "split" window is + created. + • The `win` key decides which window to split. If nil or 0, the split + will be adjacent to the current window. If -1, a top-level split will + be created. + • Use `vertical` and `split` to control split direction. For `vertical`, + the exact direction is determined by 'splitright' and 'splitbelow'. + • Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, + `footer`. With relative=editor (row=0,col=0) refers to the top-left corner of the screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right @@ -3961,10 +3956,11 @@ nvim_win_get_config({window}) *nvim_win_get_config()* see |nvim_open_win()| nvim_win_set_config({window}, {config}) *nvim_win_set_config()* - Reconfigures the layout of a window. - • Absent (`nil`) keys will not be changed. - • `row` / `col` / `relative` must be reconfigured together. - • Cannot be used to move the last window in a tabpage to a different one. + Reconfigures the layout and properties of a window. + • Updates only the given keys; unspecified (`nil`) keys will not be + changed. + • Keys `row` / `col` / `relative` must be specified together. + • Cannot move the last window in a tabpage to a different one. Example: to convert a floating window to a "normal" split window, specify the `win` field: >lua diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt index f5b4950c6d..9f8a3579ff 100644 --- a/runtime/doc/dev.txt +++ b/runtime/doc/dev.txt @@ -247,7 +247,11 @@ Docstring format: "stable". If `` is greater than the current stable release (or 0), it is marked as "experimental". - See scripts/util.lua for the mapping of api-level to Nvim version. +- Use `@deprecated` to mark deprecated functions. - Use `@nodoc` to prevent documentation generation. +- Use `@private` if the function is internal or otherwise non-public. + - Naming a function with an underscore prefix ("_foo", not "foo") implies + `@nodoc` and `@private`. - Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. E.g. >lua --- Object with fields: @@ -342,7 +346,7 @@ preference): *dev-patterns* Interface conventions ~ -Where possible, these patterns apply to _both_ Lua and the API: +Where applicable, these patterns apply to _both_ Lua and the API: - When accepting a buffer id, etc., 0 means "current buffer", nil means "all buffers". Likewise for window id, tabpage id, etc. @@ -379,6 +383,12 @@ Where possible, these patterns apply to _both_ Lua and the API: appropriate): when the function returns a nil value it excludes (filters out) its input, else the transformed value is used. - Example: See the format() field of |vim.diagnostic.Opts.Float|. +- Do not add "foreach" functions (e.g. |LanguageTree:for_each_tree()|). + Instead return an |iterable|, which is more flexible and composable: > + vim.iter(parser.tree_iter()):each(function() + ... + end) +< API DESIGN GUIDELINES *dev-api* diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt index c96d546dcb..9bfab61964 100644 --- a/runtime/doc/dev_test.txt +++ b/runtime/doc/dev_test.txt @@ -345,6 +345,10 @@ Writing tests *dev-write-test* GUIDELINES +- CI runs tests in parallel via the `functionaltest-parallel` cmake target. +- The Nvim test instance CWD is isolated to per "test group" (see + `WORKING_DIRECTORY` in `cmake/RunTests.cmake`), so tests can write files to + CWD without interferring with other tests running in parallel. - Luajit needs to know about type and constant declarations used in function prototypes. The [testutil.lua](https://github.com/neovim/neovim/blob/master/test/unit/testutil.lua) diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 09e3db77f9..7e32890506 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1715,17 +1715,22 @@ mark a file as trusted or untrusted using the |:trust| command or the :trust [++deny] [++remove] [file] Manage trusted files. Without ++ options, :trust marks - [file] (or current buffer if no [file]) as trusted, - keyed on a hash of its contents. The trust list is - stored on disk, Nvim will re-use it after restarting. + the current buffer (or [file], but see WARNING below) + as trusted, keyed on a hash of its contents. The trust + list is stored on disk, Nvim will re-use it after + restarting. - [++deny] marks [file] (or current buffer if no [file]) - as untrusted: it will never be executed, 'exrc' will + WARNING: `:trust [file]` has a TOCTOU risk, so for + security you should view the file, inspect its + contents, and run `:trust` (without [file] arg). + + [++deny] marks the current buffer or [file] as + untrusted: it will never be executed, 'exrc' will ignore it. - [++remove] removes [file] (or current buffer if no - [file]) from the trust list. When the file is - discovered by 'exrc' or |vim.secure.read()|, the user - will be asked whether to trust or deny the file. + [++remove] removes the current buffer or [file] from + the trust list. When the file is discovered by 'exrc' + or |vim.secure.read()|, the user will be prompted to + trust or deny it. vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 45f4231ce0..0d2cd3ef04 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -64,8 +64,6 @@ Stop or detach the current UI the channel to be closed, it may be (incorrectly) reported as an error. - Note: Not supported on Windows yet. - ------------------------------------------------------------------------------ Restart Nvim @@ -327,26 +325,26 @@ configure which ones appear with the 'guioptions' option. The interface looks like this (with `:set guioptions=mlrb`): > - +------------------------------+ ` - | File Edit Help | <- Menu bar (m) ` - +-+--------------------------+-+ ` - |^| |^| ` - |#| Text area. |#| ` - | | | | ` - |v|__________________________|v| ` - Normal status line -> |-+ File.c 5,2 +-| ` - between Vim windows |^|""""""""""""""""""""""""""|^| ` - | | | | ` - | | Another file buffer. | | ` - | | | | ` - |#| |#| ` - Left scrollbar (l) -> |#| |#| <- Right ` - |#| |#| scrollbar (r) ` - | | | | ` - |v| |v| ` - +-+--------------------------+-+ ` - | |< #### >| | <- Bottom ` - +-+--------------------------+-+ scrollbar (b) ` + +------------------------------+ + | File Edit Help | <- Menu bar (m) + +-+--------------------------+-+ + |^| |^| + |#| Text area. |#| + | | | | + |v|__________________________|v| + Normal status line -> |-+ File.c 5,2 +-| + between Vim windows |^|""""""""""""""""""""""""""|^| + | | | | + | | Another file buffer. | | + | | | | + |#| |#| + Left scrollbar (l) -> |#| |#| <- Right + |#| |#| scrollbar (r) + | | | | + |v| |v| + +-+--------------------------+-+ + | |< #### >| | <- Bottom + +-+--------------------------+-+ scrollbar (b) < Any of the scrollbar or menu components may be turned off by not putting the appropriate letter in the 'guioptions' string. The bottom scrollbar is diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c004720157..5a6a16dcab 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -56,10 +56,9 @@ Follow these steps to get LSP features: a |lsp-root_markers| file so the workspace can be recognized. 5. Check that LSP is active ("attached") for the buffer: >vim :checkhealth vim.lsp -6. Please note that certain LSP features are disabled by default, - you may choose to enable them manually. See: +6. Note: some LSP features are disabled by default, you can enable them + manually: - |lsp-codelens| - - |lsp-document_color| - |lsp-linked_editing_range| - |lsp-inlay_hint| - |lsp-inline_completion| @@ -85,8 +84,15 @@ These GLOBAL keymaps are created unconditionally when Nvim starts: - "grt" is mapped to |vim.lsp.buf.type_definition()| - "gO" is mapped to |vim.lsp.buf.document_symbol()| - CTRL-S (Insert mode) is mapped to |vim.lsp.buf.signature_help()| -- |v_an| and |v_in| fall back to |vim.lsp.buf.selection_range()| when - buffer has no treesitter parser +- |v_an| and |v_in| fall back to LSP |vim.lsp.buf.selection_range()| if + treesitter is not active. +- |gx| handles `textDocument/documentLink`. Example: with gopls, invoking gx + on "os" in this Go code will open documentation externally: > + package nvim + import ( + "os" + ) +< BUFFER-LOCAL DEFAULTS @@ -1575,12 +1581,8 @@ Lua module: vim.lsp.client *lsp-client* |vim.lsp.ClientConfig|. • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities provided at runtime (after startup). - • {exit_timeout} (`integer|boolean`, default: `false`) - Milliseconds to wait for server to exit - cleanly after sending the "shutdown" request - before sending kill -15. If set to false, - waits indefinitely. If set to true, nvim will - kill the server immediately. + • {exit_timeout} (`integer|boolean`, default: `false`) See + |vim.lsp.ClientConfig|. • {flags} (`table`) Experimental client flags: • {allow_incremental_sync}? (`boolean`, default: `true`) Allow using incremental @@ -1701,12 +1703,17 @@ Lua module: vim.lsp.client *lsp-client* process on exit, but if Nvim fails to exit cleanly this could leave behind orphaned server processes. - • {exit_timeout}? (`integer|boolean`, default: `false`) - Milliseconds to wait for server to exit cleanly - after sending the "shutdown" request before - sending kill -15. If set to false, waits - indefinitely. If set to true, nvim will kill - the server immediately. + • {exit_timeout}? (`integer|boolean`, default: `false`) Decides + if/when to force-stop the server after sending + the "shutdown" request. See |Client:stop()|. + Note: when Nvim itself is exiting, + • `false`: Nvim will not force-stop LSP + server(s). + • `true`: Nvim will force-stop LSP server(s) + that did not comply with the "shutdown" + request. + • `number`: Nvim will wait up to `exit_timeout` + milliseconds before performing force-stop. • {flags}? (`table`) Experimental client flags: • {allow_incremental_sync}? (`boolean`, default: `true`) Allow using incremental sync @@ -1877,20 +1884,24 @@ Client:request_sync({method}, {params}, {timeout_ms}, {bufnr}) Client:stop({force}) *Client:stop()* Stops a client, optionally with force after a timeout. - By default, it will request the server to shutdown, then force a shutdown - if the server has not exited after `self.exit_timeout` milliseconds. If - you request to stop a client which has previously been requested to - shutdown, it will automatically escalate and force shutdown immediately, - regardless of the value of `force` (or `self.exit_timeout` if `nil`). + By default this sends a "shutdown" request to the server, escalating to + force-stop if the server has not exited after `self.exit_timeout` + milliseconds (unless `exit_timeout=false`). Calling stop() on a client + that was previously requested to shutdown, will escalate to force-stop + immediately, regardless of `force` (or `self.exit_timeout` if + `force=nil`). Note: Forcing shutdown while a server is busy writing out project or index files can lead to file corruption. Parameters: ~ - • {force} (`integer|boolean?`, default: `self.exit_timeout`) Time in - milliseconds to wait before forcing a shutdown. If false, - only request the server to shutdown, but don't force it. If - true, force a shutdown immediately. + • {force} (`integer|boolean?`) (default: `self.exit_timeout`) Decides + whether to force-stop the server. + • `nil`: Defaults to `exit_timeout` from + |vim.lsp.ClientConfig|. + • `true`: Force-stop after "shutdown" request. + • `false`: Do not force-stop after "shutdown" request. + • number: Wait up to `force` milliseconds before force-stop. Client:supports_method({method}, {bufnr}) *Client:supports_method()* Checks if a client supports a given method. Always returns true for @@ -1974,7 +1985,7 @@ activate "auto-completion" when you type any of the server-defined |complete_CTRL-Y| Example: activate LSP-driven auto-completion: >lua - -- Works best with completeopt=noselect. + -- Works best if 'completeopt' has "noselect". -- Use CTRL-Y to select an item. |complete_CTRL-Y| vim.cmd[[set completeopt+=menuone,noselect,popup]] vim.lsp.start({ @@ -2007,13 +2018,15 @@ enable({enable}, {client_id}, {bufnr}, {opts}) Enables or disables completions from the given language client in the given buffer. Effects of enabling completions are: • Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve - completion candidates - • Accepting a completion candidate using `` applies side effects like + completion candidates. + • Selecting a completion item shows a preview popup + ("completionItem/resolve") if 'completeopt' has "popup". + • Accepting a completion item using `` applies side effects like expanding snippets, text edits (e.g. insert import statements) and executing associated commands. This works for completions triggered via - autotrigger, omnifunc or completion.get() + autotrigger, 'omnifunc' or |vim.lsp.completion.get()|. - Example: |lsp-attach| |lsp-completion| + Examples: |lsp-attach| |lsp-completion| Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You can override it on LspAttach, see diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index f9b386cee7..ecd04b835e 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1767,8 +1767,8 @@ vim.islist({t}) *vim.islist()* • |vim.isarray()| vim.list.bisect({t}, {val}, {opts}) *vim.list.bisect()* - Search for a position in a sorted list {t} where {val} can be inserted - while keeping the list sorted. + Search for a position in a sorted |lua-list| {t} where {val} can be + inserted while keeping the list sorted. Use {bound} to determine whether to return the first or the last position, defaults to "lower", i.e., the first position. @@ -1799,6 +1799,9 @@ vim.list.bisect({t}, {val}, {opts}) *vim.list.bisect()* end < + Attributes: ~ + Since: 0.12.0 + Parameters: ~ • {t} (`any[]`) A comparable list. • {val} (`any`) The value to search. @@ -1820,7 +1823,7 @@ vim.list.bisect({t}, {val}, {opts}) *vim.list.bisect()* position. vim.list.unique({t}, {key}) *vim.list.unique()* - Removes duplicate values from a list-like table in-place. + Removes duplicate values from a |lua-list| in-place. Only the first occurrence of each value is kept. The operation is performed in-place and the input table is modified. @@ -1842,6 +1845,9 @@ vim.list.unique({t}, {key}) *vim.list.unique()* -- t is now { {id=1}, {id=2} } < + Attributes: ~ + Since: 0.12.0 + Parameters: ~ • {t} (`any[]`) • {key} (`fun(x: T): any?`) Optional hash function to determine @@ -2943,6 +2949,9 @@ Examples: >lua Iter:all({pred}) *Iter:all()* Returns true if all items in the iterator match the given predicate. + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {pred} (`fun(...):boolean`) Predicate function. Takes all values returned from the previous stage in the pipeline as arguments @@ -2952,6 +2961,9 @@ Iter:any({pred}) *Iter:any()* Returns true if any of the items in the iterator match the given predicate. + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {pred} (`fun(...):boolean`) Predicate function. Takes all values returned from the previous stage in the pipeline as arguments @@ -2964,6 +2976,9 @@ Iter:each({f}) *Iter:each()* For functions with side effects. To modify the values in the iterator, use |Iter:map()|. + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {f} (`fun(...)`) Function to execute for each item in the pipeline. Takes all of the values returned by the previous stage in the @@ -2992,6 +3007,9 @@ Iter:enumerate() *Iter:enumerate()* -- 3 'c' < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`Iter`) @@ -3031,6 +3049,9 @@ Iter:find({f}) *Iter:find()* -- 12 < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {f} (`any`) @@ -3052,6 +3073,9 @@ Iter:flatten({depth}) *Iter:flatten()* -- error: attempt to flatten a dict-like table < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {depth} (`number?`) Depth to which |list-iterator| should be flattened (defaults to 1) @@ -3079,6 +3103,9 @@ Iter:fold({init}, {f}) *Iter:fold()* end) --> { max = 42 } < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {init} (`any`) Initial value of the accumulator. • {f} (`fun(acc:A, ...):A`) Accumulation function. @@ -3093,6 +3120,9 @@ Iter:join({delim}) *Iter:join()* Consumes the iterator. + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {delim} (`string`) Delimiter @@ -3113,6 +3143,9 @@ Iter:last() *Iter:last()* -- 15 < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`any`) @@ -3134,6 +3167,9 @@ Iter:map({f}) *Iter:map()* -- { 6, 12 } < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {f} (`fun(...):...:any`) Mapping function. Takes all values returned from the previous stage in the pipeline as arguments and returns @@ -3157,6 +3193,9 @@ Iter:next() *Iter:next()* -- 3 < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`any`) @@ -3179,6 +3218,9 @@ Iter:nth({n}) *Iter:nth()* -- 3 < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {n} (`number`) Index of the value to return. May be negative if the source is a |list-iterator|. @@ -3203,6 +3245,9 @@ Iter:peek() *Iter:peek()* -- 3 < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`any`) @@ -3218,6 +3263,9 @@ Iter:pop() *Iter:pop()* -- 3 < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`any`) @@ -3231,6 +3279,9 @@ Iter:rev() *Iter:rev()* -- { 12, 9, 6, 3 } < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`Iter`) @@ -3250,6 +3301,9 @@ Iter:rfind({f}) *Iter:rfind()* -- 1 1 < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {f} (`any`) @@ -3272,6 +3326,9 @@ Iter:rpeek() *Iter:rpeek()* -- 4 < + Attributes: ~ + Since: 0.10.0 + Return: ~ (`any`) @@ -3289,6 +3346,9 @@ Iter:rskip({n}) *Iter:rskip()* -- 3 < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {n} (`number`) Number of values to skip. @@ -3315,6 +3375,9 @@ Iter:skip({n}) *Iter:skip()* -- 12 < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {n} (`integer|fun(...):boolean`) Number of values to skip or a predicate. @@ -3327,6 +3390,9 @@ Iter:slice({first}, {last}) *Iter:slice()* Equivalent to `:skip(first - 1):rskip(len - last + 1)`. + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {first} (`number`) • {last} (`number`) @@ -3355,6 +3421,9 @@ Iter:take({n}) *Iter:take()* -- nil < + Attributes: ~ + Since: 0.10.0 + Parameters: ~ • {n} (`integer|fun(...):boolean`) Number of values to take or a predicate. @@ -3385,6 +3454,9 @@ Iter:totable() *Iter:totable()* indices. To create a map-like table with arbitrary keys, use |Iter:fold()|. + Attributes: ~ + Since: 0.10.0 + Return: ~ (`table`) @@ -3415,6 +3487,9 @@ Iter:unique({key}) *Iter:unique()* -- { {id=1}, {id=2} } < + Attributes: ~ + Since: 0.12.0 + Parameters: ~ • {key} (`fun(...):any?`) Optional hash function to determine uniqueness of values. @@ -4476,10 +4551,11 @@ vim.secure.trust({opts}) *vim.secure.trust()* Parameters: ~ • {opts} (`table`) A table with the following fields: - • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a - file to the trust database and trust it, - • `'deny'` to add a file to the trust database and deny it, - • `'remove'` to remove file from the trust database + • {action} (`'allow'|'deny'|'remove'`) One of: + • `'allow'` to add a file to the trust database and trust + it, + • `'deny'` to add a file to the trust database and deny it, + • `'remove'` to remove file from the trust database • {path}? (`string`) Path to a file to update. Mutually exclusive with {bufnr}. • {bufnr}? (`integer`) Buffer number to update. Mutually @@ -5188,10 +5264,11 @@ vim.version.gt({v1}, {v2}) *vim.version.gt()* (`boolean`) vim.version.intersect({r1}, {r2}) *vim.version.intersect()* - WARNING: This feature is experimental/unstable. - Computes the common range shared by the given ranges. + Attributes: ~ + Since: 0.12.0 + Parameters: ~ • {r1} (`vim.VersionRange`) First range to intersect. See |vim.VersionRange|. @@ -5288,7 +5365,7 @@ To enable the experimental UI (default opts shown): >lua ---@type 'cmd'|'msg' Default message target, either in the ---cmdline or in a separate ephemeral message window. ---@type string|table Default message target - or table mapping |ui-messages| kinds and triggers to a target. + ---or table mapping |ui-messages| kinds and triggers to a target. targets = 'cmd', timeout = 4000, -- Time a message is visible in the message window. }, @@ -5310,6 +5387,8 @@ options for these windows and their respective buffers. Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the -spilled lines. To see the full message, the |g<| command can be used. +spilled lines. To see the full message, use either: +• ENTER immediately after a message from interactive |:| cmdline. +• |g<| at any time. vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index 40c135b6ee..6ff87b00e8 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -11,7 +11,7 @@ means. It is not complete though. Type |gO| to see the table of contents. ============================================================================== -1. Old messages *:messages* *:mes* *message-history* +Messages history *:messages* *:mes* *message-history* The ":messages" command can be used to view previously given messages. This is especially useful when messages have been overwritten or truncated. This @@ -57,7 +57,7 @@ If you are lazy, it also works without the shift key: > :help e72 ============================================================================== -2. Error messages *error-messages* *errors* +Error messages *error-messages* *errors* When an error message is displayed, but it is removed before you could read it, you can see it again with: > @@ -767,78 +767,78 @@ startup. This can only happen when changing the source code, after adding a command in src/ex_cmds.lua. Update the lookup table by re-running the build. - *E970* > + *E970* > Failed to initialize lua interpreter Failed to initialize builtin lua modules Nvim failed to initialize the Lua interpreter or its builtin modules during startup. This is a fatal error that prevents Nvim from running. - *E5107* > + *E5107* > Lua: {error} Lua code compilation (loadbuffer) failed when executing |:lua| commands or functions. {error} contains the Lua syntax or compilation error message. - *E5108* > + *E5108* > Lua function: {error} Lua: {error} -Lua code execution (pcall) failed. This can occur when executing |:lua| -commands, during Lua function completion, or in other Lua code execution -contexts. {error} contains the Lua runtime error message and traceback. +Lua code execution (pcall) failed, when executing Lua code or during Lua +function completion. {error} contains the Lua runtime error message and +traceback. - *E5109* > + *E5109* > Lua: {error} -Lua code compilation (loadbuffer) failed when executing the |:luado| command. -{error} contains the Lua syntax or compilation error message. +Lua code compilation (loadbuffer) failed during |:luado|. {error} contains the +Lua syntax or compilation error message. - *E5110* > + *E5110* > Lua: {error} Lua code execution (pcall) failed during |:luado| command initialization. {error} contains the Lua runtime error message and traceback. - *E5111* > + *E5111* > Lua: {error} Lua code execution failed in |:luado| callback or during Lua script loading. {error} contains the Lua runtime error message and traceback. - *E5112* > + *E5112* > Lua chunk: {error} Lua chunk compilation failed. The loadstring() function returned an error when trying to compile the Lua code. {error} contains the compilation error message. - *E5113* > + *E5113* > Lua chunk: {error} Lua chunk execution failed after successful compilation. {error} contains the Lua runtime error message and traceback. - *E5114* > + *E5114* > Converting print argument #{i}: {error} -Failed to convert argument number {i} to a string in the Lua print() -function. {error} contains the conversion error details. +Lua `print()` failed to convert argument number {i} to a string. {error} +contains the conversion error details. - *E5115* > + *E5115* > Loading Lua debug string: {error} Failed to load (compile) a Lua debug command string. {error} contains the compilation error message. - *E5116* > + *E5116* > Calling Lua debug string: {error} Failed to execute a Lua debug command string. {error} contains the runtime error message and traceback. ============================================================================== -3. Messages *messages* +Messages *messages* This is an (incomplete) overview of various messages that Vim gives: @@ -935,7 +935,7 @@ This is especially useful if you accidentally typed at the hit-enter prompt. ============================================================================== -4. PROGRESS MESSAGE *progress-message* +Progress messages *progress-message* Plugins and core Nvim features can emit "progress" |ui-messages| to report the state of long-running tasks. diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index fffd7b36b5..d6ee40d5bb 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -150,8 +150,8 @@ API `max_height` is reached, and returns the `end_row` and `end_vcol` for which `max_height` or the calculated height is reached. • |vim.secure.read()| now returns `true` for trusted directories. Previously - it would return `nil`, which made it impossible to tell if the directory was - actually trusted. + it would return `nil`, thus impossible to tell if the directory was actually + trusted. • Added |vim.lsp.is_enabled()| to check if a given LSP config has been enabled by |vim.lsp.enable()|. • |nvim_ui_send()| writes arbitrary data to a UI's stdout. Use this to write @@ -187,13 +187,13 @@ DEFAULTS • 'statusline' default is exposed as a statusline expression (previously it was implemented as an internal C routine). • 'statusline' includes |vim.diagnostic.status()| +• 'statusline' shows exit code of finished terminal buffers • Project-local configuration ('exrc') is also loaded from parent directories. Unset 'exrc' to stop further search. • Mappings: • |grt| in Normal mode maps to |vim.lsp.buf.type_definition()| • 'shada' default now excludes "/tmp/" and "/private/" paths to reduce clutter in |:oldfiles|. • Enabled treesitter highlighting for Markdown files -• 'statusline' shows exit code of finished terminal buffers DIAGNOSTICS @@ -220,8 +220,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`. +• For security, 'exrc' no longer shows "(a)llow". Instead you must "(v)iew", + then run `:trust` (or `:trust [file]`, but that has a TOCTOU risk). • |gx| in help buffers opens the online documentation for the tag under the cursor. • |:source| with a range in non-Lua files (e.g., vimdoc) now detects Lua @@ -303,7 +303,10 @@ LSP to a top-level field. Defaults to `false`. • |Client:stop()| accepts `force` as an integer, which is treated as the time to wait before before stop escalates to force-stop. -• Add cmp field to opts of |vim.lsp.completion.enable()| for custom completion ordering. +• |lsp-completion|: + • |vim.lsp.completion.enable()| gained a `cmp` option for custom ordering. + • Supports colored symbol preview for color items. + • Shows a preview ("completionItem/resolve") if 'completeopt' has "popup". • Support for `workspace/diagnostic/refresh`: https://microsoft.github.io/language-server-protocol/specification/#diagnostic_refresh • Support for dynamic registration for `textDocument/diagnostic` @@ -315,8 +318,7 @@ LSP • Code lenses now display as virtual lines • Support for `workspace/codeLens/refresh`: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#codeLens_refresh -• `gx` will use `textDocument/documentLink` if available. -• |vim.lsp.completion.enable()| adds colored symbol preview for color items. +• |gx| opens `textDocument/documentLink` items found at cursor. LUA @@ -394,7 +396,7 @@ PLUGINS STARTUP -• todo +• |v:argf| provides file arguments given at startup. TERMINAL @@ -403,6 +405,8 @@ TERMINAL • CSI 3 J (the sequence to clear terminal scrollback) is now supported. • A suspended PTY process is now indicated by "[Process suspended]" at the bottom-left of the buffer and can be resumed by pressing a key. +• On terminal exit, "[Process exited]" is shown as virtual text (instead of + modifying buffer contents), and exit code is shown in statusline. TREESITTER @@ -473,8 +477,6 @@ These existing features changed their behavior. for input and output. This matters mostly for Linux where some command lines using "/dev/stdin" and similiar would break as these special files can be reopened when backed by pipes but not when backed by socket pairs. -• On terminal exit, "[Process exited]" is not added to the buffer contents, - instead it is shown as virtual text and exit code is shown in statusline. ============================================================================== REMOVED FEATURES *news-removed* diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 92c407406d..ceefd0902a 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -3343,14 +3343,15 @@ A jump table for the options with a short description can be found at |Q_op|. Examples of cursor highlighting: >vim highlight Cursor gui=reverse guifg=NONE guibg=NONE + " Note: gui=reverse overrides colors. highlight Cursor gui=NONE guifg=bg guibg=fg < *'guifont'* *'gfn'* *E235* *E596* -'guifont' 'gfn' string (default (MS-Windows) "Cascadia Code,Cascadia Mono,Consolas,Courier New,monospace" - (Mac) "SF Mono,Menlo,Monaco,Courier New,monospace" - (Linux) "Source Code Pro,DejaVu Sans Mono,Courier New,monospace" - (others) "DejaVu Sans Mono,Courier New,monospace") +'guifont' 'gfn' string (default "DejaVu Sans Mono,Courier New,monospace" + Mac: "SF Mono,Menlo,Monaco,Courier New,monospace" + Linux: "Source Code Pro,DejaVu Sans Mono,Courier New,monospace" + MS-Windows: "Cascadia Code,Cascadia Mono,Consolas,Courier New,monospace") global This is a list of fonts which will be used for the GUI version of Vim. In its simplest form the value is just one font name. When diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index 6b9ec96cce..11f55d4b8d 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -528,10 +528,10 @@ update({names}, {opts}) *vim.pack.update()* updates. Default: `false`. • {target}? (`string`) How to compute a new plugin revision. One of: - • "version" (default) - use latest revision matching + • "version" (default): use latest revision matching `version` from plugin specification. - • "lockfile" - use revision from the lockfile. Useful for - reverting or performing controlled update. + • "lockfile": use revision from the lockfile. For reverting + or performing controlled update. vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 0dbc8d2da9..7f2ee6452b 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -548,7 +548,6 @@ When multiple captures set this metadata over a region, only the innermost ============================================================================== TREESITTER LANGUAGE INJECTIONS *treesitter-language-injections* -< Note the following information is adapted from: https://tree-sitter.github.io/tree-sitter/3-syntax-highlighting.html#language-injection @@ -1604,10 +1603,8 @@ edit({lang}) *vim.treesitter.query.edit()* If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted with |hl-DiagnosticVirtualTextHint| in the source - buffer. - - The query editor is a scratch buffer, use `:write` to save it. You can - find example queries at `$VIMRUNTIME/queries/`. + buffer. The query editor is a scratch buffer, use `:write` to save it. You + can find example queries at `$VIMRUNTIME/queries/`. Parameters: ~ • {lang} (`string?`) language to open the query editor for. If omitted, diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index bad272273b..29fdc6c6e4 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -101,9 +101,11 @@ g8 Print the hex values of the bytes used in the command won't move the cursor. *gx* -gx Opens the current filepath or URL (decided by - ||, 'isfname') at cursor using the system - default handler. Mapped to |vim.ui.open()|. +gx Opens the current filepath, URL (decided by + ||, 'isfname'), or |LSP| "documentLink" at + cursor using the system default handler. + + Mapped to |vim.ui.open()|. *v_gx* {Visual}gx Opens the selected text using the system default diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index 9f0e7a8c37..1df41773cf 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -13,24 +13,25 @@ be mentioned at the variable description below. The type cannot be changed. *v:argf* *argf-variable* v:argf - The list of file arguments passed on the command line at startup. - - Each filename is expanded to an absolute path, so that v:argf - remains valid even if the current working directory changes later. + File arguments (expanded to absolute paths) given at startup. Unlike |v:argv|, this does not include option arguments such as `-u`, `--cmd`, or `+cmd`. Unlike |argv()|, it is not affected by later |:args|, |:argadd|, or plugin modifications. - It also handles the `--` separator correctly, including only - files specified after it. - This is a read-only snapshot of the original startup file arguments. + Example: > + nvim file1.txt +ls -- file2.txt + :echo v:argf + " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt'] +< *v:argv* *argv-variable* v:argv - The command line arguments Vim was invoked with. This is a - list of strings. The first item is the Vim command. - See |v:progpath| for the command with full path. + Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was + invoked with. The first item is the Nvim command. + + See |v:progpath| to get the full path to Nvim. + See |v:argf| to get only file args, without other options. *v:char* *char-variable* v:char diff --git a/runtime/example_init.lua b/runtime/example_init.lua index 8c27c042f8..5549655486 100644 --- a/runtime/example_init.lua +++ b/runtime/example_init.lua @@ -3,17 +3,18 @@ -- NOTE: Must happen before plugins are loaded (otherwise wrong leader will be used) vim.g.mapleader = ' ' --- [[ Setting options ]] See `:h vim.o` +-- OPTIONS +-- +-- See `:h vim.o` -- NOTE: You can change these options as you wish! -- For more options, you can see `:help option-list` -- To see documentation for an option, you can use `:h 'optionname'`, for example `:h 'number'` -- (Note the single quotes) --- Print the line number in front of each line -vim.o.number = true +vim.o.number = true -- Show line numbers in a column. --- Use relative line numbers, so that it is easier to jump with j, k. This will affect the 'number' --- option above, see `:h number_relativenumber` +-- Show line numbers relative to where the cursor is. +-- Affects the 'number' option above, see `:h number_relativenumber`. vim.o.relativenumber = true -- Sync clipboard between OS and Neovim. Schedule the setting after `UIEnter` because it can @@ -29,20 +30,17 @@ vim.api.nvim_create_autocmd('UIEnter', { vim.o.ignorecase = true vim.o.smartcase = true --- Highlight the line where the cursor is on -vim.o.cursorline = true - --- Minimal number of screen lines to keep above and below the cursor. -vim.o.scrolloff = 10 - --- Show and trailing spaces -vim.o.list = true +vim.o.cursorline = true -- Highlight the line where the cursor is on. +vim.o.scrolloff = 10 -- Keep this many screen lines above/below the cursor. +vim.o.list = true -- Show and trailing spaces. -- if performing an operation that would fail due to unsaved changes in the buffer (like `:q`), -- instead raise a dialog asking if you wish to save the current file(s) See `:help 'confirm'` vim.o.confirm = true --- [[ Set up keymaps ]] See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes` +-- KEYMAPS +-- +-- See `:h vim.keymap.set()`, `:h mapping`, `:h keycodes` -- Use to exit terminal mode vim.keymap.set('t', '', '') @@ -57,7 +55,8 @@ vim.keymap.set({ 'n' }, '', 'j') vim.keymap.set({ 'n' }, '', 'k') vim.keymap.set({ 'n' }, '', 'l') --- [[ Basic Autocommands ]]. +-- AUTOCOMMANDS (EVENT HANDLERS) +-- -- See `:h lua-guide-autocommands`, `:h autocmd`, `:h nvim_create_autocmd()` -- Highlight when yanking (copying) text. @@ -69,7 +68,8 @@ vim.api.nvim_create_autocmd('TextYankPost', { end, }) --- [[ Create user commands ]] +-- USER COMMANDS: DEFINE CUSTOM COMMANDS +-- -- See `:h nvim_create_user_command()` and `:h user-commands` -- Create a command `:GitBlameLine` that print the git blame for the current line @@ -79,15 +79,24 @@ vim.api.nvim_create_user_command('GitBlameLine', function() print(vim.system({ 'git', 'blame', '-L', line_number .. ',+1', filename }):wait().stdout) end, { desc = 'Print the git blame for the current line' }) --- [[ Add optional packages ]] --- Nvim comes bundled with a set of packages that are not enabled by --- default. You can enable any of them by using the `:packadd` command. +-- PLUGINS +-- +-- * Enable optional, builtin plugins via ":packadd". +-- * Install third-party plugins via "vim.pack". --- For example, to add the "nohlsearch" package to automatically turn off search highlighting after --- 'updatetime' and when going to insert mode +-- Example: add the "nohlsearch" package to automatically disable search highlighting after +-- 'updatetime' and when going to insert mode. vim.cmd('packadd! nohlsearch') --- [[ Install plugins ]] --- Nvim functionality can be extended by installing external plugins. --- One way to do it is with a built-in plugin manager. See `:h vim.pack`. -vim.pack.add({ 'https://github.com/neovim/nvim-lspconfig' }) +-- Example: Install third-party plugins by calling "vim.pack.add{}". +vim.pack.add({ + 'https://github.com/neovim/nvim-lspconfig', + -- Fuzzy picker + 'https://github.com/ibhagwan/fzf-lua', + -- Autocompletion + 'https://github.com/echasnovski/mini.completion', + -- Enhanced quickfix/loclist + 'https://github.com/stevearc/quicker.nvim', + -- Git integration + 'https://github.com/lewis6991/gitsigns.nvim', +}) diff --git a/runtime/lua/man.lua b/runtime/lua/man.lua index 9efc7e96f9..1104e7f906 100644 --- a/runtime/lua/man.lua +++ b/runtime/lua/man.lua @@ -221,12 +221,7 @@ local function get_path(name, sect) sect = sect or '' -- We can avoid relying on -S or -s here since they are very -- inconsistently supported. Instead, call -w with a section and a name. - local cmd --- @type string[] - if sect == '' then - cmd = { 'man', '-w', name } - else - cmd = { 'man', '-w', sect, name } - end + local cmd = sect == '' and { 'man', '-w', name } or { 'man', '-w', sect, name } local lines = system(cmd, true) local results = vim.split(lines, '\n', { trimempty = true }) diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua index e923e8934c..9b9ab01b52 100644 --- a/runtime/lua/vim/_core/defaults.lua +++ b/runtime/lua/vim/_core/defaults.lua @@ -445,15 +445,15 @@ do end, { expr = true, desc = 'Add empty line below cursor' }) end - --- incremental treesitter selection mappings (+ lsp fallback) + --- "Incremental selection" mappings (treesitter + LSP fallback). do vim.keymap.set({ 'x' }, '[n', function() require 'vim.treesitter._select'.select_prev(vim.v.count1) - end, { desc = 'Select previous treesitter node' }) + end, { desc = 'Select previous node' }) vim.keymap.set({ 'x' }, ']n', function() require 'vim.treesitter._select'.select_next(vim.v.count1) - end, { desc = 'Select next treesitter node' }) + end, { desc = 'Select next node' }) vim.keymap.set({ 'x', 'o' }, 'an', function() if vim.treesitter.get_parser(nil, nil, { error = false }) then @@ -461,7 +461,7 @@ do else vim.lsp.buf.selection_range(vim.v.count1) end - end, { desc = 'Select parent treesitter node or outer incremental lsp selections' }) + end, { desc = 'Select parent (outer) node' }) vim.keymap.set({ 'x', 'o' }, 'in', function() if vim.treesitter.get_parser(nil, nil, { error = false }) then @@ -469,7 +469,7 @@ do else vim.lsp.buf.selection_range(-vim.v.count1) end - end, { desc = 'Select child treesitter node or inner incremental lsp selections' }) + end, { desc = 'Select child (inner) node' }) end end diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua index 1f01b70f2a..da50338d01 100644 --- a/runtime/lua/vim/_core/shared.lua +++ b/runtime/lua/vim/_core/shared.lua @@ -360,7 +360,7 @@ local function key_fn(v, key) return key and key(v) or v end ---- Removes duplicate values from a list-like table in-place. +--- Removes duplicate values from a |lua-list| in-place. --- --- Only the first occurrence of each value is kept. --- The operation is performed in-place and the input table is modified. @@ -383,6 +383,7 @@ end --- -- t is now { {id=1}, {id=2} } --- ``` --- +--- @since 14 --- @generic T --- @param t T[] --- @param key? fun(x: T): any Optional hash function to determine uniqueness of values @@ -482,8 +483,8 @@ local function upper_bound(t, val, lo, hi, key) return lo end ---- Search for a position in a sorted list {t} ---- where {val} can be inserted while keeping the list sorted. +--- Search for a position in a sorted |lua-list| {t} where {val} can be inserted while keeping the +--- list sorted. --- --- Use {bound} to determine whether to return the first or the last position, --- defaults to "lower", i.e., the first position. @@ -514,6 +515,7 @@ end --- print(t[i]) -- { 3, 3, 3 } --- end --- ``` +---@since 14 ---@generic T ---@param t T[] A comparable list. ---@param val T The value to search. diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua index debd1feac5..c679f2bdde 100644 --- a/runtime/lua/vim/_core/ui2.lua +++ b/runtime/lua/vim/_core/ui2.lua @@ -11,7 +11,7 @@ --- ---@type 'cmd'|'msg' Default message target, either in the --- ---cmdline or in a separate ephemeral message window. --- ---@type string|table Default message target ---- or table mapping |ui-messages| kinds and triggers to a target. +--- ---or table mapping |ui-messages| kinds and triggers to a target. --- targets = 'cmd', --- timeout = 4000, -- Time a message is visible in the message window. --- }, @@ -32,7 +32,9 @@ --- ---Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do ---not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the ----spilled lines. To see the full message, the |g<| command can be used. +---spilled lines. To see the full message, use either: +--- - ENTER immediately after a message from interactive |:| cmdline. +--- - |g<| at any time. local api = vim.api local M = { diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 9b7bec6678..ff05e0a332 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1703,26 +1703,19 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- @return integer # Channel id, or 0 on error function vim.api.nvim_open_term(buffer, opts) end ---- Opens a new split window, or a floating window if `relative` is specified, ---- or an external window (managed by the UI) if `external` is specified. +--- Opens a new split window, floating window, or external window. --- ---- Floats are windows that are drawn above the split layout, at some anchor ---- position in some other window. Floats can be drawn internally or by external ---- GUI with the `ui-multigrid` extension. External windows are only supported ---- with multigrid GUIs, and are displayed as separate top-level windows. ---- ---- For a general overview of floats, see `api-floatwin`. ---- ---- The `width` and `height` of the new window must be specified when opening ---- a floating window, but are optional for normal windows. ---- ---- If `relative` and `external` are omitted, a normal "split" window is created. ---- The `win` property determines which window will be split. If no `win` is ---- provided or `win == 0`, a window will be created adjacent to the current window. ---- If -1 is provided, a top-level split will be created. `vertical` and `split` are ---- only valid for normal windows, and are used to control split direction. For `vertical`, ---- the exact direction is determined by 'splitright' and 'splitbelow'. ---- Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer` properties. +--- - Specify `relative` to create a floating window. Floats are drawn over the split layout, +--- relative to a position in some other window. See `api-floatwin`. +--- - Floats must specify `width` and `height`. +--- - Specify `external` to create an external window. External windows are displayed as separate +--- top-level windows managed by the `ui-multigrid` UI (not Nvim). +--- - If `relative` and `external` are omitted, a normal "split" window is created. +--- - The `win` key decides which window to split. If nil or 0, the split will be adjacent to +--- the current window. If -1, a top-level split will be created. +--- - Use `vertical` and `split` to control split direction. For `vertical`, the exact direction +--- is determined by 'splitright' and 'splitbelow'. +--- - Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer`. --- --- With relative=editor (row=0,col=0) refers to the top-left corner of the --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right @@ -2492,11 +2485,11 @@ function vim.api.nvim_win_is_valid(window) end --- @param buffer integer Buffer id function vim.api.nvim_win_set_buf(window, buffer) end ---- Reconfigures the layout of a window. +--- Reconfigures the layout and properties of a window. --- ---- - Absent (`nil`) keys will not be changed. ---- - `row` / `col` / `relative` must be reconfigured together. ---- - Cannot be used to move the last window in a tabpage to a different one. +--- - Updates only the given keys; unspecified (`nil`) keys will not be changed. +--- - Keys `row` / `col` / `relative` must be specified together. +--- - Cannot move the last window in a tabpage to a different one. --- --- Example: to convert a floating window to a "normal" split window, specify the `win` field: --- diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 177c77b8eb..4b532cf34e 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -3159,6 +3159,7 @@ vim.go.gp = vim.go.grepprg --- --- ```vim --- highlight Cursor gui=reverse guifg=NONE guibg=NONE +--- " Note: gui=reverse overrides colors. --- highlight Cursor gui=NONE guifg=bg guibg=fg --- ``` --- @@ -3240,7 +3241,7 @@ vim.go.gcr = vim.go.guicursor --- --- --- @type string -vim.o.guifont = "Source Code Pro,DejaVu Sans Mono,Courier New,monospace" +vim.o.guifont = "DFLT_GFN" vim.o.gfn = vim.o.guifont vim.go.guifont = vim.o.guifont vim.go.gfn = vim.go.guifont diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index 58cdddce48..dec1cfc476 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -6,24 +6,26 @@ error('Cannot require a meta file') --- @class vim.v vim.v = ... ---- The list of file arguments passed on the command line at startup. ---- ---- Each filename is expanded to an absolute path, so that v:argf ---- remains valid even if the current working directory changes later. +--- File arguments (expanded to absolute paths) given at startup. --- --- Unlike `v:argv`, this does not include option arguments --- such as `-u`, `--cmd`, or `+cmd`. Unlike `argv()`, it is not --- affected by later `:args`, `:argadd`, or plugin modifications. ---- It also handles the `--` separator correctly, including only ---- files specified after it. --- ---- This is a read-only snapshot of the original startup file arguments. +--- Example: +--- ``` +--- nvim file1.txt +ls -- file2.txt +--- :echo v:argf +--- " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt'] +--- ``` --- @type string[] vim.v.argf = ... ---- The command line arguments Vim was invoked with. This is a ---- list of strings. The first item is the Vim command. ---- See `v:progpath` for the command with full path. +--- Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was +--- invoked with. The first item is the Nvim command. +--- +--- See `v:progpath` to get the full path to Nvim. +--- See `v:argf` to get only file args, without other options. --- @type string[] vim.v.argv = ... diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua index 654ab9bf12..1bcfcaffa0 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -243,6 +243,7 @@ end --- -- { {id=1}, {id=2} } --- ``` --- +---@since 14 ---@param key? fun(...):any Optional hash function to determine uniqueness of values. ---@return Iter ---@see |vim.list.unique()| @@ -282,6 +283,7 @@ end --- -- error: attempt to flatten a dict-like table --- ``` --- +---@since 12 ---@param depth? number Depth to which |list-iterator| should be flattened --- (defaults to 1) ---@return Iter @@ -331,6 +333,7 @@ end --- -- { 6, 12 } --- ``` --- +---@since 12 ---@param f fun(...):...:any Mapping function. Takes all values returned from --- the previous stage in the pipeline as arguments --- and returns one or more new values, which are used @@ -399,6 +402,7 @@ end --- --- For functions with side effects. To modify the values in the iterator, use |Iter:map()|. --- +---@since 12 ---@param f fun(...) Function to execute for each item in the pipeline. --- Takes all of the values returned by the previous stage --- in the pipeline as arguments. @@ -446,6 +450,7 @@ end --- To create a map-like table with arbitrary keys, use |Iter:fold()|. --- --- +---@since 12 ---@return table function Iter:totable() local t = {} @@ -498,6 +503,7 @@ end --- --- Consumes the iterator. --- +--- @since 12 --- @param delim string Delimiter --- @return string function Iter:join(delim) @@ -527,6 +533,7 @@ end --- ---@generic A --- +---@since 12 ---@param init A Initial value of the accumulator. ---@param f fun(acc:A, ...):A Accumulation function. ---@return A @@ -572,6 +579,7 @@ end --- --- ``` --- +---@since 12 ---@return any function Iter:next() if self._peeked then @@ -606,6 +614,7 @@ end --- --- ``` --- +---@since 12 ---@return Iter function Iter:rev() error('rev() requires an array-like table') @@ -637,6 +646,7 @@ end --- --- ``` --- +---@since 12 ---@return any function Iter:peek() if not self._peeked then @@ -674,6 +684,7 @@ end --- -- 12 --- --- ``` +---@since 12 ---@param f any ---@return any function Iter:find(f) @@ -720,6 +731,7 @@ end --- ---@see |Iter:find()| --- +---@since 12 ---@param f any ---@return any ---@diagnostic disable-next-line: unused-local @@ -769,6 +781,7 @@ end --- -- nil --- ``` --- +---@since 12 ---@param n integer|fun(...):boolean Number of values to take or a predicate. ---@return Iter function Iter:take(n) @@ -828,6 +841,7 @@ end --- -- 3 --- ``` --- +---@since 12 ---@return any function Iter:pop() error('pop() requires an array-like table') @@ -858,6 +872,7 @@ end --- ---@see |Iter:last()| --- +---@since 12 ---@return any function Iter:rpeek() error('rpeek() requires an array-like table') @@ -891,6 +906,7 @@ end --- -- 12 --- ``` --- +---@since 12 ---@param n integer|fun(...):boolean Number of values to skip or a predicate. ---@return Iter function Iter:skip(n) @@ -956,6 +972,7 @@ end --- -- 3 --- ``` --- +---@since 12 ---@param n number Number of values to skip. ---@return Iter ---@diagnostic disable-next-line: unused-local @@ -993,6 +1010,7 @@ end --- -- 3 --- ``` --- +---@since 12 ---@param n number Index of the value to return. May be negative if the source is a |list-iterator|. ---@return any function Iter:nth(n) @@ -1007,6 +1025,7 @@ end --- --- Equivalent to `:skip(first - 1):rskip(len - last + 1)`. --- +---@since 12 ---@param first number ---@param last number ---@return Iter @@ -1022,6 +1041,7 @@ end --- Returns true if any of the items in the iterator match the given predicate. --- +---@since 12 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous --- stage in the pipeline as arguments and returns true if the --- predicate matches. @@ -1046,6 +1066,7 @@ end --- Returns true if all items in the iterator match the given predicate. --- +---@since 12 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous --- stage in the pipeline as arguments and returns true if the --- predicate matches. @@ -1083,6 +1104,7 @@ end --- --- ``` --- +---@since 12 ---@see |Iter:rpeek()| --- ---@return any @@ -1135,6 +1157,7 @@ end --- --- ``` --- +---@since 12 ---@return Iter function Iter:enumerate() local i = 0 diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index d1ed9138ea..5aa473968f 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -1046,13 +1046,11 @@ end --- ``` --- --- By default asks the server to shutdown, unless stop was requested already for this client (then ---- force-shutdown is attempted, unless `exit_timeout=false`). +--- force-stop is attempted, unless `exit_timeout=false`). --- ---@deprecated ---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects ----@param force? boolean|integer Whether to shutdown forcefully. ---- If `force` is a number, it will be treated as the time in milliseconds to ---- wait before forcing the shutdown. +---@param force? boolean|integer See |Client:stop()| function lsp.stop_client(client_id, force) vim.deprecate('vim.lsp.stop_client()', 'vim.lsp.Client:stop()', '0.13') --- @type integer[]|vim.lsp.Client[] diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index d98f1c000f..635c2cde76 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/runtime/lua/vim/lsp/client.lua @@ -68,9 +68,11 @@ local all_clients = {} --- (default: `true`) --- @field detached? boolean --- ---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before ---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the ---- server immediately. +--- Decides if/when to force-stop the server after sending the "shutdown" request. See |Client:stop()|. +--- Note: when Nvim itself is exiting, +--- - `false`: Nvim will not force-stop LSP server(s). +--- - `true`: Nvim will force-stop LSP server(s) that did not comply with the "shutdown" request. +--- - `number`: Nvim will wait up to `exit_timeout` milliseconds before performing force-stop. --- (default: `false`) --- @field exit_timeout? integer|boolean --- @@ -156,9 +158,7 @@ local all_clients = {} --- Capabilities provided at runtime (after startup). --- @field dynamic_capabilities lsp.DynamicCapabilities --- ---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before ---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the ---- server immediately. +--- See [vim.lsp.ClientConfig]. --- (default: `false`) --- @field exit_timeout integer|boolean --- @@ -852,20 +852,19 @@ end --- Stops a client, optionally with force after a timeout. --- ---- By default, it will request the server to shutdown, then force a shutdown ---- if the server has not exited after `self.exit_timeout` milliseconds. If ---- you request to stop a client which has previously been requested to ---- shutdown, it will automatically escalate and force shutdown immediately, ---- regardless of the value of `force` (or `self.exit_timeout` if `nil`). +--- By default this sends a "shutdown" request to the server, escalating to force-stop if the server +--- has not exited after `self.exit_timeout` milliseconds (unless `exit_timeout=false`). +--- Calling stop() on a client that was previously requested to shutdown, will escalate to +--- force-stop immediately, regardless of `force` (or `self.exit_timeout` if `force=nil`). --- ---- Note: Forcing shutdown while a server is busy writing out project or index ---- files can lead to file corruption. +--- Note: Forcing shutdown while a server is busy writing out project or index files can lead to +--- file corruption. --- ---- @param force? integer|boolean Time in milliseconds to wait before forcing ---- a shutdown. If false, only request the ---- server to shutdown, but don't force it. If ---- true, force a shutdown immediately. ---- (default: `self.exit_timeout`) +--- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server. +--- - `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|. +--- - `true`: Force-stop after "shutdown" request. +--- - `false`: Do not force-stop after "shutdown" request. +--- - number: Wait up to `force` milliseconds before force-stop. function Client:stop(force) validate('force', force, { 'number', 'boolean' }, true) diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua index 4910c415d9..e495af4240 100644 --- a/runtime/lua/vim/lsp/completion.lua +++ b/runtime/lua/vim/lsp/completion.lua @@ -6,7 +6,7 @@ --- --- Example: activate LSP-driven auto-completion: --- ```lua ---- -- Works best with completeopt=noselect. +--- -- Works best if 'completeopt' has "noselect". --- -- Use CTRL-Y to select an item. |complete_CTRL-Y| --- vim.cmd[[set completeopt+=menuone,noselect,popup]] --- vim.lsp.start({ @@ -1159,15 +1159,14 @@ end --- Enables or disables completions from the given language client in the given --- buffer. Effects of enabling completions are: --- ---- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve ---- completion candidates +--- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve completion candidates. +--- - Selecting a completion item shows a preview popup ("completionItem/resolve") if 'completeopt' +--- has "popup". +--- - Accepting a completion item using `` applies side effects like expanding snippets, +--- text edits (e.g. insert import statements) and executing associated commands. This works for +--- completions triggered via autotrigger, 'omnifunc' or [vim.lsp.completion.get()]. --- ---- - Accepting a completion candidate using `` applies side effects like ---- expanding snippets, text edits (e.g. insert import statements) and ---- executing associated commands. This works for completions triggered via ---- autotrigger, omnifunc or completion.get() ---- ---- Example: |lsp-attach| |lsp-completion| +--- Examples: |lsp-attach| |lsp-completion| --- --- Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You --- can override it on LspAttach, see |lsp-autocompletion|. diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua index c59a9b410a..6d9b8dc9a1 100644 --- a/runtime/lua/vim/pack.lua +++ b/runtime/lua/vim/pack.lua @@ -1204,9 +1204,8 @@ end --- @field offline? boolean Whether to skip downloading new updates. Default: `false`. --- --- How to compute a new plugin revision. One of: ---- - "version" (default) - use latest revision matching `version` from plugin specification. ---- - "lockfile" - use revision from the lockfile. Useful for reverting or performing controlled ---- update. +--- - "version" (default): use latest revision matching `version` from plugin specification. +--- - "lockfile": use revision from the lockfile. For reverting or performing controlled update. --- @field target? string --- Update plugins diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua index 784b4d5ff0..9f5463ac98 100644 --- a/runtime/lua/vim/secure.lua +++ b/runtime/lua/vim/secure.lua @@ -162,9 +162,10 @@ end --- @class vim.trust.opts --- @inlinedoc --- ---- - `'allow'` to add a file to the trust database and trust it, ---- - `'deny'` to add a file to the trust database and deny it, ---- - `'remove'` to remove file from the trust database +--- One of: +--- - `'allow'` to add a file to the trust database and trust it, +--- - `'deny'` to add a file to the trust database and deny it, +--- - `'remove'` to remove file from the trust database --- @field action 'allow'|'deny'|'remove' --- --- Path to a file to update. Mutually exclusive with {bufnr}. diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 7fa954698d..d29e376ef1 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -1193,10 +1193,8 @@ end --- parsers. --- --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted ---- with |hl-DiagnosticVirtualTextHint| in the source buffer. ---- ---- The query editor is a scratch buffer, use `:write` to save it. You can find example queries ---- at `$VIMRUNTIME/queries/`. +--- with |hl-DiagnosticVirtualTextHint| in the source buffer. The query editor is a scratch buffer, +--- use `:write` to save it. You can find example queries at `$VIMRUNTIME/queries/`. --- --- @param lang? string language to open the query editor for. If omitted, inferred from the current buffer's filetype. function M.edit(lang) diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua index c0bd22dfaf..1d426a664b 100755 --- a/src/gen/gen_vimdoc.lua +++ b/src/gen/gen_vimdoc.lua @@ -512,6 +512,9 @@ local function should_render_field_or_param(p) and not vim.startswith(p.name, '_') end +--- Gets a field's description and its "(default: …)" value, if any (see `lsp/client.lua` for +--- examples). +--- --- @param desc? string --- @return string?, string? local function get_default(desc) @@ -801,13 +804,18 @@ local function render_fun(fun, classes, cfg) if fun.since then local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name) - local info = nvim_api_info() - if since == 0 or (info.prerelease and since == info.level) then + local nvim_api = nvim_api_info() + _ = nvim_api -- Disable prerelease "WARNING" doc, in preparation for for upcoming release. + + if + since == 0 --[[or (nvim_api.prerelease and since == nvim_api.level)]] + then -- Experimental = (since==0 or current prerelease) local s = 'WARNING: This feature is experimental/unstable.' table.insert(ret, md_to_vimdoc(s, INDENTATION, INDENTATION, TEXT_WIDTH)) table.insert(ret, '\n') - else + end + if since > 0 then local v = assert(util.version_level[since], 'invalid @since on ' .. fun.name) fun.attrs = fun.attrs or {} table.insert(fun.attrs, fmt('Since: %s', v)) diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c index 15d3904660..55e089b133 100644 --- a/src/nvim/api/win_config.c +++ b/src/nvim/api/win_config.c @@ -39,26 +39,19 @@ #include "api/win_config.c.generated.h" -/// Opens a new split window, or a floating window if `relative` is specified, -/// or an external window (managed by the UI) if `external` is specified. +/// Opens a new split window, floating window, or external window. /// -/// Floats are windows that are drawn above the split layout, at some anchor -/// position in some other window. Floats can be drawn internally or by external -/// GUI with the |ui-multigrid| extension. External windows are only supported -/// with multigrid GUIs, and are displayed as separate top-level windows. -/// -/// For a general overview of floats, see |api-floatwin|. -/// -/// The `width` and `height` of the new window must be specified when opening -/// a floating window, but are optional for normal windows. -/// -/// If `relative` and `external` are omitted, a normal "split" window is created. -/// The `win` property determines which window will be split. If no `win` is -/// provided or `win == 0`, a window will be created adjacent to the current window. -/// If -1 is provided, a top-level split will be created. `vertical` and `split` are -/// only valid for normal windows, and are used to control split direction. For `vertical`, -/// the exact direction is determined by 'splitright' and 'splitbelow'. -/// Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer` properties. +/// - Specify `relative` to create a floating window. Floats are drawn over the split layout, +/// relative to a position in some other window. See |api-floatwin|. +/// - Floats must specify `width` and `height`. +/// - Specify `external` to create an external window. External windows are displayed as separate +/// top-level windows managed by the |ui-multigrid| UI (not Nvim). +/// - If `relative` and `external` are omitted, a normal "split" window is created. +/// - The `win` key decides which window to split. If nil or 0, the split will be adjacent to +/// the current window. If -1, a top-level split will be created. +/// - Use `vertical` and `split` to control split direction. For `vertical`, the exact direction +/// is determined by 'splitright' and 'splitbelow'. +/// - Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer`. /// /// With relative=editor (row=0,col=0) refers to the top-left corner of the /// screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right @@ -618,11 +611,11 @@ resize: #undef HAS_KEY_X } -/// Reconfigures the layout of a window. +/// Reconfigures the layout and properties of a window. /// -/// - Absent (`nil`) keys will not be changed. -/// - `row` / `col` / `relative` must be reconfigured together. -/// - Cannot be used to move the last window in a tabpage to a different one. +/// - Updates only the given keys; unspecified (`nil`) keys will not be changed. +/// - Keys `row` / `col` / `relative` must be specified together. +/// - Cannot move the last window in a tabpage to a different one. /// /// Example: to convert a floating window to a "normal" split window, specify the `win` field: /// diff --git a/src/nvim/file_search.c b/src/nvim/file_search.c index bc97b2c482..1cd747a08f 100644 --- a/src/nvim/file_search.c +++ b/src/nvim/file_search.c @@ -1668,6 +1668,7 @@ char *file_name_in_line(char *line, int col, int options, int count, char *rel_f // Search forward for the last char of the file name. // Also allow ":/" when ':' is not in 'isfname'. + // TODO(justinmk): Check for driveletter "x:/" at start, regardless of 'isfname'. len = path_has_drive_letter(ptr, strlen(ptr)) ? 2 : 0; while (vim_isfilec((uint8_t)ptr[len]) || (ptr[len] == '\\' && ptr[len + 1] == ' ') || ((options & FNAME_HYP) && path_is_url(ptr + len)) diff --git a/src/nvim/file_search.h b/src/nvim/file_search.h index ab22069a4d..293bfe1616 100644 --- a/src/nvim/file_search.h +++ b/src/nvim/file_search.h @@ -17,7 +17,7 @@ enum { enum { FNAME_MESS = 1, ///< give error message FNAME_EXP = 2, ///< expand to path - FNAME_HYP = 4, ///< check for hypertext link + FNAME_HYP = 4, ///< check for hyperlink url ("foo://") FNAME_INCL = 8, ///< apply 'includeexpr' FNAME_REL = 16, ///< ".." and "./" are relative to the (current) ///< file instead of the current directory diff --git a/src/nvim/lua/executor.c b/src/nvim/lua/executor.c index 17567c4eb0..3338928739 100644 --- a/src/nvim/lua/executor.c +++ b/src/nvim/lua/executor.c @@ -887,12 +887,12 @@ void nlua_init(char **argv, int argc, int lua_arg0) lua_State *lstate = luaL_newstate(); if (lstate == NULL) { - fprintf(stderr, _("E970: Failed to initialize lua interpreter\n")); + fprintf(stderr, _("E970: Failed to initialize Lua interpreter\n")); os_exit(1); } luaL_openlibs(lstate); if (!nlua_state_init(lstate)) { - fprintf(stderr, _("E970: Failed to initialize builtin lua modules\n")); + fprintf(stderr, _("E970: Failed to initialize builtin Lua modules\n")); #ifdef EXITFREE nlua_common_free_all_mem(lstate); #endif diff --git a/src/nvim/options.lua b/src/nvim/options.lua index e17b80817a..255d5f7f5c 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -3985,6 +3985,7 @@ local options = { Examples of cursor highlighting: >vim highlight Cursor gui=reverse guifg=NONE guibg=NONE + " Note: gui=reverse overrides colors. highlight Cursor gui=NONE guifg=bg guibg=fg < ]=], @@ -4000,10 +4001,11 @@ local options = { abbreviation = 'gfn', defaults = { if_true = macros('DFLT_GFN', 'string'), - doc = [[(MS-Windows) "Cascadia Code,Cascadia Mono,Consolas,Courier New,monospace" - (Mac) "SF Mono,Menlo,Monaco,Courier New,monospace" - (Linux) "Source Code Pro,DejaVu Sans Mono,Courier New,monospace" - (others) "DejaVu Sans Mono,Courier New,monospace"]], + doc = [["DejaVu Sans Mono,Courier New,monospace" + Mac: "SF Mono,Menlo,Monaco,Courier New,monospace" + Linux: "Source Code Pro,DejaVu Sans Mono,Courier New,monospace" + MS-Windows: "Cascadia Code,Cascadia Mono,Consolas,Courier New,monospace"]], + meta = 'DFLT_GFN', }, desc = [=[ This is a list of fonts which will be used for the GUI version of Vim. diff --git a/src/nvim/path.c b/src/nvim/path.c index f09535cdb5..298026d7b3 100644 --- a/src/nvim/path.c +++ b/src/nvim/path.c @@ -1775,10 +1775,10 @@ int path_is_url(const char *p) return 0; } -/// Check if "fname" starts with "name://" or "name:\\". +/// Check if "fname" starts with "name:/" or "name:\". /// /// @param fname is the filename to test -/// @return URL_SLASH for "name://", URL_BACKSLASH for "name:\\", zero otherwise. +/// @return URL_SLASH for "name:/", URL_BACKSLASH for "name:\", zero otherwise. int path_with_url(const char *fname) FUNC_ATTR_NONNULL_ALL { diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua index 6428627389..c6b839fef3 100644 --- a/src/nvim/vvars.lua +++ b/src/nvim/vvars.lua @@ -4,26 +4,27 @@ M.vars = { argf = { type = 'string[]', desc = [=[ - The list of file arguments passed on the command line at startup. - - Each filename is expanded to an absolute path, so that v:argf - remains valid even if the current working directory changes later. + File arguments (expanded to absolute paths) given at startup. Unlike |v:argv|, this does not include option arguments such as `-u`, `--cmd`, or `+cmd`. Unlike |argv()|, it is not affected by later |:args|, |:argadd|, or plugin modifications. - It also handles the `--` separator correctly, including only - files specified after it. - This is a read-only snapshot of the original startup file arguments. + Example: > + nvim file1.txt +ls -- file2.txt + :echo v:argf + " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt'] + < ]=], }, argv = { type = 'string[]', desc = [=[ - The command line arguments Vim was invoked with. This is a - list of strings. The first item is the Vim command. - See |v:progpath| for the command with full path. + Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was + invoked with. The first item is the Nvim command. + + See |v:progpath| to get the full path to Nvim. + See |v:argf| to get only file args, without other options. ]=], }, char = { diff --git a/test/functional/core/path_spec.lua b/test/functional/core/path_spec.lua index d8e274019a..e8c7578306 100644 --- a/test/functional/core/path_spec.lua +++ b/test/functional/core/path_spec.lua @@ -115,6 +115,7 @@ describe('file search', function() eq(expected, eval('expand("")')) end + -- test_cfile([[c:/d:/e:/foo/bar.txt]], 'c:/d:/e') -- TODO(justinmk): should return "d:/foo/bar.txt" ? test_cfile([[c:/d:/foo/bar.txt]]) -- TODO(justinmk): should return "d:/foo/bar.txt" ? test_cfile([[//share/c:/foo/bar/]]) test_cfile([[file://c:/foo/bar]]) diff --git a/test/functional/core/server_spec.lua b/test/functional/core/server_spec.lua index 5ec6cc5979..3d65885376 100644 --- a/test/functional/core/server_spec.lua +++ b/test/functional/core/server_spec.lua @@ -219,7 +219,7 @@ describe('server', function() client:close() end) - it('removes stale socket files automatically #26053', function() + it('removes stale socket files automatically #36581', function() -- Windows named pipes are ephemeral kernel objects that are automatically -- cleaned up when the process terminates. Unix domain sockets persist as -- files on the filesystem and can become stale after crashes. @@ -243,7 +243,7 @@ describe('server', function() fn.serverstop(socket_path) end) - it('does not remove live sockets #26053', function() + it('does not remove live sockets #36581', function() t.skip(is_os('win'), 'N/A on Windows') clear() diff --git a/test/functional/lua/diagnostic_spec.lua b/test/functional/lua/diagnostic_spec.lua index 6de00d75d6..37939370b2 100644 --- a/test/functional/lua/diagnostic_spec.lua +++ b/test/functional/lua/diagnostic_spec.lua @@ -4065,7 +4065,7 @@ describe('vim.diagnostic', function() end) end) - describe('toqflist() and fromqflist()', function() + describe('toqflist(), fromqflist()', function() it('works', function() local result = exec_lua(function() vim.diagnostic.set(_G.diagnostic_ns, _G.diagnostic_bufnr, { @@ -4091,95 +4091,71 @@ describe('vim.diagnostic', function() end) it('merge_lines=true merges continuation lines', function() - local result = exec_lua(function() - local qflist = { - { - bufnr = 1, - lnum = 10, - col = 5, - end_lnum = 10, - end_col = 10, - text = 'error: [GHC-83865]', - type = 'E', - nr = 0, - valid = 1, - }, - { - bufnr = 1, - lnum = 0, - col = 0, - end_lnum = 0, - end_col = 0, - text = " Couldn't match expected type", - type = '', - nr = 0, - valid = 0, - }, - { - bufnr = 1, - lnum = 0, - col = 0, - end_lnum = 0, - end_col = 0, - text = ' with actual type', - type = '', - nr = 0, - valid = 0, - }, - { - bufnr = 1, - lnum = 20, - col = 1, - end_lnum = 20, - end_col = 5, - text = 'warning: unused', - type = 'W', - nr = 0, - valid = 1, - }, - } - return vim.diagnostic.fromqflist(qflist, { merge_lines = true }) - end) + local function get_fromqflist(merge_lines) + return exec_lua(function(merge_lines_) + local qflist = { + { + bufnr = 1, + lnum = 10, + col = 5, + end_lnum = 10, + end_col = 10, + text = 'error: [GHC-83865]', + type = 'E', + nr = 0, + valid = 1, + }, + { + bufnr = 1, + lnum = 0, + col = 0, + end_lnum = 0, + end_col = 0, + text = " Couldn't match expected type", + type = '', + nr = 0, + valid = 0, + }, + { + bufnr = 1, + lnum = 0, + col = 0, + end_lnum = 0, + end_col = 0, + text = ' with actual type', + type = '', + nr = 0, + valid = 0, + }, + { + bufnr = 1, + lnum = 20, + col = 1, + end_lnum = 20, + end_col = 5, + text = 'warning: unused', + type = 'W', + nr = 0, + valid = 1, + }, + } + return vim.diagnostic.fromqflist(qflist, { merge_lines = merge_lines_ }) + end, merge_lines) + end + -- merge_lines=true + local result = get_fromqflist(true) eq(2, #result) eq( "error: [GHC-83865]\n Couldn't match expected type\n with actual type", result[1].message ) eq('warning: unused', result[2].message) - end) - it('merge_lines=false ignores continuation lines', function() - local result = exec_lua(function() - local qflist = { - { - bufnr = 1, - lnum = 10, - col = 5, - end_lnum = 10, - end_col = 10, - text = 'error: main', - type = 'E', - nr = 0, - valid = 1, - }, - { - bufnr = 1, - lnum = 0, - col = 0, - end_lnum = 0, - end_col = 0, - text = 'continuation', - type = '', - nr = 0, - valid = 0, - }, - } - return vim.diagnostic.fromqflist(qflist) - end) - - eq(1, #result) - eq('error: main', result[1].message) + -- merge_lines=false + result = get_fromqflist(false) + eq(2, #result) + eq('error: [GHC-83865]', result[1].message) end) end) diff --git a/test/functional/lua/ui_spec.lua b/test/functional/lua/ui_spec.lua index 5da0ddb373..14f02d520f 100644 --- a/test/functional/lua/ui_spec.lua +++ b/test/functional/lua/ui_spec.lua @@ -145,12 +145,12 @@ describe('vim.ui', function() if not is_os('bsd') then local rv = exec_lua([[ local cmd, err = vim.ui.open('non-existent-file') - if err then return nil end + if err and err:find('no handler found') then + return -1 + end return cmd:wait(100).code ]]) - if type(rv) == 'number' then - ok(rv ~= 0, 'nonzero exit code', rv) - end + ok(type(rv) == 'number' and rv ~= 0, 'nonzero exit code', rv) end exec_lua [[ diff --git a/test/functional/plugin/lsp/completion_spec.lua b/test/functional/plugin/lsp/completion_spec.lua index ed76e44157..787d1e7425 100644 --- a/test/functional/plugin/lsp/completion_spec.lua +++ b/test/functional/plugin/lsp/completion_spec.lua @@ -752,7 +752,7 @@ describe('vim.lsp.completion: item conversion', function() eq('foobar', result.items[1].user_data.nvim.lsp.completion_item.textEdit.newText) end) - it('shows snippet source in doc popup if completeopt include popup', function() + it('shows snippet source in doc popup if completeopt=popup', function() exec_lua([[ vim.opt.completeopt:append('popup') vim.bo.filetype = 'lua' @@ -1362,7 +1362,7 @@ describe('vim.lsp.completion: integration', function() eq('w-1/2', n.api.nvim_get_current_line()) end) - it('completionItem/resolve', function() + it('selecting an item triggers completionItem/resolve + preview', function() local screen = Screen.new(50, 20) screen:add_extra_attr_ids({ [100] = { background = Screen.colors.Plum1, foreground = Screen.colors.Blue }, diff --git a/test/functional/treesitter/parser_spec.lua b/test/functional/treesitter/parser_spec.lua index 9a35febc8f..d797928e00 100644 --- a/test/functional/treesitter/parser_spec.lua +++ b/test/functional/treesitter/parser_spec.lua @@ -337,25 +337,25 @@ describe('treesitter parser API', function() end) local test_text = [[ -void ui_refresh(void) -{ - int width = INT_MAX, height = INT_MAX; - bool ext_widgets[kUIExtCount]; - for (UIExtension i = 0; (int)i < kUIExtCount; i++) { - ext_widgets[i] = true; - } + void ui_refresh(void) + { + int width = INT_MAX, height = INT_MAX; + bool ext_widgets[kUIExtCount]; + for (UIExtension i = 0; (int)i < kUIExtCount; i++) { + ext_widgets[i] = true; + } - bool inclusive = ui_override(); - for (size_t i = 0; i < ui_count; i++) { - UI *ui = uis[i]; - width = MIN(ui->width, width); - height = MIN(ui->height, height); - foo = BAR(ui->bazaar, bazaar); - for (UIExtension j = 0; (int)j < kUIExtCount; j++) { - ext_widgets[j] &= (ui->ui_ext[j] || inclusive); - } - } -}]] + bool inclusive = ui_override(); + for (size_t i = 0; i < ui_count; i++) { + UI *ui = uis[i]; + width = MIN(ui->width, width); + height = MIN(ui->height, height); + foo = BAR(ui->bazaar, bazaar); + for (UIExtension j = 0; (int)j < kUIExtCount; j++) { + ext_widgets[j] &= (ui->ui_ext[j] || inclusive); + } + } + }]] it('can iterate over nodes children', function() insert(test_text) @@ -424,7 +424,7 @@ void ui_refresh(void) local tree = parser:parse()[1] return vim.treesitter.get_node_text(tree:root(), 0) end) - eq(test_text, res) + eq(t.dedent(test_text), res) local res2 = exec_lua(function() local parser = vim.treesitter.get_parser(0, 'c') @@ -436,9 +436,9 @@ void ui_refresh(void) it('can get text where start of node is one past EOF', function() local text = [[ -def run - a = <<~E -end]] + def run + a = <<~E + end]] insert(text) eq( '', @@ -463,9 +463,10 @@ end]] it('can get empty text if node range is zero-width', function() local text = [[ -```lua -{} -```]] + ```lua + {} + ``` + ]] insert(text) local result = exec_lua(function() local fake_node = {} @@ -602,12 +603,12 @@ end]] before_each(function() insert([[ -int x = INT_MAX; -#define READ_STRING(x, y) (char *)read_string((x), (size_t)(y)) -#define READ_STRING_OK(x, y) (char *)read_string((x), (size_t)(y)) -#define VALUE 123 -#define VALUE1 123 -#define VALUE2 123 + int x = INT_MAX; + #define READ_STRING(x, y) (char *)read_string((x), (size_t)(y)) + #define READ_STRING_OK(x, y) (char *)read_string((x), (size_t)(y)) + #define VALUE 123 + #define VALUE1 123 + #define VALUE2 123 ]]) end) @@ -989,8 +990,8 @@ int x = INT_MAX; describe('when getting the language for a range', function() before_each(function() insert([[ -int x = INT_MAX; -#define VALUE 123456789 + int x = INT_MAX; + #define VALUE 123456789 ]]) end) @@ -1015,7 +1016,7 @@ int x = INT_MAX; describe('when setting the node for an injection', function() before_each(function() insert([[ -print() + print() ]]) end) diff --git a/test/functional/treesitter/select_spec.lua b/test/functional/treesitter/select_spec.lua index eb1acff85e..25fc7ad657 100644 --- a/test/functional/treesitter/select_spec.lua +++ b/test/functional/treesitter/select_spec.lua @@ -33,7 +33,7 @@ local function treeselect(cmd_, ...) end, cmd_, ...) end -describe('incremental treesitter selection', function() +describe('treesitter incremental-selection', function() before_each(function() clear() @@ -66,7 +66,7 @@ describe('incremental treesitter selection', function() eq('foo(1)\nbar(2)\n', get_selected()) end) - it('repeate works', function() + it('repeat', function() set_lines('foo(1,2,3,4)') treeselect('select_node') eq('foo', get_selected()) @@ -91,7 +91,7 @@ describe('incremental treesitter selection', function() eq('2', get_selected()) end) - it('has history', function() + it('history', function() treeselect('select_node') treeselect('select_child') treeselect('select_next') @@ -111,7 +111,7 @@ describe('incremental treesitter selection', function() eq('foo(1)', get_selected()) end) - it('correctly selects node as parent when node half selected', function() + it('selects node as parent when node half-selected', function() feed('kkl', 'v', 'l') eq('oo', get_selected()) @@ -119,7 +119,7 @@ describe('incremental treesitter selection', function() eq('foo', get_selected()) end) - it('correctly selects node as child when node half selected', function() + it('selects node as child when node half-selected', function() feed('kkl', 'v', 'l') eq('oo', get_selected()) @@ -127,7 +127,7 @@ describe('incremental treesitter selection', function() eq('foo', get_selected()) end) - it('correctly find child node when node half selected', function() + it('finds child node when node half-selected', function() feed('kkl', 'v', 'j') eq('oo(1)\nba', get_selected()) @@ -135,7 +135,7 @@ describe('incremental treesitter selection', function() eq('(1)', get_selected()) end) - it('maintainse cursor selection-end-pos', function() + it('maintains cursor selection-end-pos', function() feed('kk') treeselect('select_node') eq('foo', get_selected()) @@ -174,7 +174,7 @@ describe('incremental treesitter selection', function() end) end) -describe('incremental treesitter selection with injections', function() +describe('treesitter incremental-selection with injections', function() before_each(function() clear({ args_rm = { '--cmd' }, args = { '--clean', '--cmd', n.runtime_set } }) end) From a3058abf301aa3553398f70f5d3ea6a12b6f4e38 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 11 Mar 2026 15:10:48 +0100 Subject: [PATCH 3/4] docs: deprecate hit-enter --- runtime/doc/api.txt | 2 +- runtime/doc/deprecated.txt | 5 ++ runtime/doc/dev_test.txt | 9 ++- runtime/doc/lua.txt | 51 +++++++------ runtime/doc/message.txt | 85 ++++------------------ runtime/doc/starting.txt | 3 +- runtime/doc/vvars.txt | 6 +- runtime/lua/vim/_core/ui2.lua | 55 +++++++------- runtime/lua/vim/_meta/vvars.lua | 6 +- runtime/lua/vim/pack/_lsp.lua | 2 +- src/nvim/vvars.lua | 6 +- test/functional/api/vim_spec.lua | 4 +- test/functional/ex_cmds/mksession_spec.lua | 2 +- test/functional/terminal/tui_spec.lua | 4 +- 14 files changed, 92 insertions(+), 148 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 6c260e16db..ee38379cfc 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -157,7 +157,7 @@ indices, end-inclusive): *api-fast* Most API functions are "deferred": they are queued on the main loop and processed sequentially with normal input. So if the editor is waiting for -user input in a "modal" fashion (e.g. the |hit-enter-prompt|), the request +user input in a "modal" fashion (e.g. an |input()| prompt), the request will block. Non-deferred (fast) functions such as |nvim_get_mode()| and |nvim_input()| are served immediately (i.e. without waiting in the input queue). Lua code can use |vim.in_fast_event()| to detect a fast context. diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index c27a7c018d..618083717c 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -52,6 +52,11 @@ LUA • *vim.diff()* Renamed to |vim.text.diff()| +UI + +• *hit-enter* *hit-enter-prompt* With |ui2|, the legacy "Press ENTER" + *press-enter prompt is never triggered. + VIMSCRIPT • todo diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt index 9bfab61964..b5f7985bae 100644 --- a/runtime/doc/dev_test.txt +++ b/runtime/doc/dev_test.txt @@ -123,10 +123,11 @@ DEBUGGING TESTS See `nvim_argv` in `test/functional/testnvim.lua`. -- Hanging tests can happen due to unexpected "press-enter" prompts. The - default screen width is 50 columns. Commands that try to print lines longer - than 50 columns in the command-line, e.g. `:edit very...long...path`, will - trigger the prompt. Try using a shorter path, or `:silent edit`. +- Hanging tests can happen due to unexpected modal prompts (waiting for user + input). The default screen width is 50 columns. + - Commands that try to print lines longer than 50 columns in the cmdline, + e.g. `:edit very...long...path`, will trigger the hit-enter prompt. Try + using a shorter path, or `:silent edit`. - If you can't figure out what is going on, try to visualize the screen. Put this at the beginning of your test: > local Screen = require('test.functional.ui.screen') diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index ecd04b835e..111cdc5191 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -5355,39 +5355,38 @@ vim.version.range({spec}) *vim.version.range()* ============================================================================== UI2 *ui2* -WARNING: This is an experimental interface intended to replace the message -grid in the TUI. +WARNING: This is an experimental feature intended to replace the builtin +message + cmdline presentation layer. -To enable the experimental UI (default opts shown): >lua +To enable this feature (default opts shown): >lua require('vim._core.ui2').enable({ - enable = true, -- Whether to enable or disable the UI. - msg = { -- Options related to the message module. - ---@type 'cmd'|'msg' Default message target, either in the - ---cmdline or in a separate ephemeral message window. - ---@type string|table Default message target - ---or table mapping |ui-messages| kinds and triggers to a target. - targets = 'cmd', - timeout = 4000, -- Time a message is visible in the message window. - }, + enable = true, -- Whether to enable or disable the UI. + msg = { -- Options related to the message module. + ---@type 'cmd'|'msg' Default message target, either in the + ---cmdline or in a separate ephemeral message window. + ---@type string|table Default message target + ---or table mapping |ui-messages| kinds and triggers to a target. + targets = 'cmd', + timeout = 4000, -- Time a message is visible in the message window. + }, }) < -There are four separate window types used by this interface: -• "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and - messages if 'cmdheight' > 0. -• "msg": The message window; used for messages when 'cmdheight' == 0. -• "pager": The pager window; used for |:messages| and certain messages that - should be shown in full. -• "dialog": The dialog window; used for prompt messages that expect user - input. +There are four special windows/buffers for presenting messages and cmdline: +• "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages + if 'cmdheight' > 0. +• "msg": Message window, shows messages when 'cmdheight' == 0. +• "pager": Pager window, shows |:messages| and certain messages that are never + "collapsed". +• "dialog": Dialog window, shows modal prompts that expect user input. -These four windows are assigned the "cmd", "msg", "pager" and "dialog" -'filetype' respectively. Use a |FileType| autocommand to configure any local -options for these windows and their respective buffers. +The buffer 'filetype' is to the above-listed id ("cmd", "msg", …). Handle +the |FileType| event to configure any local options for these windows and +their respective buffers. -Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do -not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the -spilled lines. To see the full message, use either: +Unlike the legacy |hit-enter| prompt, messages that overflow the cmdline area +are instead "collapsed", followed by a `[+x]` "spill" indicator, where `x` +indicates the spilled lines. To see the full messages, do either: • ENTER immediately after a message from interactive |:| cmdline. • |g<| at any time. diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index 6ff87b00e8..9cfc21e391 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -30,14 +30,9 @@ depends on the 'shortmess' option. The number of remembered messages is determined by the 'messagesopt' option. *g<* -The "g<" command can be used to see the last page of previous command output. -This is especially useful if you accidentally typed at the hit-enter -prompt. You are then back at the hit-enter prompt and can then scroll further -back. -Note: If the output has been stopped with "q" at the more prompt, it will only -be displayed up to this point. -The previous command output is cleared when another command produces output. -The "g<" output is not redirected. +The "g<" command shows the last page of previous command output. +This only works when 'more' is set. +With |ui2|: "g<" shows recent messages in the |pager|. If you want to find help on a specific (error) message, use the ID at the start of the message. For example, to get help on the message: > @@ -840,65 +835,26 @@ error message and traceback. ============================================================================== Messages *messages* -This is an (incomplete) overview of various messages that Vim gives: +Messages are shown in the |ui2| messages area. If they exceed ("overflow") the +area then they will be collapsed and a "spill" indicator will indicate how +many lines were collapsed. Use |g<| to see the full messages. - *hit-enter* *press-enter* *hit-return* - *press-return* *hit-enter-prompt* > - - Press ENTER or type command to continue - -This message is given when there is something on the screen for you to read, -and the screen is about to be redrawn: -- After executing an external command (e.g., ":!ls" and "="). -- Something is displayed on the status line that is longer than the width of - the window, or runs into the 'showcmd' or 'ruler' output. - --> Press or to redraw the screen and continue, without that - key being used otherwise. --> Press ':' or any other Normal mode command character to start that command. - Note that after an external command some special keys, such as the cursor - keys, may not work normally, because the terminal is still set to a state - for executing the external command. --> Press 'k', , 'u', 'b' or 'g' to scroll back in the messages. This - works the same way as at the |more-prompt|. Only works when 'more' is on. --> Pressing 'j', 'f', 'd' or is ignored when messages scrolled off the - top of the screen and 'more' is on, to avoid that typing one 'j' or 'f' too - many causes the messages to disappear. --> Press to copy (yank) a modeless selection to the clipboard register. --> Use a menu. The characters defined for Cmdline-mode are used. --> When 'mouse' contains the 'r' flag, clicking the left mouse button works - like pressing . This makes it impossible to select text though. --> For the GUI clicking the left mouse button in the last line works like - pressing . --> |q| won't start recording into a register (rationale: it is often used as - "quit" prompt key by users) - -If you accidentally hit or and you want to see the displayed -text then use |g<|. This only works when 'more' is set. - -To reduce the number of hit-enter prompts: -- Set 'messagesopt'. +To avoid overflow ("spill") of the |ui2| messages area: - Set 'cmdheight' to 2 or higher. - Add flags to 'shortmess'. - Reset 'showcmd' and/or 'ruler'. - Make sure `:echo` text is within |v:echospace| screen cells. -If your script causes the hit-enter prompt and you don't know why, you may -find the |v:scrollstart| variable useful. - -Also see 'mouse'. The hit-enter message is highlighted with the |hl-Question| -group. - - *more-prompt* *pager* > - -- More -- - -- More -- SPACE/d/j: screen/page/line down, b/u/k: up, q: quit + f/d/j: screen/page/line down, b/u/k: up, : stop paging -This message is given when the screen is filled with messages. It is only -given when the 'more' option is on. It is highlighted with the |hl-MoreMsg| -group. +This message is given when the |ui2| modal dialog is active. +Only when the 'more' option is on. +Highlighted with the |hl-MoreMsg| group. -Type effect ~ +With |ui2|: use "g<" to show messages in the pager. + + Type Effect ~ or or j or one more line d down a page (half a screen) or f or or CTRL-F down a screen @@ -920,19 +876,6 @@ Type effect ~ in Cmdline-mode. next page* -Any other key causes the meaning of the keys to be displayed. - -* Clicking the left mouse button only works: - - For the GUI: in the last line of the screen. - - When 'r' is included in 'mouse' (but then selecting text won't work). - - -Note: The typed key is directly obtained from the terminal, it is not mapped -and typeahead is ignored. - -The |g<| command can be used to see the last page of previous command output. -This is especially useful if you accidentally typed at the hit-enter -prompt. ============================================================================== Progress messages *progress-message* diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index b46e8d8f06..2d78197c2a 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1198,8 +1198,7 @@ running) you have additional options: List file names as with |:oldfiles|, and then prompt for a number. When the number is valid that file from the list is edited. - If you get the |press-enter| prompt you can press "q" - and still get the prompt to enter a file number. + Use [!] to abandon a modified buffer. |abandon| SHADA FILE FORMAT *shada-format* diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index 1df41773cf..7f90913449 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -127,7 +127,9 @@ v:dying *v:echospace* *echospace-variable* v:echospace Number of screen cells that can be used for an `:echo` message - in the last screen line before causing the |hit-enter-prompt|. + in the last screen line before causing the |hit-enter| prompt + (or "overflow" with |ui2|). + Depends on 'showcmd', 'ruler' and 'columns'. You need to check 'cmdheight' for whether there are full-width lines available above the last line. @@ -557,8 +559,6 @@ v:scrollstart screen to scroll up. It's only set when it is empty, thus the first reason is remembered. It is set to "Unknown" for a typed command. - This can be used to find out why your script causes the - hit-enter prompt. *v:searchforward* *searchforward-variable* v:searchforward diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua index c679f2bdde..1414eb75e7 100644 --- a/runtime/lua/vim/_core/ui2.lua +++ b/runtime/lua/vim/_core/ui2.lua @@ -1,38 +1,35 @@ --- @brief --- ----WARNING: This is an experimental interface intended to replace the message ----grid in the TUI. +--- WARNING: This is an experimental feature intended to replace the builtin message + cmdline +--- presentation layer. --- ----To enable the experimental UI (default opts shown): ----```lua ----require('vim._core.ui2').enable({ ---- enable = true, -- Whether to enable or disable the UI. ---- msg = { -- Options related to the message module. ---- ---@type 'cmd'|'msg' Default message target, either in the ---- ---cmdline or in a separate ephemeral message window. ---- ---@type string|table Default message target ---- ---or table mapping |ui-messages| kinds and triggers to a target. ---- targets = 'cmd', ---- timeout = 4000, -- Time a message is visible in the message window. ---- }, ----}) ----``` +--- To enable this feature (default opts shown): +--- ```lua +--- require('vim._core.ui2').enable({ +--- enable = true, -- Whether to enable or disable the UI. +--- msg = { -- Options related to the message module. +--- ---@type 'cmd'|'msg' Default message target, either in the +--- ---cmdline or in a separate ephemeral message window. +--- ---@type string|table Default message target +--- ---or table mapping |ui-messages| kinds and triggers to a target. +--- targets = 'cmd', +--- timeout = 4000, -- Time a message is visible in the message window. +--- }, +--- }) +--- ``` --- ----There are four separate window types used by this interface: ----- "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and ---- messages if 'cmdheight' > 0. ----- "msg": The message window; used for messages when 'cmdheight' == 0. ----- "pager": The pager window; used for |:messages| and certain messages ---- that should be shown in full. ----- "dialog": The dialog window; used for prompt messages that expect user input. +--- There are four special windows/buffers for presenting messages and cmdline: +--- - "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages if 'cmdheight' > 0. +--- - "msg": Message window, shows messages when 'cmdheight' == 0. +--- - "pager": Pager window, shows |:messages| and certain messages that are never "collapsed". +--- - "dialog": Dialog window, shows modal prompts that expect user input. --- ----These four windows are assigned the "cmd", "msg", "pager" and "dialog" ----'filetype' respectively. Use a |FileType| autocommand to configure any local ----options for these windows and their respective buffers. +--- The buffer 'filetype' is to the above-listed id ("cmd", "msg", …). Handle the |FileType| event +--- to configure any local options for these windows and their respective buffers. --- ----Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do ----not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the ----spilled lines. To see the full message, use either: +--- Unlike the legacy |hit-enter| prompt, messages that overflow the cmdline area are instead +--- "collapsed", followed by a `[+x]` "spill" indicator, where `x` indicates the spilled lines. To +--- see the full messages, do either: --- - ENTER immediately after a message from interactive |:| cmdline. --- - |g<| at any time. diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index dec1cfc476..fde0af2f0e 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -127,7 +127,9 @@ vim.v.ctype = ... vim.v.dying = ... --- Number of screen cells that can be used for an `:echo` message ---- in the last screen line before causing the `hit-enter-prompt`. +--- in the last screen line before causing the `hit-enter` prompt +--- (or "overflow" with `ui2`). +--- --- Depends on 'showcmd', 'ruler' and 'columns'. You need to --- check 'cmdheight' for whether there are full-width lines --- available above the last line. @@ -581,8 +583,6 @@ vim.v.relnum = ... --- screen to scroll up. It's only set when it is empty, thus the --- first reason is remembered. It is set to "Unknown" for a --- typed command. ---- This can be used to find out why your script causes the ---- hit-enter prompt. --- @type string vim.v.scrollstart = ... diff --git a/runtime/lua/vim/pack/_lsp.lua b/runtime/lua/vim/pack/_lsp.lua index f0d3dc235b..f40d65ddea 100644 --- a/runtime/lua/vim/pack/_lsp.lua +++ b/runtime/lua/vim/pack/_lsp.lua @@ -167,7 +167,7 @@ local commands = { end, } --- NOTE: Use `vim.schedule_wrap` to avoid press-enter after choosing code +-- NOTE: Use `vim.schedule_wrap` to avoid hit-enter after choosing code -- action via built-in `vim.fn.inputlist()` --- @param params { command: string, arguments: table } --- @param callback function diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua index c6b839fef3..0136bbd9e1 100644 --- a/src/nvim/vvars.lua +++ b/src/nvim/vvars.lua @@ -144,7 +144,9 @@ M.vars = { type = 'integer', desc = [=[ Number of screen cells that can be used for an `:echo` message - in the last screen line before causing the |hit-enter-prompt|. + in the last screen line before causing the |hit-enter| prompt + (or "overflow" with |ui2|). + Depends on 'showcmd', 'ruler' and 'columns'. You need to check 'cmdheight' for whether there are full-width lines available above the last line. @@ -666,8 +668,6 @@ M.vars = { screen to scroll up. It's only set when it is empty, thus the first reason is remembered. It is set to "Unknown" for a typed command. - This can be used to find out why your script causes the - hit-enter prompt. ]=], }, searchforward = { diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua index ab947951d4..56ac0ec205 100644 --- a/test/functional/api/vim_spec.lua +++ b/test/functional/api/vim_spec.lua @@ -2182,7 +2182,7 @@ describe('API', function() eq({ mode = 'n', blocking = false }, api.nvim_get_mode()) end) - it('during press-enter prompt without UI returns blocking=false', function() + it('during hit-enter prompt without UI returns blocking=false', function() eq({ mode = 'n', blocking = false }, api.nvim_get_mode()) command("echom 'msg1'") command("echom 'msg2'") @@ -2194,7 +2194,7 @@ describe('API', function() eq({ mode = 'n', blocking = false }, api.nvim_get_mode()) end) - it('during press-enter prompt returns blocking=true', function() + it('during hit-enter prompt returns blocking=true', function() api.nvim_ui_attach(80, 20, {}) eq({ mode = 'n', blocking = false }, api.nvim_get_mode()) command("echom 'msg1'") diff --git a/test/functional/ex_cmds/mksession_spec.lua b/test/functional/ex_cmds/mksession_spec.lua index 7041288302..2ef2a87a2c 100644 --- a/test/functional/ex_cmds/mksession_spec.lua +++ b/test/functional/ex_cmds/mksession_spec.lua @@ -158,7 +158,7 @@ describe(':mksession', function() -- Create a new test instance of Nvim. clear() - -- Use :silent to avoid press-enter prompt due to long path + -- Use :silent to avoid hit-enter prompt due to long path command('silent source ' .. session_path) command('tabnext 1') eq(cwd_dir .. get_pathsep() .. tmpfile_base .. '1', fn.expand('%:p')) diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua index f0da67c699..a9203bd41f 100644 --- a/test/functional/terminal/tui_spec.lua +++ b/test/functional/terminal/tui_spec.lua @@ -3313,10 +3313,10 @@ describe('TUI FocusGained/FocusLost', function() ]]) end) - it('in press-enter prompt', function() + it('in hit-enter prompt', function() t.skip(is_os('win'), 'FIXME: some spaces have wrong attrs on Windows') feed_data(":echom 'msg1'|echom 'msg2'|echom 'msg3'|echom 'msg4'|echom 'msg5'\n") - -- Execute :messages to provoke the press-enter prompt. + -- Execute :messages to provoke the hit-enter prompt. feed_data(':messages\n') screen:expect([[ msg1 | From 682f5fee600802236e104ef85b5fbc6d3fe860cf Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 11 Mar 2026 18:24:57 +0100 Subject: [PATCH 4/4] docs: misc Close #37458 Close #37838 Close #37840 Close #37872 Close #37890 Close #38016 Close #38051 Close #38189 Close #38225 Close #38243 Close #38250 Co-authored-by: Colin Kennedy Co-authored-by: "Mike J. McGuirk" Co-authored-by: Austin Rambo Co-authored-by: Jonathan Birk <1965620+cafce25@users.noreply.github.com> Co-authored-by: Sean Dewar <6256228+seandewar@users.noreply.github.com> Co-authored-by: Mike Smith <10135646+mikesmithgh@users.noreply.github.com> Co-authored-by: Saad Nadeem Co-authored-by: brianhuster Co-authored-by: zeertzjq Co-authored-by: Yi Ming --- runtime/doc/cmdline.txt | 2 +- runtime/doc/faq.txt | 4 ++-- runtime/doc/index.txt | 3 ++- runtime/doc/quickref.txt | 3 ++- runtime/doc/vim_diff.txt | 2 ++ runtime/doc/vimfn.txt | 8 ++++---- runtime/lua/vim/_meta.lua | 1 + runtime/lua/vim/_meta/api.lua | 8 ++++---- runtime/lua/vim/_meta/builtin_types.lua | 1 + runtime/lua/vim/_meta/vimfn.lua | 8 ++++---- runtime/lua/vim/_meta/vvars_extra.lua | 2 +- src/nvim/api/vim.c | 8 ++++---- src/nvim/eval.lua | 6 ++++-- 13 files changed, 32 insertions(+), 24 deletions(-) diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index a9b7acdb20..1154bb4812 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -124,7 +124,7 @@ CTRL-W Delete the |word| before the cursor. This depends on the 'iskeyword' option. *c_CTRL-U* CTRL-U Remove all characters between the cursor position and - the beginning of the line. Previous versions of vim + the beginning of the line. Previous versions of Vim deleted all characters on the line. If that is the preferred behavior, add the following to your vimrc: > :cnoremap diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt index 3dae04d6c3..7e8180d964 100644 --- a/runtime/doc/faq.txt +++ b/runtime/doc/faq.txt @@ -356,7 +356,7 @@ CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK - https://github.com/vim/vim/issues/4379 This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way -with `set shortmes+=F`. There are plans to improve this, but meanwhile as a +with `set shortmess+=F`. There are plans to improve this, but meanwhile as a workaround, use `set shortmess-=F` or use `unsilent` as follows. >vim unsilent let var = inputlist(['1. item1', '2. item2']) @@ -386,7 +386,7 @@ Or, if you want automatic reloading when assigning to |g:clipboard|, set runtime autoload/provider/clipboard.vim endfunction - if !exists('s:loaded") + if !exists('s:loaded') call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed')) endif let s:loaded = v:true diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 493e00c956..a1e85a0fb6 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1057,7 +1057,8 @@ Tag Command Command-line editing-mode action ~ under the cursor literally CTRL-S not used, or used for terminal control flow |c_CTRL-T| CTRL-T previous match when 'incsearch' is active -|c_CTRL-U| CTRL-U remove all characters +|c_CTRL-U| CTRL-U remove all characters between the cursor + and beginning of command-line |c_CTRL-V| CTRL-V insert next non-digit literally, insert three digit decimal number as a single byte. |c_CTRL-W| CTRL-W delete the word in front of the cursor diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 32754d61c5..78444dbd33 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -1045,7 +1045,8 @@ Short explanation of each option: *option-list* |c_| delete the character in front of the cursor |c_| delete the character under the cursor |c_CTRL-W| CTRL-W delete the word in front of the cursor -|c_CTRL-U| CTRL-U remove all characters +|c_CTRL-U| CTRL-U remove all characters between the cursor + and beginning of command-line |c_| / recall older/newer command-line that starts with current command diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index a6b5b653e3..d8e959acb6 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -755,6 +755,8 @@ Eval: - *err_teapot()* - *js_encode()* - *js_decode()* +- *listener_add()* , etc: use |api-buffer-updates-lua| instead. +- *redraw_listener_add()* , etc: use |nvim_set_decoration_provider()| instead. - *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead. - *v:sizeofint* - *v:sizeoflong* diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 35d3b34df9..01472b04c0 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -7851,7 +7851,7 @@ readdir({directory} [, {expr}]) *readdir()* Parameters: ~ • {directory} (`string`) - • {expr} (`integer?`) + • {expr} (`integer|string|fun(name: string): integer?`) Return: ~ (`any`) @@ -8266,7 +8266,7 @@ screencol() *screencol()* < Return: ~ - (`integer[]`) + (`integer`) screenpos({winid}, {lnum}, {col}) *screenpos()* The result is a Dict with the screen position of the text @@ -8298,7 +8298,7 @@ screenpos({winid}, {lnum}, {col}) *screenpos()* • {col} (`integer`) Return: ~ - (`any`) + (`{ col: integer, curscol: integer, endcol: integer, row: integer }`) screenrow() *screenrow()* The result is a Number, which is the current screen row of the @@ -8742,7 +8742,7 @@ searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) • {skip} (`string|function?`) Return: ~ - (`any`) + (`{ [1]: integer, [2]: integer, [3]: integer? }`) serverlist([{opts}]) *serverlist()* Returns a list of server addresses, or empty if all servers diff --git a/runtime/lua/vim/_meta.lua b/runtime/lua/vim/_meta.lua index 02f886cf96..9ac6ceeb77 100644 --- a/runtime/lua/vim/_meta.lua +++ b/runtime/lua/vim/_meta.lua @@ -20,6 +20,7 @@ vim.iter = require('vim.iter') vim.keymap = require('vim.keymap') vim.loader = require('vim.loader') vim.lsp = require('vim.lsp') +vim.net = require('vim.net') vim.pack = require('vim.pack') vim.pos = require('vim.pos') vim.range = require('vim.range') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index ff05e0a332..1197e8620b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1299,15 +1299,15 @@ function vim.api.nvim_get_autocmds(opts) end --- - "stderr" stderr of this Nvim instance --- - "socket" TCP/IP socket or named pipe --- - "job" Job with communication over its stdio. ---- - "mode" How data received on the channel is interpreted. +--- - "mode" How data received on the channel is interpreted. --- - "bytes" Send and receive raw bytes. --- - "terminal" |terminal| instance interprets ASCII sequences. --- - "rpc" |RPC| communication on the channel is active. ---- - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like +--- - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like --- "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g. --- for conpty on Windows). ---- - "buffer" (optional) Buffer connected to |terminal| instance. ---- - "client" (optional) Info about the peer (client on the other end of the channel), as set +--- - "buffer" (optional) Buffer connected to |terminal| instance. +--- - "client" (optional) Info about the peer (client on the other end of the channel), as set --- by |nvim_set_client_info()|. --- - "exitcode" (optional) Exit code of the |terminal| process. --- diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua index 47a5242cbb..581926d5f3 100644 --- a/runtime/lua/vim/_meta/builtin_types.lua +++ b/runtime/lua/vim/_meta/builtin_types.lua @@ -60,6 +60,7 @@ --- @field botline integer --- @field bufnr integer --- @field height integer +--- @field leftcol integer --- @field loclist integer --- @field quickfix integer --- @field tabnr integer diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 2c95ae8c92..d012b68556 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -7132,7 +7132,7 @@ function vim.fn.readblob(fname, offset, size) end --- Returns an empty List on error. --- --- @param directory string ---- @param expr? integer +--- @param expr? integer|string|fun(name: string): integer --- @return any function vim.fn.readdir(directory, expr) end @@ -7521,7 +7521,7 @@ function vim.fn.screenchars(row, col) end --- noremap GG echom screencol() --- < --- ---- @return integer[] +--- @return integer function vim.fn.screencol() end --- The result is a Dict with the screen position of the text @@ -7550,7 +7550,7 @@ function vim.fn.screencol() end --- @param winid integer --- @param lnum integer --- @param col integer ---- @return any +--- @return { col: integer, curscol: integer, endcol: integer, row: integer } function vim.fn.screenpos(winid, lnum, col) end --- The result is a Number, which is the current screen row of the @@ -7969,7 +7969,7 @@ function vim.fn.searchpairpos(start, middle, end_, flags, skip, stopline, timeou --- @param stopline? integer --- @param timeout? integer --- @param skip? string|function ---- @return any +--- @return { [1]: integer, [2]: integer, [3]: integer? } function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end --- Returns a list of server addresses, or empty if all servers diff --git a/runtime/lua/vim/_meta/vvars_extra.lua b/runtime/lua/vim/_meta/vvars_extra.lua index 9fe0be4f27..41dcbce966 100644 --- a/runtime/lua/vim/_meta/vvars_extra.lua +++ b/runtime/lua/vim/_meta/vvars_extra.lua @@ -53,7 +53,7 @@ error('Cannot require a meta file') --- `v:event.operator` is "y". --- @field operator? string --- Text stored in the register as a |readfile()|-style list of lines. ---- @field regcontents? string +--- @field regcontents? string|string[] --- Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation. --- @field regname? string --- @field regtype? string Type of register as returned by |getregtype()|. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 1c5ffb5c0e..a28fca5d3d 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1709,15 +1709,15 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String /// - "stderr" stderr of this Nvim instance /// - "socket" TCP/IP socket or named pipe /// - "job" Job with communication over its stdio. -/// - "mode" How data received on the channel is interpreted. +/// - "mode" How data received on the channel is interpreted. /// - "bytes" Send and receive raw bytes. /// - "terminal" |terminal| instance interprets ASCII sequences. /// - "rpc" |RPC| communication on the channel is active. -/// - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like +/// - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like /// "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g. /// for conpty on Windows). -/// - "buffer" (optional) Buffer connected to |terminal| instance. -/// - "client" (optional) Info about the peer (client on the other end of the channel), as set +/// - "buffer" (optional) Buffer connected to |terminal| instance. +/// - "client" (optional) Info about the peer (client on the other end of the channel), as set /// by |nvim_set_client_info()|. /// - "exitcode" (optional) Exit code of the |terminal| process. /// diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 099dd418e9..9cd17b9a3a 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -8669,7 +8669,7 @@ M.funcs = { ]=], name = 'readdir', - params = { { 'directory', 'string' }, { 'expr', 'integer' } }, + params = { { 'directory', 'string' }, { 'expr', 'integer|string|fun(name: string): integer' } }, signature = 'readdir({directory} [, {expr}])', }, readfile = { @@ -9176,7 +9176,7 @@ M.funcs = { ]=], name = 'screencol', params = {}, - returns = 'integer[]', + returns = 'integer', signature = 'screencol()', }, screenpos = { @@ -9209,6 +9209,7 @@ M.funcs = { ]=], name = 'screenpos', params = { { 'winid', 'integer' }, { 'lnum', 'integer' }, { 'col', 'integer' } }, + returns = '{ col: integer, curscol: integer, endcol: integer, row: integer }', signature = 'screenpos({winid}, {lnum}, {col})', }, screenrow = { @@ -9671,6 +9672,7 @@ M.funcs = { { 'timeout', 'integer' }, { 'skip', 'string|function' }, }, + returns = '{ [1]: integer, [2]: integer, [3]: integer? }', signature = 'searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])', }, serverlist = {