GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-16 09:11:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc #31479

Browse Source
This commit is contained in:
Justin M. Keyes
2025-01-01 12:29:51 -08:00
committed by GitHub
parent 9d114b7205
commit dc692f553a
15 changed files with 151 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
runtime/doc/channel.txt
View File

@ -11,21 +11,20 @@ Nvim asynchronous IO *channel*
==============================================================================
1. Introduction *channel-intro*
Channels are nvim's way of communicating with external processes.
Channels are Nvim's way of communicating with external processes.
There are several ways to open a channel:
1. Through stdin/stdout when `nvim` is started with `--headless`, and a startup
script or --cmd command opens the stdio channel using |stdioopen()|.
1. Through stdin/stdout when `nvim` is started with `--headless` and a startup
script or `--cmd` command opens the stdio channel using |stdioopen()|.
2. Through stdin, stdout and stderr of a process spawned by |jobstart()|.
3. Through the PTY master end of a PTY opened with |nvim_open_term()| or
`jobstart(…, {'pty': v:true})`.
3. Through the PTY master end opened with `jobstart(…, {'pty': v:true})`.
4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|.
5. By another process connecting to a socket listened to by nvim. This only
5. By another process connecting to a socket listened to by Nvim. This only
supports RPC channels, see |rpc-connecting|.
Channels support multiple modes or protocols. In the most basic
@ -146,7 +145,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim
:echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
==============================================================================
3. Communicating using msgpack-rpc *channel-rpc*
3. Communicating with msgpack RPC *channel-rpc*
When channels are opened with the `rpc` option set to true, the channel can be
used for remote method calls in both directions, see |msgpack-rpc|. Note that

10
runtime/doc/gui.txt
View File

@ -17,10 +17,14 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
Nvim provides a default, builtin UI (the |TUI|), but there are many other
(third-party) GUIs that you can use instead:
==============================================================================
Third-party GUIs *third-party-guis* *vscode*
Nvim provides a builtin "terminal UI" (|TUI|), but also works with many
(third-party) GUIs which may provide a fresh look or extra features on top of
Nvim. For example, "vscode-neovim" essentally allows you to use VSCode as
a Nvim GUI.
*vscode*
- vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim
- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
- Neovide https://neovide.dev/

22
runtime/doc/intro.txt
View File

@ -32,8 +32,9 @@ and |user-manual|.
Resources *resources*
*internet* *www* *distribution*
- Nvim home page: https://neovim.io/
- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
Nvim home page:
https://neovim.io/
*book*
There are many resources to learn Vi, Vim, and Nvim. We recommend:
@ -48,6 +49,7 @@ There are many resources to learn Vi, Vim, and Nvim. We recommend:
- For more information try one of these:
- https://iccf-holland.org/click5.html
- https://www.vim.org/iccf/click5.html
- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
*bugs* *bug-report* *feature-request*
Report bugs and request features here: https://github.com/neovim/neovim/issues
@ -67,18 +69,24 @@ To install or upgrade Nvim, you can...
- Build from source:
https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-source
*uninstall*
------------------------------------------------------------------------------
Un-installing Nvim *uninstall*
To uninstall Nvim:
- If you downloaded a pre-built archive or built Nvim from source (e.g. `make
install`), just delete its files, typically located in: >
- If you downloaded a pre-built archive or built Nvim from source (e.g.
`make install`), just delete its files, typically located in: >
/usr/local/bin/nvim
/usr/local/share/nvim
<
- To find where Nvim is installed, run these commands: >
:echo v:progpath
:echo $VIMRUNTIME
<
- If you installed via package manager, read your package manager's
documentation. Common examples:
- APT (Debian, Ubuntu, …): `apt-get remove neovim`
- Homebrew (macOS): `brew install neovim`
- Scoop (Windows): `scoop install neovim`
- Homebrew (macOS): `brew uninstall neovim`
- Scoop (Windows): `scoop uninstall neovim`
==============================================================================
Sponsor Vim/Nvim development *sponsor* *register*

28
runtime/doc/lsp.txt
View File

