mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-05-24 13:50:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

build(docs): lint more quasi-keysets #39654

Browse Source 
Problem:
Linter missed backtick and double-quote keynames in the quasi-keyset of
the `nvim_create_user_command` docstring.

Solution:
Update the linter to check backtick-surrounded and quote-surrounded key
names.
This commit is contained in:
Justin M. Keyes
2026-05-07 12:00:26 -04:00
committed by GitHub
parent 3639f7a867
commit b351024daf
16 changed files with 173 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
runtime/doc/api.txt
View File

@@ -1438,26 +1438,26 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
field of |nvim_get_chan_info()|.
• {version} (`table<string,any>`) Dict describing the version, with
these (optional) keys:
• "commit" hash or similar identifier of commit
• "major" major version (defaults to 0 if not set, for
no release yet)
• "minor" minor version
• "patch" patch number
• "prerelease" string describing a prerelease, like
"dev" or "beta1"
• "commit" hash or similar identifier of commit
• {type} (`string`) Must be one of the following values. Client
libraries should default to "remote" unless overridden
by the user.
• "remote" remote client connected "Nvim flavored"
MessagePack-RPC (responses must be in reverse order of
requests). |msgpack-rpc|
• "msgpack-rpc" remote client connected to Nvim via
fully MessagePack-RPC compliant protocol.
• "ui" gui frontend
• "embedder" application using Nvim as a component (for
example, IDE/editor implementing a vim mode).
• "host" plugin host, typically started by nvim
• "msgpack-rpc" remote client connected to Nvim via
fully MessagePack-RPC compliant protocol.
• "plugin" single plugin, started by nvim
• "remote" remote client connected "Nvim flavored"
MessagePack-RPC (responses must be in reverse order of
requests). |msgpack-rpc|
• "ui" gui frontend
• {methods} (`table<string,any>`) Builtin methods in the client. For
a host, this does not include plugin methods which will
be discovered later. The key should be the method name,
@@ -1472,13 +1472,13 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
inclusive.
• {attributes} (`table<string,any>`) Arbitrary string:string map of
informal client properties. Suggested keys:
• "pid": Process id.
• "website": Client homepage URL (e.g. GitHub
repository)
• "license": License description ("Apache 2", "GPLv3",
"MIT", …)
• "logo": URI or path to image, preferably small logo or
icon. .png or .svg format is preferred.
• "pid": Process id.
• "website": Client homepage URL (e.g. GitHub
repository)
nvim_set_current_buf({buf}) *nvim_set_current_buf()*
Sets the current window's buffer to `buf`.
@@ -1651,9 +1651,9 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()*
• {opts} (`vim.api.keyset.keymap`) Optional parameters map: Accepts all
|:map-arguments| as keys except <buffer>, values are booleans
(default false). Also:
• "noremap" disables |recursive_mapping|, like |:noremap|
• "desc" human-readable description.
• "callback" Lua function called in place of {rhs}.
• "desc" human-readable description.
• "noremap" disables |recursive_mapping|, like |:noremap|
• "replace_keycodes" (boolean) When "expr" is true, replace
keycodes in the resulting string (see
|nvim_replace_termcodes()|). Returning nil from the Lua
@@ -1984,17 +1984,18 @@ nvim_parse_expression({expr}, {flags}, {hl}) *nvim_parse_expression()*
• {expr} (`string`) Expression to parse. Always treated as a single
line.
• {flags} (`string`) Flags:
• "m" if multiple expressions in a row are allowed (only the
first one will be parsed),
• "E" if EOC tokens are not allowed (determines whether they
will stop parsing process or be recognized as an
operator/space, though also yielding an error).
• "l" when needing to start parsing with lvalues for ":let"
or ":for". Common flag sets:
• "m" to parse like for `":echo"`.
• "E" to parse like for `"<C-r>="`.
• empty string for ":call".
• "lm" to parse for ":let".
or ":for".
• "m" if multiple expressions in a row are allowed (only the
first one will be parsed),
• Common flag sets:
• "E" to parse like for `"<C-r>="`.
• "lm" to parse for ":let".
• "m" to parse like for `":echo"`.
• empty string for ":call".
• {hl} (`boolean`) If true, return value will also include
"highlight" key containing array of 4-tuples (arrays)
(Integer, Integer, Integer, String), where first three
@@ -2144,15 +2145,15 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
triggered. Lua callback can return |lua-truthy| to delete
the autocommand. Callback receives one argument, a table
with keys: *event-args*
• id: (`number`) Autocommand id
• event: (`vim.api.keyset.events`) Name of the triggered
event |autocmd-events|
• group: (`number?`) Group id, if any
• file: (`string`) <afile> (not expanded to a full path)
• match: (`string`) <amatch> (expanded to a full path)
• buf: (`number`) <abuf>
• data: (`any`) Arbitrary data passed from
|nvim_exec_autocmds()| *event-data*
• event: (`vim.api.keyset.events`) Name of the triggered
event |autocmd-events|
• file: (`string`) <afile> (not expanded to a full path)
• group: (`number?`) Group id, if any
• id: (`number`) Autocommand id
• match: (`string`) <amatch> (expanded to a full path)
• command (string?) Vim command executed on event. Not
allowed with {callback}.
• desc (`string?`) Description (for documentation and
@@ -2927,45 +2928,43 @@ nvim_create_user_command({name}, {cmd}, {opts})
Since: 0.7.0
Parameters: ~
• {name} (`string`) Name of the new user command. Must begin with an
uppercase letter.
• {name} (`string`) Command name. First char must be uppercase.
• {cmd} (`string|fun(args: vim.api.keyset.create_user_command.command_args)`)
Replacement command to execute when this user command is
executed. When called from Lua, the command can also be a Lua
function. The function is called with a single table argument
that contains the following keys:
• args: (string) The args passed to the command, if any <args>
• bang: (boolean) "true" if the command was executed with a !
modifier <bang>
• count: (number) Any count supplied <count>
• fargs: (table) The args split by unescaped whitespace (when
more than one argument is allowed), if any <f-args>
• line1: (number) The starting line of the command range
<line1>
• line2: (number) The final line of the command range <line2>
• mods: (string) Command modifiers, if any <mods>
• name: (string) Command name
• nargs: (string) Number of arguments allowed for the command
• range: (number) The number of items in the command range: 0,
1, or 2 <range>
• reg: (string) The optional register, if specified <reg>
• smods: (table) Command modifiers in a structured format. Has
the same structure as the "mods" key of |nvim_parse_cmd()|.
• {opts} (`vim.api.keyset.user_command`) Optional flags
• `desc` (string) Command description.
• `force` (boolean, default true) Override any previous
definition.
• `complete` |:command-complete| command or function like
|:command-completion-customlist|.
• `nargs` Number of arguments allowed for the command
Command or Lua function, executed when the command is invoked.
Lua function receives a table with keys:
• args: (string) Args passed to the command, if any. <args>
• bang: (boolean) true if the command was executed with "!".
<bang>
• count: (number) Count, if any. <count>
• fargs: (table) Args split by unescaped whitespace (when more
than one arg is allowed), if any. <f-args>
• line1: (number) Start of the command range. <line1>
• line2: (number) End of the command range. <line2>
• mods: (string) Command modifiers (unstructured string), if
any. <mods>
• name: (string) Command name.
• nargs: (string) Number of arguments allowed by the command.
|:command-nargs|
• `preview` (function) Preview handler for 'inccommand'
• range: (number) Number of items in the command range: 0, 1,
or 2. <range>
• reg: (string) Register name, if any. <reg>
• smods: (table) Command modifiers (structured), same as
"mods" in |nvim_parse_cmd()|.
• {opts} (`vim.api.keyset.user_command`) Optional flags:
• `addr` |:command-addr|
• `complete` |:command-complete| command or function
|:command-completion-customlist|.
• `count` |:command-count|
• `desc` (string) Command description.
• `force` (boolean, default true) Override the existing
definition, if any.
• `nargs` Number of arguments allowed by the command.
|:command-nargs|
• `preview` (function) Preview handler for 'inccommand'.
|:command-preview|
• `range` see |:command-range|
• `count` see |:command-count|
• `addr` see |:command-addr|
• Set boolean |command-attributes| such as |:command-bang| or
|:command-bar| to true (but not |:command-buffer|, use
• `range` |:command-range|
• boolean |command-attributes| such as |:command-bang| or
|:command-bar| (but not |:command-buffer|, use
|nvim_buf_create_user_command()| instead).
nvim_del_user_command({name}) *nvim_del_user_command()*

2
runtime/doc/autocmd.txt
View File

@@ -1151,7 +1151,7 @@ TabClosed After closing a tabpage. <afile> expands to
the closing |tabpage-number|.
*TabClosedPre*
TabClosedPre Before closing a tabpage. The current tabpage
TabClosedPre Before closing a tabpage. The current tabpage
(|tabpagenr()|) is the one being closed. The
window layout is locked, thus opening and
closing of windows is prohibited.

2
runtime/doc/lsp.txt
View File

@@ -2074,10 +2074,10 @@ Client:stop({force}) *Client:stop()*
Parameters: ~
• {force} (`integer|boolean?`) (default: `self.exit_timeout`) Decides
whether to force-stop the server.
• `false`: Do not force-stop after "shutdown" request.
• `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()*

4
runtime/doc/lua.txt
View File

@@ -2108,8 +2108,8 @@ vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()*
• {behavior} (`'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any`)
Decides what to do if a key is found in more than one map:
• "error": raise an error
• "keep": use value from the leftmost map
• "force": use value from the rightmost map
• "keep": use value from the leftmost map
• If a function, it receives the current key, the previous
value in the currently merged table (if present), the
current value and should return the value for the given
@@ -2129,8 +2129,8 @@ vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()*
• {behavior} (`'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any`)
Decides what to do if a key is found in more than one map:
• "error": raise an error
• "keep": use value from the leftmost map
• "force": use value from the rightmost map
• "keep": use value from the leftmost map
• If a function, it receives the current key, the previous
value in the currently merged table (if present), the
current value and should return the value for the given

2
runtime/doc/news.txt
View File

@@ -241,7 +241,7 @@ VIMSCRIPT
• |v:exitreason| is set before |QuitPre|.
• |v:starttime| is the process start time (nanoseconds since UNIX epoch).
• |v:useractive| timestamp of the most recent user activity.
• |v:useractive| indicates user activity.
• |serverlist()| with `info=true` returns details for each server (own + peers).
==============================================================================

7
runtime/doc/vvars.txt
View File

@@ -756,9 +756,10 @@ v:true
*v:useractive* *useractive-variable*
v:useractive
Timestamp indicating the most recent user activity.
Updated every time a key is received from a UI
(TUI keystrokes or RPC |nvim_input()|).
Timestamp (nanoseconds since UNIX epoch) indicating the most
recent user activity, i.e. when a key is received from a UI
(TUI input or |nvim_input()|).
Initialized to 0 (no user activity since startup).
Read-only.

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

@@ -660,8 +660,8 @@ end
---
---@param behavior 'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any Decides what to do if a key is found in more than one map:
--- - "error": raise an error
--- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost map
--- - "keep": use value from the leftmost map
--- - If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should
--- return the value for the given key in the merged table.
---@param ... table Two or more tables
@@ -693,8 +693,8 @@ end
---@generic T2: table
---@param behavior 'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any Decides what to do if a key is found in more than one map:
--- - "error": raise an error
--- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost map
--- - "keep": use value from the leftmost map
--- - If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should
--- return the value for the given key in the merged table.
---@param ... T2 Two or more tables

82
runtime/lua/vim/_meta/api.gen.lua generated
View File

@@ -982,13 +982,13 @@ function vim.api.nvim_create_augroup(name, opts) end
--- - callback (`function|string?`) Lua function (or Vimscript function name, if string)
--- called when the event(s) is triggered. Lua callback can return `lua-truthy` to delete
--- the autocommand. Callback receives one argument, a table with keys: [event-args]()
--- - id: (`number`) Autocommand id
--- - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events`
--- - group: (`number?`) Group id, if any
--- - file: (`string`) [<afile>] (not expanded to a full path)
--- - match: (`string`) [<amatch>] (expanded to a full path)
--- - buf: (`number`) [<abuf>]
--- - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
--- - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events`
--- - file: (`string`) [<afile>] (not expanded to a full path)
--- - group: (`number?`) Group id, if any
--- - id: (`number`) Autocommand id
--- - match: (`string`) [<amatch>] (expanded to a full path)
--- - command (string?) Vim command executed on event. Not allowed with {callback}.
--- - desc (`string?`) Description (for documentation and troubleshooting).
--- - group (`string|integer?`) Group name or id to match against.
@@ -1033,35 +1033,33 @@ function vim.api.nvim_create_namespace(name) end
--- Hello world!
--- ```
---
--- @param name string Name of the new user command. Must begin with an uppercase letter.
--- @param cmd string|fun(args: vim.api.keyset.create_user_command.command_args) Replacement command to execute when this user command is executed. When called
--- from Lua, the command can also be a Lua function. The function is called with a
--- single table argument that contains the following keys:
--- - args: (string) The args passed to the command, if any [<args>]
--- - bang: (boolean) "true" if the command was executed with a ! modifier [<bang>]
--- - count: (number) Any count supplied [<count>]
--- - fargs: (table) The args split by unescaped whitespace (when more than one
--- argument is allowed), if any [<f-args>]
--- - line1: (number) The starting line of the command range [<line1>]
--- - line2: (number) The final line of the command range [<line2>]
--- - mods: (string) Command modifiers, if any [<mods>]
--- - name: (string) Command name
--- - nargs: (string) Number of arguments allowed for the command
--- - range: (number) The number of items in the command range: 0, 1, or 2 [<range>]
--- - reg: (string) The optional register, if specified [<reg>]
--- - smods: (table) Command modifiers in a structured format. Has the same
--- structure as the "mods" key of `nvim_parse_cmd()`.
--- @param opts vim.api.keyset.user_command Optional flags
--- @param name string Command name. First char must be uppercase.
--- @param cmd string|fun(args: vim.api.keyset.create_user_command.command_args) Command or Lua function, executed when the command is invoked. Lua function
--- receives a table with keys:
--- - args: (string) Args passed to the command, if any. [<args>]
--- - bang: (boolean) true if the command was executed with "!". [<bang>]
--- - count: (number) Count, if any. [<count>]
--- - fargs: (table) Args split by unescaped whitespace (when more than one arg is
--- allowed), if any. [<f-args>]
--- - line1: (number) Start of the command range. [<line1>]
--- - line2: (number) End of the command range. [<line2>]
--- - mods: (string) Command modifiers (unstructured string), if any. [<mods>]
--- - name: (string) Command name.
--- - nargs: (string) Number of arguments allowed by the command. `:command-nargs`
--- - range: (number) Number of items in the command range: 0, 1, or 2. [<range>]
--- - reg: (string) Register name, if any. [<reg>]
--- - smods: (table) Command modifiers (structured), same as "mods" in `nvim_parse_cmd()`.
--- @param opts vim.api.keyset.user_command Optional flags:
--- - `addr` `:command-addr`
--- - `complete` `:command-complete` command or function `:command-completion-customlist`.
--- - `count` `:command-count`
--- - `desc` (string) Command description.
--- - `force` (boolean, default true) Override any previous definition.
--- - `complete` `:command-complete` command or function like `:command-completion-customlist`.
--- - `nargs` Number of arguments allowed for the command `:command-nargs`
--- - `preview` (function) Preview handler for 'inccommand' `:command-preview`
--- - `range` see `:command-range`
--- - `count` see `:command-count`
--- - `addr` see `:command-addr`
--- - Set boolean `command-attributes` such as `:command-bang` or `:command-bar` to
--- true (but not `:command-buffer`, use `nvim_buf_create_user_command()` instead).
--- - `force` (boolean, default true) Override the existing definition, if any.
--- - `nargs` Number of arguments allowed by the command. `:command-nargs`
--- - `preview` (function) Preview handler for 'inccommand'. `:command-preview`
--- - `range` `:command-range`
--- - boolean `command-attributes` such as `:command-bang` or `:command-bar` (but
--- not `:command-buffer`, use `nvim_buf_create_user_command()` instead).
function vim.api.nvim_create_user_command(name, cmd, opts) end
--- Delete an autocommand group by id.
@@ -1965,18 +1963,18 @@ function vim.api.nvim_parse_cmd(str, opts) end
---
--- @param expr string Expression to parse. Always treated as a single line.
--- @param flags string Flags:
--- - "m" if multiple expressions in a row are allowed (only
--- the first one will be parsed),
--- - "E" if EOC tokens are not allowed (determines whether
--- they will stop parsing process or be recognized as an
--- operator/space, though also yielding an error).
--- - "l" when needing to start parsing with lvalues for
--- ":let" or ":for".
--- Common flag sets:
--- - "m" to parse like for `":echo"`.
--- - "E" to parse like for `"<C-r>="`.
--- - empty string for ":call".
--- - "lm" to parse for ":let".
--- - "m" if multiple expressions in a row are allowed (only
--- the first one will be parsed),
--- - Common flag sets:
--- - "E" to parse like for `"<C-r>="`.
--- - "lm" to parse for ":let".
--- - "m" to parse like for `":echo"`.
--- - empty string for ":call".
--- @param hl boolean If true, return value will also include "highlight"
--- key containing array of 4-tuples (arrays) (Integer,
--- Integer, Integer, String), where first three numbers
@@ -2305,9 +2303,9 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
--- @param rhs string Right-hand-side `{rhs}` of the mapping.
--- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys except [<buffer>],
--- values are booleans (default false). Also:
--- - "noremap" disables `recursive_mapping`, like `:noremap`
--- - "desc" human-readable description.
--- - "callback" Lua function called in place of {rhs}.
--- - "desc" human-readable description.
--- - "noremap" disables `recursive_mapping`, like `:noremap`
--- - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
--- resulting string (see `nvim_replace_termcodes()`). Returning nil from the Lua
--- "callback" is equivalent to returning an empty string.

7
runtime/lua/vim/_meta/vvars.gen.lua generated
View File

@@ -805,9 +805,10 @@ vim.v.throwpoint = ...
--- @type boolean
vim.v['true'] = ...
--- Timestamp indicating the most recent user activity.
--- Updated every time a key is received from a UI
--- (TUI keystrokes or RPC `nvim_input()`).
--- Timestamp (nanoseconds since UNIX epoch) indicating the most
--- recent user activity, i.e. when a key is received from a UI
--- (TUI input or `nvim_input()`).
---
--- Initialized to 0 (no user activity since startup).
--- Read-only.
--- @type integer

2
runtime/lua/vim/lsp/client.lua
View File

@@ -892,9 +892,9 @@ end
--- file corruption.
---
--- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server.
--- - `false`: Do not force-stop after "shutdown" request.
--- - `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)

8
src/gen/lint.lua
View File

@@ -274,10 +274,12 @@ function M.lint_quasi_keysets(source, funs)
for _, p in ipairs(fun.params or {}) do
if p.desc then
local prev = nil --- @type string?
for name in p.desc:gmatch('\n%- ([%w_]+)') do
-- Capture the keyname with optional punctuation (`, "), so the sort includes surrounding
-- chars: backtick items group together, double-quote group together, etc. (Example: |Client:stop()|)
for name in p.desc:gmatch('\n%- (["`]?[%w_]+["`]?)') do
-- Sort underscore-prefixed keys (e.g. "_cmdline_offset") at the end.
local prev_key = prev and prev:gsub('^_', '~') or nil
local name_key = name:gsub('^_', '~')
local prev_key = prev and prev:gsub('^([`"]?)_', '%1~') or nil
local name_key = name:gsub('^([`"]?)_', '%1~')
if prev_key and name_key < prev_key then
errors[#errors + 1] = fmt(
'%s: %s(): param "%s": key "%s" should come before "%s" (sort alphabetically)',

10
src/nvim/api/autocmd.c
View File

@@ -370,13 +370,13 @@ cleanup:
/// - callback (`function|string?`) Lua function (or Vimscript function name, if string)
/// called when the event(s) is triggered. Lua callback can return |lua-truthy| to delete
/// the autocommand. Callback receives one argument, a table with keys: [event-args]()
/// - id: (`number`) Autocommand id
/// - event: (`vim.api.keyset.events`) Name of the triggered event |autocmd-events|
/// - group: (`number?`) Group id, if any
/// - file: (`string`) [<afile>] (not expanded to a full path)
/// - match: (`string`) [<amatch>] (expanded to a full path)
/// - buf: (`number`) [<abuf>]
/// - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
/// - event: (`vim.api.keyset.events`) Name of the triggered event |autocmd-events|
/// - file: (`string`) [<afile>] (not expanded to a full path)
/// - group: (`number?`) Group id, if any
/// - id: (`number`) Autocommand id
/// - match: (`string`) [<amatch>] (expanded to a full path)
/// - command (string?) Vim command executed on event. Not allowed with {callback}.
/// - desc (`string?`) Description (for documentation and troubleshooting).
/// - group (`string|integer?`) Group name or id to match against.

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

@@ -977,35 +977,33 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// Hello world!
/// ```
///
/// @param name Name of the new user command. Must begin with an uppercase letter.
/// @param cmd Replacement command to execute when this user command is executed. When called
/// from Lua, the command can also be a Lua function. The function is called with a
/// single table argument that contains the following keys:
/// - args: (string) The args passed to the command, if any [<args>]
/// - bang: (boolean) "true" if the command was executed with a ! modifier [<bang>]
/// - count: (number) Any count supplied [<count>]
/// - fargs: (table) The args split by unescaped whitespace (when more than one
/// argument is allowed), if any [<f-args>]
/// - line1: (number) The starting line of the command range [<line1>]
/// - line2: (number) The final line of the command range [<line2>]
/// - mods: (string) Command modifiers, if any [<mods>]
/// - name: (string) Command name
/// - nargs: (string) Number of arguments allowed for the command
/// - range: (number) The number of items in the command range: 0, 1, or 2 [<range>]
/// - reg: (string) The optional register, if specified [<reg>]
/// - smods: (table) Command modifiers in a structured format. Has the same
/// structure as the "mods" key of |nvim_parse_cmd()|.
/// @param opts Optional flags
/// @param name Command name. First char must be uppercase.
/// @param cmd Command or Lua function, executed when the command is invoked. Lua function
/// receives a table with keys:
/// - args: (string) Args passed to the command, if any. [<args>]
/// - bang: (boolean) true if the command was executed with "!". [<bang>]
/// - count: (number) Count, if any. [<count>]
/// - fargs: (table) Args split by unescaped whitespace (when more than one arg is
/// allowed), if any. [<f-args>]
/// - line1: (number) Start of the command range. [<line1>]
/// - line2: (number) End of the command range. [<line2>]
/// - mods: (string) Command modifiers (unstructured string), if any. [<mods>]
/// - name: (string) Command name.
/// - nargs: (string) Number of arguments allowed by the command. |:command-nargs|
/// - range: (number) Number of items in the command range: 0, 1, or 2. [<range>]
/// - reg: (string) Register name, if any. [<reg>]
/// - smods: (table) Command modifiers (structured), same as "mods" in |nvim_parse_cmd()|.
/// @param opts Optional flags:
/// - `addr` |:command-addr|
/// - `complete` |:command-complete| command or function |:command-completion-customlist|.
/// - `count` |:command-count|
/// - `desc` (string) Command description.
/// - `force` (boolean, default true) Override any previous definition.
/// - `complete` |:command-complete| command or function like |:command-completion-customlist|.
/// - `nargs` Number of arguments allowed for the command |:command-nargs|
/// - `preview` (function) Preview handler for 'inccommand' |:command-preview|
/// - `range` see |:command-range|
/// - `count` see |:command-count|
/// - `addr` see |:command-addr|
/// - Set boolean |command-attributes| such as |:command-bang| or |:command-bar| to
/// true (but not |:command-buffer|, use |nvim_buf_create_user_command()| instead).
/// - `force` (boolean, default true) Override the existing definition, if any.
/// - `nargs` Number of arguments allowed by the command. |:command-nargs|
/// - `preview` (function) Preview handler for 'inccommand'. |:command-preview|
/// - `range` |:command-range|
/// - boolean |command-attributes| such as |:command-bang| or |:command-bar| (but
/// not |:command-buffer|, use |nvim_buf_create_user_command()| instead).
/// @param[out] err Error details, if any.
void nvim_create_user_command(uint64_t channel_id,
String name,

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

@@ -1630,9 +1630,9 @@ ArrayOf(DictAs(get_keymap)) nvim_get_keymap(String mode, Arena *arena)
/// @param rhs Right-hand-side |{rhs}| of the mapping.
/// @param opts Optional parameters map: Accepts all |:map-arguments| as keys except [<buffer>],
/// values are booleans (default false). Also:
/// - "noremap" disables |recursive_mapping|, like |:noremap|
/// - "desc" human-readable description.
/// - "callback" Lua function called in place of {rhs}.
/// - "desc" human-readable description.
/// - "noremap" disables |recursive_mapping|, like |:noremap|
/// - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
/// resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua
/// "callback" is equivalent to returning an empty string.
@@ -1685,22 +1685,22 @@ ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena)
/// @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:
/// - "commit" hash or similar identifier of commit
/// - "major" major version (defaults to 0 if not set, for no release yet)
/// - "minor" minor version
/// - "patch" patch number
/// - "prerelease" string describing a prerelease, like "dev" or "beta1"
/// - "commit" hash or similar identifier of commit
/// @param type Must be one of the following values. Client libraries should
/// default to "remote" unless overridden by the user.
/// - "remote" remote client connected "Nvim flavored" MessagePack-RPC (responses
/// must be in reverse order of requests). |msgpack-rpc|
/// - "msgpack-rpc" remote client connected to Nvim via fully MessagePack-RPC
/// compliant protocol.
/// - "ui" gui frontend
/// - "embedder" application using Nvim as a component (for example,
/// IDE/editor implementing a vim mode).
/// - "host" plugin host, typically started by nvim
/// - "msgpack-rpc" remote client connected to Nvim via fully MessagePack-RPC
/// compliant protocol.
/// - "plugin" single plugin, started by nvim
/// - "remote" remote client connected "Nvim flavored" MessagePack-RPC (responses
/// must be in reverse order of requests). |msgpack-rpc|
/// - "ui" gui frontend
/// @param methods Builtin methods in the client. For a host, this does not
/// include plugin methods which will be discovered later.
/// The key should be the method name, the values are dicts with
@@ -1715,11 +1715,11 @@ ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena)
///
/// @param attributes Arbitrary string:string map of informal client properties.
/// Suggested keys:
/// - "pid": Process id.
/// - "website": Client homepage URL (e.g. GitHub repository)
/// - "license": License description ("Apache 2", "GPLv3", "MIT", …)
/// - "logo": URI or path to image, preferably small logo or icon.
/// .png or .svg format is preferred.
/// - "pid": Process id.
/// - "website": Client homepage URL (e.g. GitHub repository)
///
/// @param[out] err Error details, if any
void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String type, Dict methods,

14
src/nvim/api/vimscript.c
View File

@@ -357,18 +357,18 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
///
/// @param[in] expr Expression to parse. Always treated as a single line.
/// @param[in] flags Flags:
/// - "m" if multiple expressions in a row are allowed (only
/// the first one will be parsed),
/// - "E" if EOC tokens are not allowed (determines whether
/// they will stop parsing process or be recognized as an
/// operator/space, though also yielding an error).
/// - "l" when needing to start parsing with lvalues for
/// ":let" or ":for".
/// Common flag sets:
/// - "m" to parse like for `":echo"`.
/// - "E" to parse like for `"<C-r>="`.
/// - empty string for ":call".
/// - "lm" to parse for ":let".
/// - "m" if multiple expressions in a row are allowed (only
/// the first one will be parsed),
/// - Common flag sets:
/// - "E" to parse like for `"<C-r>="`.
/// - "lm" to parse for ":let".
/// - "m" to parse like for `":echo"`.
/// - empty string for ":call".
/// @param[in] hl If true, return value will also include "highlight"
/// key containing array of 4-tuples (arrays) (Integer,
/// Integer, Integer, String), where first three numbers

7
src/nvim/vvars.lua
View File

@@ -450,9 +450,10 @@ M.vars = {
useractive = {
type = 'integer',
desc = [=[
Timestamp indicating the most recent user activity.
Updated every time a key is received from a UI
(TUI keystrokes or RPC |nvim_input()|).
Timestamp (nanoseconds since UNIX epoch) indicating the most
recent user activity, i.e. when a key is received from a UI
(TUI input or |nvim_input()|).
Initialized to 0 (no user activity since startup).
Read-only.
]=],