mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-08-27 01:21:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #38268 docs: misc

Browse Source
This commit is contained in:
Justin M. Keyes
2026-03-13 15:37:12 -04:00
committed by GitHub
parent 911337eb3c 017d8aa298
commit 8499af1119
22 changed files with 112 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
runtime/doc/api.txt
View File

@@ -2837,19 +2837,21 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
(`vim.api.keyset.command_info`) Map of maps describing commands.
nvim_cmd({cmd}, {opts}) *nvim_cmd()*
Executes an Ex command.
Executes an Ex command `cmd`, specified as a Dict with the same structure
as returned by |nvim_parse_cmd()|.
Unlike |nvim_command()| this command takes a structured Dict instead of a
String. This allows for easier construction and manipulation of an Ex
command. This also allows for things such as having spaces inside a
command argument, expanding filenames in a command that otherwise doesn't
expand filenames, etc. Command arguments may also be Number, Boolean or
String.
The first argument may also be used instead of count for commands that
support it in order to make their usage simpler with |vim.cmd()|. For
example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do
`vim.cmd.bdelete(2)`.
Use `magic={…=false}` to disable special chars: >lua
vim.api.nvim_cmd({
cmd = 'edit',
args = { '%foo"|bar#baz"' },
magic = { file = false, bar = false }
},
{}
)
<
• See |nvim_parse_cmd()| to parse a cmdline string (which can then be
passed to `nvim_cmd`).
• See |nvim_command()| to execute a cmdline string.
On execution error: fails with Vimscript error, updates v:errmsg.
@@ -2857,11 +2859,10 @@ nvim_cmd({cmd}, {opts}) *nvim_cmd()*
Since: 0.8.0
Parameters: ~
• {cmd} (`vim.api.keyset.cmd`) Command to execute. Must be a Dict that
can contain the same values as the return value of
|nvim_parse_cmd()| except "addr", "nargs" and "nextcmd" which
are ignored if provided. All values except for "cmd" are
optional.
• {cmd} (`vim.api.keyset.cmd`) Command to execute, a Dict with the
same structure as the return value of |nvim_parse_cmd()|
(except "addr", "nargs" and "nextcmd" are ignored). All keys
except "cmd" are optional.
• {opts} (`vim.api.keyset.cmd_opts`) Optional parameters.
• output: (boolean, default false) Whether to return command
output.
@@ -2871,8 +2872,9 @@ nvim_cmd({cmd}, {opts}) *nvim_cmd()*
true, else empty string.
See also: ~
• |nvim_exec2()|
• |nvim_command()|
• |nvim_exec2()|
• |nvim_parse_cmd()|
*nvim_create_user_command()*
nvim_create_user_command({name}, {command}, {opts})

3
runtime/doc/lua.txt
View File

@@ -1261,6 +1261,9 @@ vim.cmd({command}) *vim.cmd()*
-- Ex command :vertical resize +2
vim.cmd.resize({ '+2', mods = { vertical = true } })
-- Pass arg literally, without needing to escape special chars:
vim.cmd.edit({ '%foo"|bar#baz"', magic = { file = false, bar = false } })
<
Parameters: ~

12
runtime/doc/vimfn.txt
View File

