From b8a976afdaf0080498e85530fae65a3165f201d5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 12 Feb 2026 14:16:47 +0100 Subject: [PATCH] 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)