IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc #31867

Browse Source
This commit is contained in:
Justin M. Keyes 2025-01-09 09:26:45 -08:00 committed by GitHub
parent 0c296ab224
commit 7c00e0efbb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
16 changed files with 155 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/vim_patches.yml vendored
View File

@ -43,7 +43,7 @@ jobs:
id: update-version
run: |
git checkout -b ${VERSION_BRANCH}
nvim -V1 -es -i NONE +'luafile scripts/vimpatch.lua' +q
nvim -l scripts/vimpatch.lua
printf 'NEW_PATCHES=%s\n' $([ -z "$(git diff)" ]; echo $?) >> $GITHUB_OUTPUT
- name: Automatic PR

50
runtime/doc/api.txt
View File

@ -654,20 +654,22 @@ nvim_del_var({name}) *nvim_del_var()*
• {name} Variable name
nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
Echo a message.
Prints a message given by a list of `[text, hl_group]` "chunks".
Example: >lua
vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
<
Parameters: ~
• {chunks} A list of `[text, hl_group]` arrays, each representing a
text chunk with specified highlight group name or ID.
`hl_group` element can be omitted for no highlight.
• {chunks} List of `[text, hl_group]` pairs, where each is a `text`
string highlighted by the (optional) name or ID `hl_group`.
• {history} if true, add to |message-history|.
• {opts} Optional parameters.
• err: Treat the message like |:echoerr|. Omitted `hlgroup`
uses |hl-ErrorMsg| instead.
• verbose: Message is printed as a result of 'verbose'
option. If Nvim was invoked with -V3log_file, the message
will be redirected to the log_file and suppressed from
direct output.
• err: Treat the message like `:echoerr`. Sets `hl_group`
to |hl-ErrorMsg| by default.
• verbose: Message is controlled by the 'verbose' option.
Nvim invoked with `-V3log` will write the message to the
"log" file instead of standard output.
nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()*
Evaluates statusline string.
@ -760,6 +762,8 @@ nvim_get_api_info() *nvim_get_api_info()*
nvim_get_chan_info({chan}) *nvim_get_chan_info()*
Gets information about a channel.
See |nvim_list_uis()| for an example of how to get channel info.
Parameters: ~
• {chan} channel_id, or 0 for current channel
@ -781,7 +785,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()*
present if a pty is used (e.g. for conpty on Windows).
• "buffer" (optional) Buffer connected to |terminal| instance.
• "client" (optional) Info about the peer (client on the other end of
the RPC channel), which it provided via |nvim_set_client_info()|.
the channel), as set by |nvim_set_client_info()|.
nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
@ -1064,6 +1068,12 @@ nvim_list_tabpages() *nvim_list_tabpages()*
nvim_list_uis() *nvim_list_uis()*
Gets a list of dictionaries representing attached UIs.
Example: The Nvim builtin |TUI| sets its channel info as described in
|startup-tui|. In particular, it sets `client.name` to "nvim-tui". So you
can check if the TUI is running by inspecting the client name of each UI: >lua
vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
<
Return: ~
Array of UI dictionaries, each with these keys:
• "height" Requested height of the UI
@ -1112,7 +1122,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()*
Example: this `TermHl` command can be used to display and highlight raw
ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals
like kitty): *terminal-scrollback-pager* >lua
like kitty): *ansi-colorize* *terminal-scrollback-pager* >lua
vim.api.nvim_create_user_command('TermHl', function()
local b = vim.api.nvim_create_buf(false, true)
local chan = vim.api.nvim_open_term(b, {})
@ -1237,25 +1247,23 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
*nvim_set_client_info()*
nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
Self-identifies the client.
Self-identifies the client. Sets the `client` object returned by
|nvim_get_chan_info()|.
The client/plugin/application should call this after connecting, to
provide hints about its identity and purpose, for debugging and
orchestration.
Clients should call this just after connecting, to provide hints for
debugging and orchestration. (Note: Something is better than nothing!
Fields are optional, but at least set `name`.)
Can be called more than once; the caller should merge old info if
appropriate. Example: library first identifies the channel, then a plugin
using that library later identifies itself.
Note: ~
• "Something is better than nothing". You don't need to include all the
fields.
Attributes: ~
|RPC| only
Parameters: ~
• {name} Short name for the connected client
• {name} Client short-name. Sets the `client.name` field of
|nvim_get_chan_info()|.
• {version} Dict describing the version, with these (optional) keys:
• "major" major version (defaults to 0 if not set, for
no release yet)

30
runtime/doc/health.txt
View File

@ -21,18 +21,7 @@ To run all healthchecks, use: >vim
<
Plugin authors are encouraged to write new healthchecks. |health-dev|
*g:health*
g:health This global variable controls the behavior and appearance of the
`health` floating window. It should be a dictionary containing the
following optional keys:
- `style`: string? Determines the display style of the `health` window.
Set to `'float'` to enable a floating window. Other
styles are not currently supported.
Example: >lua
vim.g.health = { style = 'float' }
Commands *health-commands*
COMMANDS *health-commands*
*:che* *:checkhealth*
:che[ckhealth] Run all healthchecks.
@ -60,6 +49,23 @@ Commands *health-commands*
:checkhealth vim*
<
USAGE *health-usage*
Local mappings in the healthcheck buffer:
q Closes the window.
Global configuration:
*g:health*
g:health Dictionary with the following optional keys:
- `style` (`'float'|nil`) Set to "float" to display :checkhealth in
a floating window instead of the default behavior.
Example: >lua
vim.g.health = { style = 'float' }
--------------------------------------------------------------------------------
Create a healthcheck *health-dev*
Healthchecks are functions that check the user environment, configuration, or

8
runtime/doc/lua.txt
View File

@ -1505,7 +1505,7 @@ vim.wo[{winid}][{bufnr}] *vim.wo*
Lua module: vim *lua-vim*
vim.cmd({command}) *vim.cmd()*
Executes Vim script commands.
Executes Vimscript (|Ex-commands|).
Note that `vim.cmd` can be indexed with a command name to return a
callable function to the command.
@ -1539,9 +1539,9 @@ vim.cmd({command}) *vim.cmd()*
Parameters: ~
• {command} (`string|table`) Command(s) to execute. If a string,
executes multiple lines of Vim script at once. In this
case, it is an alias to |nvim_exec2()|, where `opts.output`
is set to false. Thus it works identical to |:source|. If a
executes multiple lines of Vimscript at once. In this case,
it is an alias to |nvim_exec2()|, where `opts.output` is
set to false. Thus it works identical to |:source|. If a
table, executes a single command. In this case, it is an
alias to |nvim_cmd()| where `opts` is empty.

6
runtime/doc/news.txt
View File

@ -221,6 +221,7 @@ DIAGNOSTICS
EDITOR
• Use |yxx| in :help docs to execute Lua and Vimscript code examples.
• Improved |paste| handling for redo (dot-repeat) and macros (|recording|):
• Redoing a large paste is significantly faster and ignores 'autoindent'.
• Replaying a macro with |@| also replays pasted text.
@ -276,7 +277,6 @@ LUA
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.
• Lua and vimscript code examples in docs can now be run using `yxx`.
OPTIONS
@ -362,8 +362,8 @@ UI
• |vim.diagnostic.setqflist()| updates an existing quickfix list with the
given title if found
• |ui-messages| content chunks now also contain the highlight group ID.
• |:checkhealth| can be display in a floating window and controlled by
the |g:health| variable.
• |:checkhealth| can display in a floating window, controlled by the
|g:health| variable.
==============================================================================
CHANGED FEATURES *news-changed*

33
runtime/doc/starting.txt
View File

@ -164,8 +164,7 @@ argument.
you can overwrite a file by adding an exclamation mark to
the Ex command, as in ":w!". The 'readonly' option can be
reset with ":set noro" (see the options chapter, |options|).
Subsequent edits will not be done in readonly mode. Calling
the executable "view" has the same effect as the -R argument.
Subsequent edits will not be done in readonly mode.
The 'updatecount' option will be set to 10000, meaning that
the swap file will not be updated automatically very often.
See |-M| for disallowing modifications.
@ -226,7 +225,8 @@ argument.
arguments. The {script} name is stored at `_G.arg[0]`.
Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to
output.
output, as well as other message-emitting functions like
|:echo|.
If {script} prints messages and doesn't cause Nvim to exit,
Nvim ensures output ends with a newline.
@ -288,21 +288,18 @@ argument.
command from a script. |debug-mode|
*-n*
-n No |swap-file| will be used. Recovery after a crash will be
impossible. Handy if you want to view or edit a file on a
very slow medium (e.g., a floppy).
Can also be done with ":set updatecount=0". You can switch it
on again by setting the 'updatecount' option to some value,
e.g., ":set uc=100".
'updatecount' is set to 0 AFTER executing commands from a
vimrc file, but before the GUI initializations. Thus it
overrides a setting for 'updatecount' in a vimrc file, but not
in a gvimrc file. See |startup|.
When you want to reduce accesses to the disk (e.g., for a
laptop), don't use "-n", but set 'updatetime' and
'updatecount' to very big numbers, and type ":preserve" when
you want to save your work. This way you keep the possibility
for crash recovery.
-n Disables |swap-file| by setting 'updatecount' to 0 (after
executing any |vimrc|). Recovery after a crash will be
impossible. Improves peformance when working with a file on
a very slow medium (usb drive, network share).
Enable it again by setting 'updatecount' to some value, e.g.
":set updatecount=100".
To reduce accesses to the disk, don't use "-n", but set
'updatetime' and 'updatecount' to very big numbers, and type
":preserve" when you want to save your work. This way you
keep the possibility for crash recovery.
*-o*
-o[N] Open N windows, split horizontally. If [N] is not given,

7
runtime/doc/vim_diff.txt
View File

@ -423,8 +423,11 @@ TUI:
<
*'term'* *E529* *E530* *E531*
- 'term' reflects the terminal type derived from |$TERM| and other environment
checks. For debugging only; not reliable during startup. >vim
:echo &term
checks. Use `:echo &term` to get its value. For debugging only; not
reliable during startup.
- Note: If you want to detect when Nvim is running in a terminal, use
`has('gui_running')` |has()| or see |nvim_list_uis()| for an example of
how to inspect the UI channel.
- "builtin_x" means one of the |builtin-terms| was chosen, because the expected
terminfo file was not found on the system.
- Nvim will use 256-colour capability on Linux virtual terminals. Vim uses

4
runtime/lua/vim/_editor.lua
View File

@ -391,7 +391,7 @@ end
local VIM_CMD_ARG_MAX = 20
--- Executes Vim script commands.
--- Executes Vimscript (|Ex-commands|).
---
--- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
--- command.
@ -426,7 +426,7 @@ local VIM_CMD_ARG_MAX = 20
--- ```
---
---@param command string|table Command(s) to execute.
--- If a string, executes multiple lines of Vim script at once. In this
--- If a string, executes multiple lines of Vimscript at once. In this
--- case, it is an alias to |nvim_exec2()|, where `opts.output` is set
--- to false. Thus it works identical to |:source|.
--- If a table, executes a single command. In this case, it is an alias

37
runtime/lua/vim/_meta/api.lua generated
View File

@ -1097,18 +1097,20 @@ function vim.api.nvim_del_user_command(name) end
--- @param name string Variable name
function vim.api.nvim_del_var(name) end
--- Echo a message.
--- Prints a message given by a list of `[text, hl_group]` "chunks".
---
--- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
--- text chunk with specified highlight group name or ID.
--- `hl_group` element can be omitted for no highlight.
--- Example:
--- ```lua
--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
--- ```
---
--- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
--- the (optional) name or ID `hl_group`.
--- @param history boolean if true, add to `message-history`.
--- @param opts vim.api.keyset.echo_opts Optional parameters.
--- - err: Treat the message like `:echoerr`. Omitted `hlgroup`
--- uses `hl-ErrorMsg` instead.
--- - verbose: Message is printed as a result of 'verbose' option.
--- If Nvim was invoked with -V3log_file, the message will be
--- redirected to the log_file and suppressed from direct output.
--- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
--- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
--- will write the message to the "log" file instead of standard output.
function vim.api.nvim_echo(chunks, history, opts) end
--- @deprecated
@ -1276,6 +1278,8 @@ function vim.api.nvim_get_autocmds(opts) end
--- Gets information about a channel.
---
--- See `nvim_list_uis()` for an example of how to get channel info.
---
--- @param chan integer channel_id, or 0 for current channel
--- @return table<string,any> # Channel info dict with these keys:
--- - "id" Channel id.
@ -1293,8 +1297,8 @@ function vim.api.nvim_get_autocmds(opts) end
--- "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
--- for conpty on Windows).
--- - "buffer" (optional) Buffer connected to |terminal| instance.
--- - "client" (optional) Info about the peer (client on the other end of the RPC channel),
--- which it provided via |nvim_set_client_info()|.
--- - "client" (optional) Info about the peer (client on the other end of the channel), as set
--- by |nvim_set_client_info()|.
---
function vim.api.nvim_get_chan_info(chan) end
@ -1616,6 +1620,14 @@ function vim.api.nvim_list_tabpages() end
--- Gets a list of dictionaries representing attached UIs.
---
--- Example: The Nvim builtin `TUI` sets its channel info as described in `startup-tui`. In
--- particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by
--- inspecting the client name of each UI:
---
--- ```lua
--- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
--- ```
---
--- @return any[] # Array of UI dictionaries, each with these keys:
--- - "height" Requested height of the UI
--- - "width" Requested width of the UI
@ -1661,7 +1673,8 @@ function vim.api.nvim_notify(msg, log_level, opts) end
--- in a virtual terminal having the intended size.
---
--- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
--- can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
--- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
--- [terminal-scrollback-pager]()
---
--- ```lua
--- vim.api.nvim_create_user_command('TermHl', function()

30
runtime/lua/vim/health.lua
View File

@ -11,18 +11,7 @@
--- <
--- Plugin authors are encouraged to write new healthchecks. |health-dev|
---
--- *g:health*
--- g:health This global variable controls the behavior and appearance of the
--- `health` floating window. It should be a dictionary containing the
--- following optional keys:
--- - `style`: string? Determines the display style of the `health` window.
--- Set to `'float'` to enable a floating window. Other
--- styles are not currently supported.
---
--- Example: >lua
--- vim.g.health = { style = 'float' }
---
--- Commands *health-commands*
--- COMMANDS *health-commands*
---
--- *:che* *:checkhealth*
--- :che[ckhealth] Run all healthchecks.
@ -50,6 +39,23 @@
--- :checkhealth vim*
--- <
---
--- USAGE *health-usage*
---
--- Local mappings in the healthcheck buffer:
---
--- q Closes the window.
---
--- Global configuration:
---
--- *g:health*
--- g:health Dictionary with the following optional keys:
--- - `style` (`'float'|nil`) Set to "float" to display :checkhealth in
--- a floating window instead of the default behavior.
---
--- Example: >lua
--- vim.g.health = { style = 'float' }
---
--- --------------------------------------------------------------------------------
--- Create a healthcheck *health-dev*
---
--- Healthchecks are functions that check the user environment, configuration, or

3
runtime/lua/vim/lsp/util.lua
View File

@ -879,8 +879,7 @@ function M.make_floating_popup_options(width, height, opts)
col = col + (opts.offset_x or 0),
height = height,
focusable = opts.focusable,
relative = opts.relative == 'mouse' and 'mouse'
or opts.relative == 'editor' and 'editor'
relative = (opts.relative == 'mouse' or opts.relative == 'editor') and opts.relative
or 'cursor',
style = 'minimal',
width = width,

2
scripts/vimpatch.lua
View File

@ -1,7 +1,7 @@
-- Updates version.c list of applied Vim patches.
--
-- Usage:
-- VIM_SOURCE_DIR=~/neovim/.vim-src/ nvim -V1 -es -i NONE +'luafile ./scripts/vimpatch.lua' +q
-- VIM_SOURCE_DIR=~/neovim/.vim-src/ nvim -l ./scripts/vimpatch.lua
local nvim = vim.api

54
src/nvim/api/vim.c
View File

@ -766,18 +766,20 @@ void nvim_set_vvar(String name, Object value, Error *err)
dict_set_var(&vimvardict, name, value, false, false, NULL, err);
}
/// Echo a message.
/// Prints a message given by a list of `[text, hl_group]` "chunks".
///
/// @param chunks A list of `[text, hl_group]` arrays, each representing a
/// text chunk with specified highlight group name or ID.
/// `hl_group` element can be omitted for no highlight.
/// Example:
/// ```lua
/// vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
/// ```
///
/// @param chunks List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
/// the (optional) name or ID `hl_group`.
/// @param history if true, add to |message-history|.
/// @param opts Optional parameters.
/// - err: Treat the message like |:echoerr|. Omitted `hlgroup`
/// uses |hl-ErrorMsg| instead.
/// - verbose: Message is printed as a result of 'verbose' option.
/// If Nvim was invoked with -V3log_file, the message will be
/// redirected to the log_file and suppressed from direct output.
/// - err: Treat the message like `:echoerr`. Sets `hl_group` to |hl-ErrorMsg| by default.
/// - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
/// will write the message to the "log" file instead of standard output.
void nvim_echo(Array chunks, Boolean history, Dict(echo_opts) *opts, Error *err)
FUNC_API_SINCE(7)
{
@ -1000,7 +1002,8 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
/// in a virtual terminal having the intended size.
///
/// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
/// can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
/// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
/// [terminal-scrollback-pager]()
///
/// ```lua
/// vim.api.nvim_create_user_command('TermHl', function()
@ -1500,20 +1503,17 @@ Array nvim_get_api_info(uint64_t channel_id, Arena *arena)
return rv;
}
/// Self-identifies the client.
/// Self-identifies the client. Sets the `client` object returned by |nvim_get_chan_info()|.
///
/// The client/plugin/application should call this after connecting, to provide
/// hints about its identity and purpose, for debugging and orchestration.
/// Clients should call this just after connecting, to provide hints for debugging and
/// orchestration. (Note: Something is better than nothing! Fields are optional, but at least set
/// `name`.)
///
/// Can be called more than once; the caller should merge old info if
/// appropriate. Example: library first identifies the channel, then a plugin
/// using that library later identifies itself.
///
/// @note "Something is better than nothing". You don't need to include all the
/// fields.
/// Can be called more than once; the caller should merge old info if appropriate. Example: library
/// first identifies the channel, then a plugin using that library later identifies itself.
///
/// @param channel_id
/// @param name Short name for the connected client
/// @param name Client short-name. Sets the `client.name` field of |nvim_get_chan_info()|.
/// @param version Dict describing the version, with these
/// (optional) keys:
/// - "major" major version (defaults to 0 if not set, for no release yet)
@ -1587,6 +1587,8 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String
/// Gets information about a channel.
///
/// See |nvim_list_uis()| for an example of how to get channel info.
///
/// @param chan channel_id, or 0 for current channel
/// @returns Channel info dict with these keys:
/// - "id" Channel id.
@ -1604,8 +1606,8 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String
/// "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
/// for conpty on Windows).
/// - "buffer" (optional) Buffer connected to |terminal| instance.
/// - "client" (optional) Info about the peer (client on the other end of the RPC channel),
/// which it provided via |nvim_set_client_info()|.
/// - "client" (optional) Info about the peer (client on the other end of the channel), as set
/// by |nvim_set_client_info()|.
///
Dict nvim_get_chan_info(uint64_t channel_id, Integer chan, Arena *arena, Error *err)
FUNC_API_SINCE(4)
@ -1702,6 +1704,14 @@ Dict nvim__stats(Arena *arena)
/// Gets a list of dictionaries representing attached UIs.
///
/// Example: The Nvim builtin |TUI| sets its channel info as described in |startup-tui|. In
/// particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by
/// inspecting the client name of each UI:
///
/// ```lua
/// vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
/// ```
///
/// @return Array of UI dictionaries, each with these keys:
/// - "height" Requested height of the UI
/// - "width" Requested width of the UI

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

@ -340,9 +340,6 @@ describe('vim.fs', function()
end)
describe('normalize()', function()
-- local function vim.fs.normalize(path, opts)
-- return exec_lua([[return vim.fs.vim.fs.normalize(...)]], path, opts)
-- end
it('removes trailing /', function()
eq('/home/user', vim.fs.normalize('/home/user/'))
end)
@ -389,7 +386,7 @@ describe('vim.fs', function()
eq('D:foo/test', vim.fs.normalize('d:foo/test/', win_opts))
end)
it('does not change case on paths, see #31833', function()
it('always treats paths as case-sensitive #31833', function()
eq('TEST', vim.fs.normalize('TEST', win_opts))
eq('test', vim.fs.normalize('test', win_opts))
eq('C:/FOO/test', vim.fs.normalize('C:/FOO/test', win_opts))

0
test/functional/func/memoize_spec.lua → test/functional/lua/func_memoize_spec.lua
View File

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

@ -3435,7 +3435,6 @@ stack traceback:
end)
it('can discard input', function()
clear()
-- discard every other normal 'x' command
exec_lua [[
n_key = 0
@ -3461,7 +3460,6 @@ stack traceback:
end)
it('callback invalid return', function()
clear()
-- second key produces an error which removes the callback
exec_lua [[
n_call = 0