@@ -1551,6 +1551,8 @@ deepcopy({expr} [, {noref}]) *deepcopy()* *E69
(`T`)
delete({fname} [, {flags}]) *delete()*
Lua: see |vim.fs.rm()|.
Without {flags} or with {flags} empty: Deletes the file by the
name {fname}.
@@ -2093,7 +2095,7 @@ expand({string} [, {nosuf} [, {list}]]) *expand()*
current script ID |<SID>|
<script> Sourced script file, or script file
where the current function was defined.
For Lua see |lua-script-location|.
Lua: see |lua-script-location|.
<stack> Call stack
<cword> Word under the cursor
<cWORD> WORD under the cursor
@@ -5458,7 +5460,7 @@ jobresize({job}, {width}, {height}) *jobresize()*
(`any`)
jobstart({cmd} [, {opts}]) *jobstart()*
Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`).
Spawns {cmd} as a job.
If {cmd} is a List it runs directly (no 'shell').
@@ -11144,7 +11146,7 @@ synstack({lnum}, {col}) *synstack()*
(`integer[]`)
system({cmd} [, {input}]) *system()* *E677*
Note: Prefer |vim.system()| in Lua.
Lua: Prefer |vim.system()|.
Gets the output of {cmd} as a |string| (|systemlist()| returns
a |List|) and sets |v:shell_error| to the error code.
@@ -11688,7 +11690,7 @@ undotree([{buf}]) *undotree()*
(`vim.fn.undotree.ret`)
uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
Note: Prefer |vim.list.unique()| in Lua.
Lua: Prefer |vim.list.unique()|.
Remove second and succeeding copies of repeated adjacent
{list} items in-place. Returns {list}. If you want a list
@@ -12146,7 +12148,7 @@ windowsversion() *windowsversion()*
is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For
non-MS-Windows systems the result is an empty string.
See also Lua |uv.os_uname()|.
Lua: see |uv.os_uname()|.
Return: ~
(`string`)

2
runtime/lua/nvim/tutor.lua
View File

@@ -57,7 +57,7 @@ function M.apply_marks()
vim.b.tutor_extmarks = {}
for expct, _ in pairs(vim.b.tutor_metadata.expect) do
---@diagnostic disable-next-line: assign-type-mismatch
local lnum = vim._ensure_integer(expct)
local lnum = vim._assert_integer(expct)
vim.api.nvim_buf_set_extmark(0, tutor_hl_ns, lnum - 1, 0, {
line_hl_group = 'tutorExpect',
invalidate = true,

6
runtime/lua/tohtml.lua
View File

@@ -228,7 +228,7 @@ local function cterm_to_hex(colorstr)
if colorstr:sub(1, 1) == '#' then
return colorstr
end
local color = vim._ensure_integer(colorstr)
local color = vim._assert_integer(colorstr)
assert(0 <= color and color <= 255)
if cterm_color_cache[color] then
return cterm_color_cache[color]
@@ -238,7 +238,7 @@ local function cterm_to_hex(colorstr)
cterm_color_cache[color] = hex
else
notify("Couldn't get terminal colors, using fallback")
local t_Co = vim._ensure_integer(vim.api.nvim_eval('&t_Co'))
local t_Co = vim._assert_integer(vim.api.nvim_eval('&t_Co'))
if t_Co <= 8 then
cterm_color_cache = cterm_8_to_hex
elseif t_Co == 88 then
@@ -782,7 +782,7 @@ local function styletable_statuscolumn(state)
end)
minwidth = minwidth + math.min(maxfold, max)
else
minwidth = minwidth + vim._ensure_integer(foldcolumn)
minwidth = minwidth + vim._assert_integer(foldcolumn)
end
end

2
runtime/lua/vim/_core/defaults.lua
View File

@@ -799,7 +799,7 @@ do
return nil
end
local max = vim._ensure_integer(string.rep('f', #c), 16)
local max = vim._assert_integer(string.rep('f', #c), 16)
return val / max
end

5
runtime/lua/vim/_core/editor.lua
View File

@@ -336,6 +336,9 @@ local VIM_CMD_ARG_MAX = 20
---
--- -- Ex command :vertical resize +2
--- vim.cmd.resize({ '+2', mods = { vertical = true } })
---
--- -- Pass arg literally, without needing to escape special chars:
--- vim.cmd.edit({ '%foo"|bar#baz"', magic = { file = false, bar = false } })
--- ```
---
---@diagnostic disable-next-line: undefined-doc-param
@@ -475,7 +478,7 @@ function vim.region(bufnr, pos1, pos2, regtype, inclusive)
local c2 --- @type number
if regtype:byte() == 22 then -- block selection: take width from regtype
c1 = pos1[2]
c2 = c1 + vim._ensure_integer(regtype:sub(2))
c2 = c1 + vim._assert_integer(regtype:sub(2))
-- and adjust for non-ASCII characters
local bufline = vim.api.nvim_buf_get_lines(bufnr, l, l + 1, true)[1]
local utflen = vim.str_utfindex(bufline, 'utf-32', #bufline)

2
runtime/lua/vim/_core/shared.lua
View File

@@ -1645,7 +1645,7 @@ end
--- @param x any Value to convert.
--- @param base? integer Numeric base passed to `tonumber()`.
--- @return integer integer Converted integer value.
function vim._ensure_integer(x, base)
function vim._assert_integer(x, base)
return vim._tointeger(x, base) or error(('Cannot convert %s to integer'):format(x))
end

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

@@ -853,25 +853,32 @@ function vim.api.nvim_chan_send(chan, data) end
--- - NOTE: If not passed, will only delete autocmds *not* in any group.
function vim.api.nvim_clear_autocmds(opts) end
--- Executes an Ex command.
--- Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by
--- `nvim_parse_cmd()`.
---
--- Unlike `nvim_command()` this command takes a structured Dict instead of a String. This
--- allows for easier construction and manipulation of an Ex command. This also allows for things
--- such as having spaces inside a command argument, expanding filenames in a command that otherwise
--- doesn't expand filenames, etc. Command arguments may also be Number, Boolean or String.
--- Use `magic={…=false}` to disable special chars:
--- ```lua
--- vim.api.nvim_cmd({
--- cmd = 'edit',
--- args = { '%foo"|bar#baz"' },
--- magic = { file = false, bar = false }
--- },
--- {}
--- )
--- ```
---
--- The first argument may also be used instead of count for commands that support it in order to
--- make their usage simpler with `vim.cmd()`. For example, instead of
--- `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`.
--- - See `nvim_parse_cmd()` to parse a cmdline string (which can then be passed to `nvim_cmd`).
--- - See `nvim_command()` to execute a cmdline string.
---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
---
--- @see vim.api.nvim_exec2
--- @see vim.api.nvim_command
--- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dict that can contain the same values as
--- the return value of `nvim_parse_cmd()` except "addr", "nargs" and "nextcmd"
--- which are ignored if provided. All values except for "cmd" are optional.
--- @see vim.api.nvim_exec2
--- @see vim.api.nvim_parse_cmd
--- @param cmd vim.api.keyset.cmd Command to execute, a Dict with the same structure as the return value of
--- `nvim_parse_cmd()` (except "addr", "nargs" and "nextcmd" are ignored).
--- All keys except "cmd" are optional.
--- @param opts vim.api.keyset.cmd_opts Optional parameters.
--- - output: (boolean, default false) Whether to return command output.
--- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string.

12
runtime/lua/vim/_meta/vimfn.lua generated
View File

@@ -1368,6 +1368,8 @@ function vim.fn.debugbreak(pid) end
--- @return T
function vim.fn.deepcopy(expr, noref) end
--- Lua: see |vim.fs.rm()|.
---
--- Without {flags} or with {flags} empty: Deletes the file by the
--- name {fname}.
---
@@ -1853,7 +1855,7 @@ function vim.fn.exp(expr) end
--- current script ID |<SID>|
--- <script> Sourced script file, or script file
--- where the current function was defined.
--- For Lua see |lua-script-location|.
--- Lua: see |lua-script-location|.
--- <stack> Call stack
--- <cword> Word under the cursor
--- <cWORD> WORD under the cursor
@@ -4949,7 +4951,7 @@ function vim.fn.jobresize(job, width, height) end
--- @return any
function vim.fn.jobsend(...) end
--- Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
--- Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`).
---
--- Spawns {cmd} as a job.
--- If {cmd} is a List it runs directly (no 'shell').
@@ -10164,7 +10166,7 @@ function vim.fn.synconcealed(lnum, col) end
--- @return integer[]
function vim.fn.synstack(lnum, col) end
--- Note: Prefer |vim.system()| in Lua.
--- Lua: Prefer |vim.system()|.
---
--- Gets the output of {cmd} as a |string| (|systemlist()| returns
--- a |List|) and sets |v:shell_error| to the error code.
@@ -10644,7 +10646,7 @@ function vim.fn.undofile(name) end
--- @return vim.fn.undotree.ret
function vim.fn.undotree(buf) end
--- Note: Prefer |vim.list.unique()| in Lua.
--- Lua: Prefer |vim.list.unique()|.
---
--- Remove second and succeeding copies of repeated adjacent
--- {list} items in-place. Returns {list}. If you want a list
@@ -11042,7 +11044,7 @@ function vim.fn.wincol() end
--- is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For
--- non-MS-Windows systems the result is an empty string.
---
--- See also Lua |uv.os_uname()|.
--- Lua: see |uv.os_uname()|.
---
--- @return string
function vim.fn.windowsversion() end

2
runtime/lua/vim/deprecated/health.lua
View File

@@ -14,7 +14,7 @@ function M.check()
local version, backtraces, alternative = v[1], v[2], v[3]
local major, minor = version:match('(%d+)%.(%d+)')
major, minor = vim._ensure_integer(major), vim._ensure_integer(minor)
major, minor = vim._assert_integer(major), vim._assert_integer(minor)
local removal_version = string.format('nvim-%d.%d', major, minor)
local will_be_removed = vim.fn.has(removal_version) == 1 and 'was removed' or 'will be removed'

2
runtime/lua/vim/diagnostic.lua
View File

@@ -2886,7 +2886,7 @@ function M.match(str, pat, groups, severity_map, defaults)
if field == 'severity' then
diagnostic[field] = severity_map[match]
elseif field == 'lnum' or field == 'end_lnum' or field == 'col' or field == 'end_col' then
diagnostic[field] = vim._ensure_integer(match) - 1
diagnostic[field] = vim._assert_integer(match) - 1
elseif field then
diagnostic[field] = match
end

2
runtime/lua/vim/func/_memoize.lua
View File

@@ -29,7 +29,7 @@ local function resolve_hash(hash)
else
local c = hash:match('^concat%-(%d+)')
if c then
hash = concat_hash(vim._ensure_integer(c))
hash = concat_hash(vim._assert_integer(c))
else
error('invalid value for hash: ' .. hash)
end

6
runtime/lua/vim/lsp/completion.lua
View File

@@ -327,9 +327,9 @@ local function generate_kind(item)
local hex = r
and string.format(
'%02x%02x%02x',
vim._ensure_integer(r),
vim._ensure_integer(g),
vim._ensure_integer(b)
vim._assert_integer(r),
vim._assert_integer(g),
vim._assert_integer(b)
)
or doc:match('#?([%da-fA-F]+)')

6
runtime/lua/vim/lsp/document_color.lua
View File

@@ -47,9 +47,9 @@ local function get_contrast_color(color)
if not (r_s and g_s and b_s) then
error('Invalid color format: ' .. color)
end
local r = vim._ensure_integer(r_s, 16)
local g = vim._ensure_integer(g_s, 16)
local b = vim._ensure_integer(b_s, 16)
local r = vim._assert_integer(r_s, 16)
local g = vim._assert_integer(g_s, 16)
local b = vim._assert_integer(b_s, 16)
-- Source: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
-- Using power 2.2 is a close approximation to full piecewise transform

4
runtime/lua/vim/lsp/rpc.lua
View File

@@ -57,7 +57,7 @@ local function get_content_length(header)
if c == 13 and header:byte(i + 1) == 10 then -- must end with \r\n
local value = buf:get()
if digit then
return vim._ensure_integer(value)
return vim._assert_integer(value)
end
error('value of Content-Length is not number: ' .. value)
else
@@ -432,7 +432,7 @@ function Client:handle_body(body)
)
then
-- We sent a number, so we expect a number.
local result_id = vim._ensure_integer(decoded.id)
local result_id = vim._assert_integer(decoded.id)
-- Notify the user that a response was received for the request
local notify_reply_callback = self.notify_reply_callbacks[result_id]

4
runtime/lua/vim/treesitter/_query_linter.lua
View File

@@ -86,8 +86,8 @@ local function get_error_entry(err, node)
local start_line, start_col = node:range()
local line_offset, col_offset, msg = err:gmatch('.-:%d+: Query error at (%d+):(%d+)%. ([^:]+)')() ---@type string, string, string
start_line, start_col =
start_line + vim._ensure_integer(line_offset) - 1,
start_col + vim._ensure_integer(col_offset) - 1
start_line + vim._assert_integer(line_offset) - 1,
start_col + vim._assert_integer(col_offset) - 1
local end_line, end_col = start_line, start_col
if msg:match('^Invalid syntax') or msg:match('^Impossible') then
-- Use the length of the underlined node

2
runtime/lua/vim/uri.lua
View File

@@ -25,7 +25,7 @@ local PATTERNS = {
---@param hex string
---@return string
local function hex_to_char(hex)
return schar(vim._ensure_integer(hex, 16))
return schar(vim._assert_integer(hex, 16))
end
---@param char string

6
runtime/lua/vim/version.lua
View File

@@ -201,9 +201,9 @@ function M._version(version, strict) -- Adapted from https://github.com/folke/la
or (major and minor and patch and major ~= '' and minor ~= '' and patch ~= '')
then
return setmetatable({
major = vim._ensure_integer(major),
minor = minor == '' and 0 or vim._ensure_integer(minor),
patch = patch == '' and 0 or vim._ensure_integer(patch),
major = vim._assert_integer(major),
minor = minor == '' and 0 or vim._assert_integer(minor),
patch = patch == '' and 0 or vim._assert_integer(patch),
prerelease = prerel ~= '' and prerel or nil,
build = build ~= '' and build or nil,
}, Version)

31
src/nvim/api/command.c
View File

@@ -319,25 +319,32 @@ end:
return result;
}
/// Executes an Ex command.
/// Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by
/// |nvim_parse_cmd()|.
///
/// Unlike |nvim_command()| this command takes a structured Dict instead of a String. This
/// allows for easier construction and manipulation of an Ex command. This also allows for things
/// such as having spaces inside a command argument, expanding filenames in a command that otherwise
/// doesn't expand filenames, etc. Command arguments may also be Number, Boolean or String.
/// Use `magic={…=false}` to disable special chars:
/// ```lua
/// vim.api.nvim_cmd({
/// cmd = 'edit',
/// args = { '%foo"|bar#baz"' },
/// magic = { file = false, bar = false }
/// },
/// {}
/// )
/// ```
///
/// The first argument may also be used instead of count for commands that support it in order to
/// make their usage simpler with |vim.cmd()|. For example, instead of
/// `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`.
/// - See |nvim_parse_cmd()| to parse a cmdline string (which can then be passed to `nvim_cmd`).
/// - See |nvim_command()| to execute a cmdline string.
///
/// On execution error: fails with Vimscript error, updates v:errmsg.
///
/// @see |nvim_exec2()|
/// @see |nvim_command()|
/// @see |nvim_exec2()|
/// @see |nvim_parse_cmd()|
///
/// @param cmd Command to execute. Must be a Dict that can contain the same values as
/// the return value of |nvim_parse_cmd()| except "addr", "nargs" and "nextcmd"
/// which are ignored if provided. All values except for "cmd" are optional.
/// @param cmd Command to execute, a Dict with the same structure as the return value of
/// |nvim_parse_cmd()| (except "addr", "nargs" and "nextcmd" are ignored).
/// All keys except "cmd" are optional.
/// @param opts Optional parameters.
/// - output: (boolean, default false) Whether to return command output.
/// @param[out] err Error details, if any.

12
src/nvim/eval.lua
View File

@@ -1806,6 +1806,8 @@ M.funcs = {
args = { 1, 2 },
base = 1,
desc = [=[
Lua: see |vim.fs.rm()|.
Without {flags} or with {flags} empty: Deletes the file by the
name {fname}.
@@ -2396,7 +2398,7 @@ M.funcs = {
current script ID |<SID>|
<script> Sourced script file, or script file
where the current function was defined.
For Lua see |lua-script-location|.
Lua: see |lua-script-location|.
<stack> Call stack
<cword> Word under the cursor
<cWORD> WORD under the cursor
@@ -6105,7 +6107,7 @@ M.funcs = {
jobstart = {
args = { 1, 2 },
desc = [=[
Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`).
Spawns {cmd} as a job.
If {cmd} is a List it runs directly (no 'shell').
@@ -12261,7 +12263,7 @@ M.funcs = {
base = 1,
tags = { 'E677' },
desc = [=[
Note: Prefer |vim.system()| in Lua.
Lua: Prefer |vim.system()|.
Gets the output of {cmd} as a |string| (|systemlist()| returns
a |List|) and sets |v:shell_error| to the error code.
@@ -12889,7 +12891,7 @@ M.funcs = {
base = 1,
tags = { 'E882' },
desc = [=[
Note: Prefer |vim.list.unique()| in Lua.
Lua: Prefer |vim.list.unique()|.
Remove second and succeeding copies of repeated adjacent
{list} items in-place. Returns {list}. If you want a list
@@ -13382,7 +13384,7 @@ M.funcs = {
is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For
non-MS-Windows systems the result is an empty string.
See also Lua |uv.os_uname()|.
Lua: see |uv.os_uname()|.
]=],
fast = true,
name = 'windowsversion',

6
test/functional/api/vim_spec.lua
View File

@@ -4979,7 +4979,7 @@ describe('API', function()
result = api.nvim_parse_cmd('copen 5', {})
eq(5, result.count)
end)
it('parses range-only command', function()
it('parses range-only cmdline (:1)', function()
insert [[
line1
line2
@@ -5033,7 +5033,7 @@ describe('API', function()
res = api.nvim_parse_cmd("'<,'>", {})
eq({ 1, 5 }, res.range)
end)
it('parses modifier-only command', function()
it('parses modifier-only cmdline (:aboveleft)', function()
local res = api.nvim_parse_cmd('aboveleft', {})
eq('', res.cmd)
eq('aboveleft', res.mods.split)
@@ -5270,7 +5270,7 @@ describe('API', function()
feed(':call<CR><CR>')
eq('E471: Argument required', api.nvim_cmd({ cmd = 'messages' }, { output = true }))
-- modifier only
-- "modifier-only" command (e.g. :noautocmd).
eq('', api.nvim_cmd({ cmd = '', mods = { noautocmd = true } }, {}))
end)