@ -344,22 +344,17 @@ Each response handler has this signature: >
*lsp-handler-resolution*
Handlers can be set by (in increasing priority):
- Setting a field in vim.lsp.handlers. *vim.lsp.handlers*
`vim.lsp.handlers` is a global table that contains the default mapping of
|lsp-method| names to lsp-handlers.
*vim.lsp.handlers*
- Setting a field in `vim.lsp.handlers`. This global table contains the
default mappings of |lsp-method| names to handlers. (Note: only for
server-to-client requests/notifications, not client-to-server.)
Example: >lua
vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler
<
Note: this only applies for requests/notifications made by the
server to the client.
- The {handlers} parameter of |vim.lsp.start()|. This sets the default
|lsp-handler| for a specific server.
- Passing a {handlers} parameter to |vim.lsp.start()|. This sets the default
|lsp-handler| for a specific server. (Note: only for server-to-client
requests/notifications, not client-to-server.)
Example: >lua
vim.lsp.start {
..., -- Other configuration omitted.
handlers = {
@ -367,14 +362,9 @@ Handlers can be set by (in increasing priority):
},
}
<
Note: this only applies for requests/notifications made by the
server to the client.
- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
the |lsp-handler| ONLY for the given request(s).
- Passing a {handler} parameter to |vim.lsp.buf_request_all()|. This sets the
|lsp-handler| ONLY for the given request(s).
Example: >lua
vim.lsp.buf_request_all(
0,
'textDocument/publishDiagnostics',

16
runtime/doc/lua.txt
View File

@ -817,8 +817,8 @@ vim.json.encode({obj}, {opts}) *vim.json.encode()*
Parameters: ~
• {obj} (`any`)
• {opts} (`table<string,any>?`) Options table with keys:
• escape_slash: (boolean) (default false) When true, escapes
`/` character in JSON strings
• escape_slash: (boolean) (default false) Escape slash
characters "/" in string values.
Return: ~
(`string`)
@ -3062,11 +3062,13 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
items
vim.fs.joinpath({...}) *vim.fs.joinpath()*
Concatenates partial paths into one path. Slashes are normalized
(redundant slashes are removed, and on Windows backslashes are replaced
with forward-slashes) (e.g., `"foo/"` and `"/bar"` get joined to
`"foo/bar"`) (windows: e.g `"a\foo\"` and `"\bar"` are joined to
`"a/foo/bar"`)
Concatenates partial paths (one absolute or relative path followed by zero
or more relative paths). Slashes are normalized: redundant slashes are
removed, and (on Windows) backslashes are replaced with forward-slashes.
Examples:
• "foo/", "/bar" => "foo/bar"
• Windows: "a\foo\", "\bar" => "a/foo/bar"
Attributes: ~
Since: 0.10.0

2
runtime/doc/map.txt
View File

@ -12,7 +12,7 @@ manual.
Type |gO| to see the table of contents.
==============================================================================
1. Key mapping *keybind* *key-mapping* *mapping* *macro*
1. Key mapping *keybind* *key-mapping* *mapping*
Key mapping is used to change the meaning of typed keys. The most common use
is to define a sequence of commands for a function key. Example: >

6
runtime/doc/news.txt
View File

@ -67,7 +67,6 @@ DEFAULTS
current buffer, respectively.
• 'number', 'relativenumber', 'signcolumn', and 'foldcolumn' are disabled in
|terminal| buffers. See |terminal-config| for an example of changing these defaults.
• |vim.json.encode()| no longer escapes the forward slash symbol by default
DIAGNOSTICS
@ -137,6 +136,7 @@ LUA
• Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`,
`vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`,
and `vim.fn`.
• |vim.json.encode()| no longer escapes forward slashes "/" by default
OPTIONS
@ -192,7 +192,6 @@ The following new features were added.
API
• |nvim__ns_set()| can set properties for a namespace
• |vim.json.encode()| has an option to enable forward slash escaping
DEFAULTS
@ -270,6 +269,7 @@ LUA
is more performant and easier to read.
• |vim.str_byteindex()| and |vim.str_utfindex()| gained overload signatures
supporting two new parameters, `encoding` and `strict_indexing`.
• |vim.json.encode()| has an option to enable forward slash escaping
• |vim.fs.abspath()| converts paths to absolute paths.
OPTIONS
@ -282,6 +282,8 @@ PERFORMANCE
• Significantly reduced redraw time for long lines with treesitter
highlighting.
• LSP diagnostics and inlay hints are de-duplicated (new requests cancel
inflight requests). This greatly improves performance with slow LSP servers.
PLUGINS

2
runtime/doc/repeat.txt
View File

@ -111,7 +111,7 @@ To abort this type CTRL-C twice.
==============================================================================
Complex repeats *complex-repeat*
*q* *recording*
*q* *recording* *macro*
q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
(uppercase to append). The 'q' command is disabled
while executing a register, and it doesn't work inside

63
runtime/doc/treesitter.txt
View File

@ -81,8 +81,7 @@ that user config takes precedence over plugins, which take precedence over
queries bundled with Nvim). If a query should extend other queries instead
of replacing them, use |treesitter-query-modeline-extends|.
See |lua-treesitter-query| for the list of available methods for working with
treesitter queries from Lua.
The Lua interface is described at |lua-treesitter-query|.
TREESITTER QUERY PREDICATES *treesitter-predicates*
@ -1195,6 +1194,10 @@ register({lang}, {filetype}) *vim.treesitter.language.register()*
==============================================================================
Lua module: vim.treesitter.query *lua-treesitter-query*
This Lua |treesitter-query| interface allows you to create queries and use
them to parse text. See |vim.treesitter.query.parse()| for a working example.
*vim.treesitter.query.add_directive()*
add_directive({name}, {handler}, {opts})
Adds a new directive to be used in queries
@ -1325,21 +1328,30 @@ omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()*
• {base} (`string`)
parse({lang}, {query}) *vim.treesitter.query.parse()*
Parse {query} as a string. (If the query is in a file, the caller should
read the contents into a string before calling).
Parses a {query} string and returns a `Query` object
(|lua-treesitter-query|), which can be used to search the tree for the
query patterns (via |Query:iter_captures()|, |Query:iter_matches()|), or
inspect the query via these fields:
• `captures`: a list of unique capture names defined in the query (alias:
`info.captures`).
• `info.patterns`: information about predicates.
Returns a `Query` (see |lua-treesitter-query|) object which can be used to
search nodes in the syntax tree for the patterns defined in {query} using
the `iter_captures` and `iter_matches` methods.
Exposes `info` and `captures` with additional context about {query}.
• `captures` contains the list of unique capture names defined in {query}.
• `info.captures` also points to `captures`.
• `info.patterns` contains information about predicates.
Example (select the code then run `:'<,'>lua` to try it): >lua
local query = vim.treesitter.query.parse('vimdoc', [[
; query
((h1) @str
(#trim! @str 1 1 1 1))
]])
local tree = vim.treesitter.get_parser():parse()[1]
for id, node, metadata in query:iter_captures(tree:root(), 0) do
-- Print the node name and source text.
vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
end
<
Parameters: ~
• {lang} (`string`) Language to use for the query
• {query} (`string`) Query in s-expr syntax
• {query} (`string`) Query text, in s-expr syntax
Return: ~
(`vim.treesitter.Query`) Parsed query
@ -1349,18 +1361,23 @@ parse({lang}, {query}) *vim.treesitter.query.parse()*
*Query:iter_captures()*
Query:iter_captures({node}, {source}, {start}, {stop})
Iterate over all captures from all matches inside {node}
Iterates over all captures from all matches in {node}.
{source} is needed if the query contains predicates; then the caller must
ensure to use a freshly parsed tree consistent with the current text of
the buffer (if relevant). {start} and {stop} can be used to limit matches
inside a row range (this is typically used with root node as the {node},
i.e., to get syntax highlight matches in the current viewport). When
omitted, the {start} and {stop} row values are used from the given node.
{source} is required if the query contains predicates; then the caller
must ensure to use a freshly parsed tree consistent with the current text
of the buffer (if relevant). {start} and {stop} can be used to limit
matches inside a row range (this is typically used with root node as the
{node}, i.e., to get syntax highlight matches in the current viewport).
When omitted, the {start} and {stop} row values are used from the given
node.
The iterator returns four values: a numeric id identifying the capture,
the captured node, metadata from any directives processing the match, and
the match itself. The following example shows how to get captures by name: >lua
The iterator returns four values:
1. the numeric id identifying the capture
2. the captured node
3. metadata from any directives processing the match
4. the match itself
Example: how to get captures by name: >lua
for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
local name = query.captures[id] -- name of the capture in the query
-- typically useful info about the node:

23
runtime/doc/vim_diff.txt
View File

@ -24,7 +24,7 @@ User configuration and data files are found in standard |base-directories|
session information. |shada|
==============================================================================
Defaults *nvim-defaults*
Defaults *defaults* *nvim-defaults*
- Filetype detection is enabled by default. This can be disabled by adding
":filetype off" to |init.vim|.
@ -291,7 +291,8 @@ Commands:
User commands can support |:command-preview| to show results as you type
- |:write| with "++p" flag creates parent directories.
Events:
Events (autocommands):
- Fixed inconsistent behavior in execution of nested autocommands #23368
- |RecordingEnter|
- |RecordingLeave|
- |SearchWrapped|
@ -299,6 +300,8 @@ Events:
- |TabNewEntered|
- |TermClose|
- |TermOpen|
- |TermResponse| is fired for any OSC sequence received from the terminal,
instead of the Primary Device Attributes response. |v:termresponse|
- |UIEnter|
- |UILeave|
@ -366,7 +369,7 @@ Options:
- 'shortmess'
- "F" flag does not affect output from autocommands.
- "q" flag fully hides macro recording message.
- 'signcolumn' supports up to 9 dynamic/fixed columns
- 'signcolumn' can show multiple signs (dynamic or fixed columns)
- 'statuscolumn' full control of columns using 'statusline' format
- 'tabline' middle-click on tabpage label closes tabpage,
and %@Func@foo%X can call any function on mouse-click
@ -375,6 +378,10 @@ Options:
- 'winblend' pseudo-transparency in floating windows |api-floatwin|
- 'winhighlight' window-local highlights
Performance:
- Signs are implemented using Nvim's internal "marktree" (btree) structure.
- Folds are not updated during insert-mode.
Providers:
- If a Python interpreter is available on your `$PATH`, |:python| and
|:python3| are always available. See |provider-python|.
@ -392,6 +399,7 @@ Shell:
- |system()| does not support writing/reading "backgrounded" commands. |E5677|
Signs:
- 'signcolumn' can show multiple signs.
- Signs are removed if the associated line is deleted.
- Signs placed twice with the same identifier in the same group are moved.
@ -584,9 +592,6 @@ Mappings:
Motion:
- The |jumplist| avoids useless/phantom jumps.
Performance:
- Folds are not updated during insert-mode.
Syntax highlighting:
- syncolor.vim has been removed. Nvim now sets up default highlighting groups
automatically for both light and dark backgrounds, regardless of whether or
@ -611,12 +616,6 @@ Working directory (Vim implemented some of these after Nvim):
- `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global
working directory. Use `getcwd(-1, -1)` to get the global working directory.
Autocommands:
- Fixed inconsistent behavior in execution of nested autocommands:
https://github.com/neovim/neovim/issues/23368
- |TermResponse| is fired for any OSC sequence received from the terminal,
instead of the Primary Device Attributes response. |v:termresponse|
Options:
- 'titlestring' uses printf-style '%' items (see: 'statusline') to implement
the default behaviour. The implementation is equivalent to setting

14
runtime/lua/vim/_meta/json.lua
View File

@ -25,18 +25,18 @@ vim.json = {}
---
---@param str string Stringified JSON data.
---@param opts? table<string,any> Options table with keys:
--- - luanil: (table) Table with keys:
--- * object: (boolean) When true, converts `null` in JSON objects
--- to Lua `nil` instead of |vim.NIL|.
--- * array: (boolean) When true, converts `null` in JSON arrays
--- to Lua `nil` instead of |vim.NIL|.
--- - luanil: (table) Table with keys:
--- - object: (boolean) When true, converts `null` in JSON objects
--- to Lua `nil` instead of |vim.NIL|.
--- - array: (boolean) When true, converts `null` in JSON arrays
--- to Lua `nil` instead of |vim.NIL|.
---@return any
function vim.json.decode(str, opts) end
--- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
---@param obj any
---@param opts? table<string,any> Options table with keys:
--- - escape_slash: (boolean) (default false) When true, escapes `/`
--- character in JSON strings
--- - escape_slash: (boolean) (default false) Escape slash
--- characters "/" in string values.
---@return string
function vim.json.encode(obj, opts) end

10
runtime/lua/vim/fs.lua
View File

@ -105,9 +105,13 @@ function M.basename(file)
return file:match('/$') and '' or (file:match('[^/]*$'))
end
--- Concatenates partial paths into one path. Slashes are normalized (redundant slashes are removed, and on Windows backslashes are replaced with forward-slashes)
--- (e.g., `"foo/"` and `"/bar"` get joined to `"foo/bar"`)
--- (windows: e.g `"a\foo\"` and `"\bar"` are joined to `"a/foo/bar"`)
--- Concatenates partial paths (one absolute or relative path followed by zero or more relative
--- paths). Slashes are normalized: redundant slashes are removed, and (on Windows) backslashes are
--- replaced with forward-slashes.
---
--- Examples:
--- - "foo/", "/bar" => "foo/bar"
--- - Windows: "a\foo\", "\bar" => "a/foo/bar"
---
---@since 12
---@param ... string

51
runtime/lua/vim/treesitter/query.lua
View File

@ -1,3 +1,6 @@
--- @brief This Lua |treesitter-query| interface allows you to create queries and use them to parse
--- text. See |vim.treesitter.query.parse()| for a working example.
local api = vim.api
local language = require('vim.treesitter.language')
local memoize = vim.func._memoize
@ -8,9 +11,9 @@ local M = {}
---Parsed query, see |vim.treesitter.query.parse()|
---
---@class vim.treesitter.Query
---@field lang string name of the language for this parser
---@field lang string parser language name
---@field captures string[] list of (unique) capture names defined in query
---@field info vim.treesitter.QueryInfo contains information used in the query (e.g. captures, predicates, directives)
---@field info vim.treesitter.QueryInfo query context (e.g. captures, predicates, directives)
---@field query TSQuery userdata query object
local Query = {}
Query.__index = Query
@ -228,20 +231,28 @@ M.get = memoize('concat-2', function(lang, query_name)
return M.parse(lang, query_string)
end)
--- Parse {query} as a string. (If the query is in a file, the caller
--- should read the contents into a string before calling).
--- Parses a {query} string and returns a `Query` object (|lua-treesitter-query|), which can be used
--- to search the tree for the query patterns (via |Query:iter_captures()|, |Query:iter_matches()|),
--- or inspect the query via these fields:
--- - `captures`: a list of unique capture names defined in the query (alias: `info.captures`).
--- - `info.patterns`: information about predicates.
---
--- Returns a `Query` (see |lua-treesitter-query|) object which can be used to
--- search nodes in the syntax tree for the patterns defined in {query}
--- using the `iter_captures` and `iter_matches` methods.
---
--- Exposes `info` and `captures` with additional context about {query}.
--- - `captures` contains the list of unique capture names defined in {query}.
--- - `info.captures` also points to `captures`.
--- - `info.patterns` contains information about predicates.
--- Example (select the code then run `:'<,'>lua` to try it):
--- ```lua
--- local query = vim.treesitter.query.parse('vimdoc', [[
--- ; query
--- ((h1) @str
--- (#trim! @str 1 1 1 1))
--- ]])
--- local tree = vim.treesitter.get_parser():parse()[1]
--- for id, node, metadata in query:iter_captures(tree:root(), 0) do
--- -- Print the node name and source text.
--- vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
--- end
--- ```
---
---@param lang string Language to use for the query
---@param query string Query in s-expr syntax
---@param query string Query text, in s-expr syntax
---
---@return vim.treesitter.Query : Parsed query
---
@ -847,20 +858,22 @@ local function match_id_hash(_, match)
return (match:info())
end
--- Iterate over all captures from all matches inside {node}
--- Iterates over all captures from all matches in {node}.
---
--- {source} is needed if the query contains predicates; then the caller
--- {source} is required if the query contains predicates; then the caller
--- must ensure to use a freshly parsed tree consistent with the current
--- text of the buffer (if relevant). {start} and {stop} can be used to limit
--- matches inside a row range (this is typically used with root node
--- as the {node}, i.e., to get syntax highlight matches in the current
--- viewport). When omitted, the {start} and {stop} row values are used from the given node.
---
--- The iterator returns four values: a numeric id identifying the capture,
--- the captured node, metadata from any directives processing the match,
--- and the match itself.
--- The following example shows how to get captures by name:
--- The iterator returns four values:
--- 1. the numeric id identifying the capture
--- 2. the captured node
--- 3. metadata from any directives processing the match
--- 4. the match itself
---
--- Example: how to get captures by name:
--- ```lua
--- for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
--- local name = query.captures[id] -- name of the capture in the query

2
test/functional/lua/fs_spec.lua
View File

@ -469,7 +469,7 @@ describe('vim.fs', function()
end)
end)
describe('abspath', function()
describe('abspath()', function()
local cwd = is_os('win') and vim.uv.cwd():gsub('\\', '/') or vim.uv.cwd()
local home = is_os('win') and vim.uv.os_homedir():gsub('\\', '/') or vim.uv.os_homedir()

2
test/functional/lua/json_spec.lua
View File

@ -152,7 +152,7 @@ describe('vim.json.encode()', function()
clear()
end)
it('dumps strings with & without escaped slash', function()
it('escape_slash', function()
-- With slash
eq('"Test\\/"', exec_lua([[return vim.json.encode('Test/', { escape_slash = true })]]))
eq(