diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 7734cab633..ee896da84b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1927,348 +1927,256 @@ nvim_parse_expression({expr}, {flags}, {highlight}) ============================================================================== -Command Functions *api-command* +Autocmd Functions *api-autocmd* - *nvim_buf_create_user_command()* -nvim_buf_create_user_command({buffer}, {name}, {command}, {opts}) - Creates a buffer-local command |user-commands|. +nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* + Clears all autocommands selected by {opts}. To delete autocmds see + |nvim_del_autocmd()|. Attributes: ~ Since: 0.7.0 Parameters: ~ - • {buffer} (`integer`) Buffer id, or 0 for current buffer. - • {name} (`string`) - • {command} (`any`) - • {opts} (`vim.api.keyset.user_command`) + • {opts} (`vim.api.keyset.clear_autocmds`) Parameters + • event: (vim.api.keyset.events|vim.api.keyset.events[]) + Examples: + • event: "pat1" + • event: { "pat1" } + • event: { "pat1", "pat2", "pat3" } + • pattern: (string|table) + • pattern or patterns to match exactly. + • For example, if you have `*.py` as that pattern for the + autocmd, you must pass `*.py` exactly to clear it. + `test.py` will not match the pattern. + • defaults to clearing all patterns. + • NOTE: Cannot be used with {buffer} + • buffer: (bufnr) + • clear only |autocmd-buflocal| autocommands. + • NOTE: Cannot be used with {pattern} + • group: (string|int) The augroup name or id. + • NOTE: If not passed, will only delete autocmds not in any + group. - See also: ~ - • nvim_create_user_command +nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* + Create or get an autocommand group |autocmd-groups|. - *nvim_buf_del_user_command()* -nvim_buf_del_user_command({buffer}, {name}) - Delete a buffer-local user-defined command. - - Only commands created with |:command-buffer| or - |nvim_buf_create_user_command()| can be deleted with this function. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {buffer} (`integer`) Buffer id, or 0 for current buffer. - • {name} (`string`) Name of the command to delete. - -nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* - Gets a map of buffer-local |user-commands|. - - Attributes: ~ - Since: 0.3.0 - - Parameters: ~ - • {buffer} (`integer`) Buffer id, or 0 for current buffer - • {opts} (`vim.api.keyset.get_commands`) Optional parameters. - Currently not used. - - Return: ~ - (`vim.api.keyset.command_info`) Map of maps describing commands. - -nvim_cmd({cmd}, {opts}) *nvim_cmd()* - Executes an Ex command. - - 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)`. - - On execution error: fails with Vimscript error, updates v:errmsg. - - Attributes: ~ - 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. - • {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. - - See also: ~ - • |nvim_exec2()| - • |nvim_command()| - - *nvim_create_user_command()* -nvim_create_user_command({name}, {command}, {opts}) - Creates a global |user-commands| command. - - For Lua usage see |lua-guide-commands-create|. - - Example: >vim - :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) - :SayHello - Hello world! + To get an existing group id, do: >lua + local id = vim.api.nvim_create_augroup('my.lsp.config', { + clear = false + }) < Attributes: ~ Since: 0.7.0 Parameters: ~ - • {name} (`string`) Name of the new user command. Must begin with an - uppercase letter. - • {command} (`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: - • name: (string) Command name - • args: (string) The args passed to the command, if any - - • fargs: (table) The args split by unescaped whitespace - (when more than one argument is allowed), if any - • nargs: (string) Number of arguments |:command-nargs| - • bang: (boolean) "true" if the command was executed with a - ! modifier - • line1: (number) The starting line of the command range - - • line2: (number) The final line of the command range - - • range: (number) The number of items in the command range: - 0, 1, or 2 - • count: (number) Any count supplied - • reg: (string) The optional register, if specified - • mods: (string) Command modifiers, if any - • 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 - |command-attributes|. - • Set boolean attributes such as |:command-bang| or - |:command-bar| to true (but not |:command-buffer|, use - |nvim_buf_create_user_command()| instead). - • "complete" |:command-complete| also accepts a Lua - function which works like - |:command-completion-customlist|. - • Other parameters: - • desc: (string) Used for listing the command when a Lua - function is used for {command}. - • force: (boolean, default true) Override any previous - definition. - • preview: (function) Preview callback for 'inccommand' - |:command-preview| - -nvim_del_user_command({name}) *nvim_del_user_command()* - Delete a user-defined command. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {name} (`string`) Name of the command to delete. - -nvim_get_commands({opts}) *nvim_get_commands()* - Gets a map of global (non-buffer-local) Ex commands. - - Currently only |user-commands| are supported, not builtin Ex commands. - - Attributes: ~ - Since: 0.3.0 - - Parameters: ~ - • {opts} (`vim.api.keyset.get_commands`) Optional parameters. Currently - only supports {"builtin":false} + • {name} (`string`) String: The name of the group + • {opts} (`vim.api.keyset.create_augroup`) Dict Parameters + • clear (bool) optional: defaults to true. Clear existing + commands if the group already exists |autocmd-groups|. Return: ~ - (`table`) Map of maps describing - commands. + (`integer`) Integer id of the created group. See also: ~ - • |nvim_get_all_options_info()| + • |autocmd-groups| -nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* - Parse command line. +nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* + Creates an |autocommand| event handler, defined by `callback` (Lua + function or Vimscript function name string) or `command` (Ex command + string). - Doesn't check the validity of command arguments. + Example using Lua callback: >lua + vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, { + pattern = {'*.c', '*.h'}, + callback = function(ev) + print(string.format('event fired: %s', vim.inspect(ev))) + end + }) +< + + Example using an Ex command as the handler: >lua + vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, { + pattern = {'*.c', '*.h'}, + command = "echo 'Entering a C or C++ file'", + }) +< + + Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), + thus names like "$HOME" and "~" must be expanded explicitly: >lua + pattern = vim.fn.expand('~') .. '/some/path/*.py' +< Attributes: ~ - |api-fast| - Since: 0.8.0 + Since: 0.7.0 Parameters: ~ - • {str} (`string`) Command line string to parse. Cannot contain "\n". - • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for - future use. + • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) + that will trigger the handler (`callback` or `command`). + • {opts} (`vim.api.keyset.create_autocmd`) Options dict: + • group (string|integer) optional: autocommand group name or + id to match against. + • pattern (string|array) optional: pattern(s) to match + literally |autocmd-pattern|. + • buffer (integer) optional: buffer number for buffer-local + autocommands |autocmd-buflocal|. Cannot be used with + {pattern}. + • desc (string) optional: description (for documentation and + troubleshooting). + • callback (function|string) optional: Lua function (or + Vimscript function name, if string) called when the + event(s) is triggered. Lua callback can return a truthy + value (not `false` or `nil`) to delete the autocommand, and + receives one argument, a table with these keys: + *event-args* + • id: (number) autocommand id + • event: (vim.api.keyset.events) name of the triggered + event |autocmd-events| + • group: (number|nil) autocommand group id, if any + • file: (string) (not expanded to a full path) + • match: (string) (expanded to a full path) + • buf: (number) + • data: (any) arbitrary data passed from + |nvim_exec_autocmds()| *event-data* + • command (string) optional: Vim command to execute on event. + Cannot be used with {callback} + • once (boolean) optional: defaults to false. Run the + autocommand only once |autocmd-once|. + • nested (boolean) optional: defaults to false. Run nested + autocommands |autocmd-nested|. Return: ~ - (`vim.api.keyset.cmd`) Dict containing command information, with these - keys: - • cmd: (string) Command name. - • range: (array) (optional) Command range ( ). Omitted - if command doesn't accept a range. Otherwise, has no elements if no - range was specified, one element if only a single range item was - specified, or two elements if both range items were specified. - • count: (number) (optional) Command . Omitted if command - cannot take a count. - • reg: (string) (optional) Command . Omitted if command - cannot take a register. - • bang: (boolean) Whether command contains a (!) modifier. - • args: (array) Command arguments. - • addr: (string) Value of |:command-addr|. Uses short name or "line" - for -addr=lines. - • nargs: (string) Value of |:command-nargs|. - • nextcmd: (string) Next command if there are multiple commands - separated by a |:bar|. Empty if there isn't a next command. - • magic: (dict) Which characters have special meaning in the command - arguments. - • file: (boolean) The command expands filenames. Which means - characters such as "%", "#" and wildcards are expanded. - • bar: (boolean) The "|" character is treated as a command separator - and the double quote character (") is treated as the start of a - comment. - • mods: (dict) |:command-modifiers|. - • filter: (dict) |:filter|. - • pattern: (string) Filter pattern. Empty string if there is no - filter. - • force: (boolean) Whether filter is inverted or not. - • silent: (boolean) |:silent|. - • emsg_silent: (boolean) |:silent!|. - • unsilent: (boolean) |:unsilent|. - • sandbox: (boolean) |:sandbox|. - • noautocmd: (boolean) |:noautocmd|. - • browse: (boolean) |:browse|. - • confirm: (boolean) |:confirm|. - • hide: (boolean) |:hide|. - • horizontal: (boolean) |:horizontal|. - • keepalt: (boolean) |:keepalt|. - • keepjumps: (boolean) |:keepjumps|. - • keepmarks: (boolean) |:keepmarks|. - • keeppatterns: (boolean) |:keeppatterns|. - • lockmarks: (boolean) |:lockmarks|. - • noswapfile: (boolean) |:noswapfile|. - • tab: (integer) |:tab|. -1 when omitted. - • verbose: (integer) |:verbose|. -1 when omitted. - • vertical: (boolean) |:vertical|. - • split: (string) Split modifier string, is an empty string when - there's no split modifier. If there is a split modifier it can be - one of: - • "aboveleft": |:aboveleft|. - • "belowright": |:belowright|. - • "topleft": |:topleft|. - • "botright": |:botright|. - - -============================================================================== -Options Functions *api-options* - -nvim_get_all_options_info() *nvim_get_all_options_info()* - Gets the option information for all options. - - The dict has the full option names as keys and option metadata dicts as - detailed at |nvim_get_option_info2()|. - - Attributes: ~ - Since: 0.5.0 - - Return: ~ - (`table`) dict of all options + (`integer`) Autocommand id (number) See also: ~ - • |nvim_get_commands()| + • |autocommand| + • |nvim_del_autocmd()| -nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* - Gets the option information for one option from arbitrary buffer or window +nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* + Delete an autocommand group by id. - Resulting dict has keys: - • name: Name of the option (like 'filetype') - • shortname: Shortened name of the option (like 'ft') - • type: type of option ("string", "number" or "boolean") - • default: The default value for the option - • was_set: Whether the option was set. - • last_set_sid: Last set script id (if any) - • last_set_linenr: line number where option was set - • last_set_chan: Channel where option was set (0 for local) - • scope: one of "global", "win", or "buf" - • global_local: whether win or buf option has a global value - • commalist: List of comma separated values - • flaglist: List of single char flags + To get a group id one can use |nvim_get_autocmds()|. - When {scope} is not provided, the last set information applies to the - local value in the current buffer or window if it is available, otherwise - the global value information is returned. This behavior can be disabled by - explicitly specifying {scope} in the {opts} table. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {name} (`string`) Option name - • {opts} (`vim.api.keyset.option`) Optional parameters - • scope: One of "global" or "local". Analogous to |:setglobal| - and |:setlocal|, respectively. - • win: |window-ID|. Used for getting window local options. - • buf: Buffer number. Used for getting buffer local options. - Implies {scope} is "local". - - Return: ~ - (`vim.api.keyset.get_option_info`) Option Information - -nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* - Gets the value of an option. The behavior of this function matches that of - |:set|: the local value of an option is returned if it exists; otherwise, - the global value is returned. Local values always correspond to the - current buffer or window, unless "buf" or "win" is set in {opts}. + NOTE: behavior differs from |:augroup-delete|. When deleting a group, + autocommands contained in this group will also be deleted and cleared. + This group will no longer exist. Attributes: ~ Since: 0.7.0 Parameters: ~ - • {name} (`string`) Option name - • {opts} (`vim.api.keyset.option`) Optional parameters - • scope: One of "global" or "local". Analogous to |:setglobal| - and |:setlocal|, respectively. - • win: |window-ID|. Used for getting window local options. - • buf: Buffer number. Used for getting buffer local options. - Implies {scope} is "local". - • filetype: |filetype|. Used to get the default option for a - specific filetype. Cannot be used with any other option. - Note: this will trigger |ftplugin| and all |FileType| - autocommands for the corresponding filetype. + • {id} (`integer`) Integer The id of the group. - Return: ~ - (`any`) Option value + See also: ~ + • |nvim_del_augroup_by_name()| + • |nvim_create_augroup()| - *nvim_set_option_value()* -nvim_set_option_value({name}, {value}, {opts}) - Sets the value of an option. The behavior of this function matches that of - |:set|: for global-local options, both the global and local value are set - unless otherwise specified with {scope}. +nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* + Delete an autocommand group by name. - Note the options {win} and {buf} cannot be used together. + NOTE: behavior differs from |:augroup-delete|. When deleting a group, + autocommands contained in this group will also be deleted and cleared. + This group will no longer exist. Attributes: ~ Since: 0.7.0 Parameters: ~ - • {name} (`string`) Option name - • {value} (`any`) New option value - • {opts} (`vim.api.keyset.option`) Optional parameters - • scope: One of "global" or "local". Analogous to - |:setglobal| and |:setlocal|, respectively. - • win: |window-ID|. Used for setting window local option. - • buf: Buffer number. Used for setting buffer local option. + • {name} (`string`) String The name of the group. + + See also: ~ + • |autocmd-groups| + +nvim_del_autocmd({id}) *nvim_del_autocmd()* + Deletes an autocommand by id. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {id} (`integer`) Integer Autocommand id returned by + |nvim_create_autocmd()| + +nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* + Execute all autocommands for {event} that match the corresponding {opts} + |autocmd-execute|. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) The event + or events to execute + • {opts} (`vim.api.keyset.exec_autocmds`) Dict of autocommand options: + • group (string|integer) optional: the autocommand group name + or id to match against. |autocmd-groups|. + • pattern (string|array) optional: defaults to "*" + |autocmd-pattern|. Cannot be used with {buffer}. + • buffer (integer) optional: buffer number + |autocmd-buflocal|. Cannot be used with {pattern}. + • modeline (bool) optional: defaults to true. Process the + modeline after the autocommands . + • data (any): arbitrary data to send to the autocommand + callback. See |nvim_create_autocmd()| for details. + + See also: ~ + • |:doautocmd| + +nvim_get_autocmds({opts}) *nvim_get_autocmds()* + Get all autocommands that match the corresponding {opts}. + + These examples will get autocommands matching ALL the given criteria: >lua + -- Matches all criteria + autocommands = vim.api.nvim_get_autocmds({ + group = 'MyGroup', + event = {'BufEnter', 'BufWinEnter'}, + pattern = {'*.c', '*.h'} + }) + + -- All commands from one group + autocommands = vim.api.nvim_get_autocmds({ + group = 'MyGroup', + }) +< + + NOTE: When multiple patterns or events are provided, it will find all the + autocommands that match any combination of them. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {opts} (`vim.api.keyset.get_autocmds`) Dict with at least one of the + following: + • buffer: (integer) Buffer number or list of buffer numbers + for buffer local autocommands |autocmd-buflocal|. Cannot be + used with {pattern} + • event: (vim.api.keyset.events|vim.api.keyset.events[]) event + or events to match against |autocmd-events|. + • id: (integer) Autocommand ID to match. + • group: (string|table) the autocommand group name or id to + match against. + • pattern: (string|table) pattern or patterns to match against + |autocmd-pattern|. Cannot be used with {buffer} + + Return: ~ + (`vim.api.keyset.get_autocmds.ret[]`) Array of autocommands matching + the criteria, with each item containing the following fields: + • buffer: (integer) the buffer number. + • buflocal: (boolean) true if the autocommand is buffer local. + • command: (string) the autocommand command. Note: this will be empty + if a callback is set. + • callback: (function|string|nil): Lua function or name of a Vim + script function which is executed when this autocommand is + triggered. + • desc: (string) the autocommand description. + • event: (vim.api.keyset.events) the autocommand event. + • id: (integer) the autocommand id (only when defined with the API). + • group: (integer) the autocommand group id. + • group_name: (string) the autocommand group name. + • once: (boolean) whether the autocommand is only run once. + • pattern: (string) the autocommand pattern. If the autocommand is + buffer local |autocmd-buffer-local|: ============================================================================== @@ -2796,6 +2704,250 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* • {value} (`any`) Variable value +============================================================================== +Command Functions *api-command* + + *nvim_buf_create_user_command()* +nvim_buf_create_user_command({buffer}, {name}, {command}, {opts}) + Creates a buffer-local command |user-commands|. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {buffer} (`integer`) Buffer id, or 0 for current buffer. + • {name} (`string`) + • {command} (`any`) + • {opts} (`vim.api.keyset.user_command`) + + See also: ~ + • nvim_create_user_command + + *nvim_buf_del_user_command()* +nvim_buf_del_user_command({buffer}, {name}) + Delete a buffer-local user-defined command. + + Only commands created with |:command-buffer| or + |nvim_buf_create_user_command()| can be deleted with this function. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {buffer} (`integer`) Buffer id, or 0 for current buffer. + • {name} (`string`) Name of the command to delete. + +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* + Gets a map of buffer-local |user-commands|. + + Attributes: ~ + Since: 0.3.0 + + Parameters: ~ + • {buffer} (`integer`) Buffer id, or 0 for current buffer + • {opts} (`vim.api.keyset.get_commands`) Optional parameters. + Currently not used. + + Return: ~ + (`vim.api.keyset.command_info`) Map of maps describing commands. + +nvim_cmd({cmd}, {opts}) *nvim_cmd()* + Executes an Ex command. + + 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)`. + + On execution error: fails with Vimscript error, updates v:errmsg. + + Attributes: ~ + 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. + • {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. + + See also: ~ + • |nvim_exec2()| + • |nvim_command()| + + *nvim_create_user_command()* +nvim_create_user_command({name}, {command}, {opts}) + Creates a global |user-commands| command. + + For Lua usage see |lua-guide-commands-create|. + + Example: >vim + :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) + :SayHello + Hello world! +< + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {name} (`string`) Name of the new user command. Must begin with an + uppercase letter. + • {command} (`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: + • name: (string) Command name + • args: (string) The args passed to the command, if any + + • fargs: (table) The args split by unescaped whitespace + (when more than one argument is allowed), if any + • nargs: (string) Number of arguments |:command-nargs| + • bang: (boolean) "true" if the command was executed with a + ! modifier + • line1: (number) The starting line of the command range + + • line2: (number) The final line of the command range + + • range: (number) The number of items in the command range: + 0, 1, or 2 + • count: (number) Any count supplied + • reg: (string) The optional register, if specified + • mods: (string) Command modifiers, if any + • 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 + |command-attributes|. + • Set boolean attributes such as |:command-bang| or + |:command-bar| to true (but not |:command-buffer|, use + |nvim_buf_create_user_command()| instead). + • "complete" |:command-complete| also accepts a Lua + function which works like + |:command-completion-customlist|. + • Other parameters: + • desc: (string) Used for listing the command when a Lua + function is used for {command}. + • force: (boolean, default true) Override any previous + definition. + • preview: (function) Preview callback for 'inccommand' + |:command-preview| + +nvim_del_user_command({name}) *nvim_del_user_command()* + Delete a user-defined command. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {name} (`string`) Name of the command to delete. + +nvim_get_commands({opts}) *nvim_get_commands()* + Gets a map of global (non-buffer-local) Ex commands. + + Currently only |user-commands| are supported, not builtin Ex commands. + + Attributes: ~ + Since: 0.3.0 + + Parameters: ~ + • {opts} (`vim.api.keyset.get_commands`) Optional parameters. Currently + only supports {"builtin":false} + + Return: ~ + (`table`) Map of maps describing + commands. + + See also: ~ + • |nvim_get_all_options_info()| + +nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* + Parse command line. + + Doesn't check the validity of command arguments. + + Attributes: ~ + |api-fast| + Since: 0.8.0 + + Parameters: ~ + • {str} (`string`) Command line string to parse. Cannot contain "\n". + • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for + future use. + + Return: ~ + (`vim.api.keyset.cmd`) Dict containing command information, with these + keys: + • cmd: (string) Command name. + • range: (array) (optional) Command range ( ). Omitted + if command doesn't accept a range. Otherwise, has no elements if no + range was specified, one element if only a single range item was + specified, or two elements if both range items were specified. + • count: (number) (optional) Command . Omitted if command + cannot take a count. + • reg: (string) (optional) Command . Omitted if command + cannot take a register. + • bang: (boolean) Whether command contains a (!) modifier. + • args: (array) Command arguments. + • addr: (string) Value of |:command-addr|. Uses short name or "line" + for -addr=lines. + • nargs: (string) Value of |:command-nargs|. + • nextcmd: (string) Next command if there are multiple commands + separated by a |:bar|. Empty if there isn't a next command. + • magic: (dict) Which characters have special meaning in the command + arguments. + • file: (boolean) The command expands filenames. Which means + characters such as "%", "#" and wildcards are expanded. + • bar: (boolean) The "|" character is treated as a command separator + and the double quote character (") is treated as the start of a + comment. + • mods: (dict) |:command-modifiers|. + • filter: (dict) |:filter|. + • pattern: (string) Filter pattern. Empty string if there is no + filter. + • force: (boolean) Whether filter is inverted or not. + • silent: (boolean) |:silent|. + • emsg_silent: (boolean) |:silent!|. + • unsilent: (boolean) |:unsilent|. + • sandbox: (boolean) |:sandbox|. + • noautocmd: (boolean) |:noautocmd|. + • browse: (boolean) |:browse|. + • confirm: (boolean) |:confirm|. + • hide: (boolean) |:hide|. + • horizontal: (boolean) |:horizontal|. + • keepalt: (boolean) |:keepalt|. + • keepjumps: (boolean) |:keepjumps|. + • keepmarks: (boolean) |:keepmarks|. + • keeppatterns: (boolean) |:keeppatterns|. + • lockmarks: (boolean) |:lockmarks|. + • noswapfile: (boolean) |:noswapfile|. + • tab: (integer) |:tab|. -1 when omitted. + • verbose: (integer) |:verbose|. -1 when omitted. + • vertical: (boolean) |:vertical|. + • split: (string) Split modifier string, is an empty string when + there's no split modifier. If there is a split modifier it can be + one of: + • "aboveleft": |:aboveleft|. + • "belowright": |:belowright|. + • "topleft": |:topleft|. + • "botright": |:botright|. + + ============================================================================== Extmark Functions *api-extmark* @@ -3182,6 +3334,551 @@ nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()* • wins: a list of windows to be scoped in +============================================================================== +Options Functions *api-options* + +nvim_get_all_options_info() *nvim_get_all_options_info()* + Gets the option information for all options. + + The dict has the full option names as keys and option metadata dicts as + detailed at |nvim_get_option_info2()|. + + Attributes: ~ + Since: 0.5.0 + + Return: ~ + (`table`) dict of all options + + See also: ~ + • |nvim_get_commands()| + +nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* + Gets the option information for one option from arbitrary buffer or window + + Resulting dict has keys: + • name: Name of the option (like 'filetype') + • shortname: Shortened name of the option (like 'ft') + • type: type of option ("string", "number" or "boolean") + • default: The default value for the option + • was_set: Whether the option was set. + • last_set_sid: Last set script id (if any) + • last_set_linenr: line number where option was set + • last_set_chan: Channel where option was set (0 for local) + • scope: one of "global", "win", or "buf" + • global_local: whether win or buf option has a global value + • commalist: List of comma separated values + • flaglist: List of single char flags + + When {scope} is not provided, the last set information applies to the + local value in the current buffer or window if it is available, otherwise + the global value information is returned. This behavior can be disabled by + explicitly specifying {scope} in the {opts} table. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {name} (`string`) Option name + • {opts} (`vim.api.keyset.option`) Optional parameters + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". + + Return: ~ + (`vim.api.keyset.get_option_info`) Option Information + +nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* + Gets the value of an option. The behavior of this function matches that of + |:set|: the local value of an option is returned if it exists; otherwise, + the global value is returned. Local values always correspond to the + current buffer or window, unless "buf" or "win" is set in {opts}. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {name} (`string`) Option name + • {opts} (`vim.api.keyset.option`) Optional parameters + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". + • filetype: |filetype|. Used to get the default option for a + specific filetype. Cannot be used with any other option. + Note: this will trigger |ftplugin| and all |FileType| + autocommands for the corresponding filetype. + + Return: ~ + (`any`) Option value + + *nvim_set_option_value()* +nvim_set_option_value({name}, {value}, {opts}) + Sets the value of an option. The behavior of this function matches that of + |:set|: for global-local options, both the global and local value are set + unless otherwise specified with {scope}. + + Note the options {win} and {buf} cannot be used together. + + Attributes: ~ + Since: 0.7.0 + + Parameters: ~ + • {name} (`string`) Option name + • {value} (`any`) New option value + • {opts} (`vim.api.keyset.option`) Optional parameters + • scope: One of "global" or "local". Analogous to + |:setglobal| and |:setlocal|, respectively. + • win: |window-ID|. Used for setting window local option. + • buf: Buffer number. Used for setting buffer local option. + + +============================================================================== +Tabpage Functions *api-tabpage* + +nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* + Removes a tab-scoped (t:) variable + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + • {name} (`string`) Variable name + +nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* + Gets the tabpage number + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + + Return: ~ + (`integer`) Tabpage number + +nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* + Gets a tab-scoped (t:) variable + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + • {name} (`string`) Variable name + + Return: ~ + (`any`) Variable value + +nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* + Gets the current window in a tabpage + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + + Return: ~ + (`integer`) |window-ID| + +nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* + Checks if a tabpage is valid + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + + Return: ~ + (`boolean`) true if the tabpage is valid, false otherwise + +nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* + Gets the windows in a tabpage + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + + Return: ~ + (`integer[]`) List of windows in `tabpage` + + *nvim_tabpage_set_var()* +nvim_tabpage_set_var({tabpage}, {name}, {value}) + Sets a tab-scoped (t:) variable + + Attributes: ~ + Since: 0.1.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + • {name} (`string`) Variable name + • {value} (`any`) Variable value + +nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* + Sets the current window in a tabpage + + Attributes: ~ + Since: 0.10.0 + + Parameters: ~ + • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage + • {win} (`integer`) |window-ID|, must already belong to {tabpage} + + +============================================================================== +UI Functions *api-ui* + +nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* + Activates UI events on the channel. + + Entry point of all UI clients. Allows |--embed| to continue startup. + Implies that the client is ready to show the UI. Adds the client to the + list of UIs. |nvim_list_uis()| + + Note: ~ + • If multiple UI clients are attached, the global screen dimensions + degrade to the smallest client. E.g. if client A requests 80x40 but + client B requests 200x100, the global screen has size 80x40. + + Attributes: ~ + |RPC| only + Since: 0.1.0 + + Parameters: ~ + • {width} (`integer`) Requested screen columns + • {height} (`integer`) Requested screen rows + • {options} (`table`) |ui-option| map + +nvim_ui_detach() *nvim_ui_detach()* + Deactivates UI events on the channel. + + Removes the client from the list of UIs. |nvim_list_uis()| + + Attributes: ~ + |RPC| only + Since: 0.1.0 + + *nvim_ui_pum_set_bounds()* +nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) + Tells Nvim the geometry of the popupmenu, to align floating windows with + an external popup menu. + + Note that this method is not to be confused with + |nvim_ui_pum_set_height()|, which sets the number of visible items in the + popup menu, while this function sets the bounding box of the popup menu, + including visual elements such as borders and sliders. Floats need not use + the same font size, nor be anchored to exact grid corners, so one can set + floating-point numbers to the popup menu geometry. + + Attributes: ~ + |RPC| only + Since: 0.5.0 + + Parameters: ~ + • {width} (`number`) Popupmenu width. + • {height} (`number`) Popupmenu height. + • {row} (`number`) Popupmenu row. + • {col} (`number`) Popupmenu height. + +nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* + Tells Nvim the number of elements displaying in the popupmenu, to decide + and movement. + + Attributes: ~ + |RPC| only + Since: 0.4.0 + + Parameters: ~ + • {height} (`integer`) Popupmenu height, must be greater than zero. + +nvim_ui_set_focus({gained}) *nvim_ui_set_focus()* + Tells the nvim server if focus was gained or lost by the GUI + + Attributes: ~ + |RPC| only + Since: 0.9.0 + + Parameters: ~ + • {gained} (`boolean`) + +nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* + + Attributes: ~ + |RPC| only + Since: 0.1.0 + + Parameters: ~ + • {name} (`string`) + • {value} (`any`) + +nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* + Tells Nvim when a terminal event has occurred + + The following terminal events are supported: + • "termresponse": The terminal sent a DA1, OSC, DCS, or APC response + sequence to Nvim. The payload is the received response. Sets + |v:termresponse| and fires |TermResponse|. + + Attributes: ~ + |RPC| only + Since: 0.10.0 + + Parameters: ~ + • {event} (`string`) Event name + • {value} (`any`) Event payload + +nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* + + Attributes: ~ + |RPC| only + Since: 0.1.0 + + Parameters: ~ + • {width} (`integer`) + • {height} (`integer`) + + *nvim_ui_try_resize_grid()* +nvim_ui_try_resize_grid({grid}, {width}, {height}) + Tell Nvim to resize a grid. Triggers a grid_resize event with the + requested grid size or the maximum size if it exceeds size limits. + + On invalid grid handle, fails with error. + + Attributes: ~ + |RPC| only + Since: 0.4.0 + + Parameters: ~ + • {grid} (`integer`) The handle of the grid to be changed. + • {width} (`integer`) The new requested width. + • {height} (`integer`) The new requested height. + + +============================================================================== +Win_config Functions *api-win_config* + +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* + Opens a new split window, or a floating window if `relative` is specified, + or an external window (managed by the UI) if `external` is specified. + + Floats are windows that are drawn above the split layout, at some anchor + position in some other window. Floats can be drawn internally or by + external GUI with the |ui-multigrid| extension. External windows are only + supported with multigrid GUIs, and are displayed as separate top-level + windows. + + For a general overview of floats, see |api-floatwin|. + + The `width` and `height` of the new window must be specified when opening + a floating window, but are optional for normal windows. + + If `relative` and `external` are omitted, a normal "split" window is + created. The `win` property determines which window will be split. If no + `win` is provided or `win == 0`, a window will be created adjacent to the + current window. If -1 is provided, a top-level split will be created. + `vertical` and `split` are only valid for normal windows, and are used to + control split direction. For `vertical`, the exact direction is determined + by |'splitright'| and |'splitbelow'|. Split windows cannot have + `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. + + With relative=editor (row=0,col=0) refers to the top-left corner of the + screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right + corner. Fractional values are allowed, but the builtin implementation + (used by non-multigrid UIs) will always round down to nearest integer. + + Out-of-bounds values, and configurations that make the float not fit + inside the main editor, are allowed. The builtin implementation truncates + values so floats are fully within the main screen grid. External GUIs + could let floats hover outside of the main window like a tooltip, but this + should not be used to specify arbitrary WM screen positions. + + Example (Lua): window-relative float >lua + vim.api.nvim_open_win(0, false, + {relative='win', row=3, col=3, width=12, height=3}) +< + + Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua + vim.api.nvim_open_win(0, false, + {relative='win', width=12, height=3, bufpos={100,10}}) +< + + Example (Lua): vertical split left of the current window >lua + vim.api.nvim_open_win(0, false, { + split = 'left', + win = 0 + }) +< + + Attributes: ~ + not allowed when |textlock| is active + Since: 0.4.0 + + Parameters: ~ + • {buffer} (`integer`) Buffer to display, or 0 for current buffer + • {enter} (`boolean`) Enter the window (make it the current window) + • {config} (`vim.api.keyset.win_config`) Map defining the window + configuration. Keys: + • relative: Sets the window layout to "floating", placed at + (row,col) coordinates relative to: + • "cursor" Cursor position in current window. + • "editor" The global editor grid. + • "laststatus" 'laststatus' if present, or last row. + • "mouse" Mouse position. + • "tabline" Tabline if present, or first row. + • "win" Window given by the `win` field, or current + window. + • win: |window-ID| window to split, or relative window when + creating a float (relative="win"). + • anchor: Decides which corner of the float to place at + (row,col): + • "NW" northwest (default) + • "NE" northeast + • "SW" southwest + • "SE" southeast + • width: Window width (in character cells). Minimum of 1. + • height: Window height (in character cells). Minimum of 1. + • bufpos: Places float relative to buffer text (only when + relative="win"). Takes a tuple of zero-indexed + `[line, column]`. `row` and `col` if given are applied + relative to this position, else they default to: + • `row=1` and `col=0` if `anchor` is "NW" or "NE" + • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus + like a tooltip near the buffer text). + • row: Row position in units of "screen cell height", may be + fractional. + • col: Column position in units of screen cell width, may be + fractional. + • focusable: Enable focus by user actions (wincmds, mouse + events). Defaults to true. Non-focusable windows can be + entered by |nvim_set_current_win()|, or, when the `mouse` + field is set to true, by mouse events. See |focusable|. + • mouse: Specify how this window interacts with mouse + events. Defaults to `focusable` value. + • If false, mouse events pass through this window. + • If true, mouse events interact with this window + normally. + • external: GUI should display the window as an external + top-level window. Currently accepts no other positioning + configuration together with this. + • zindex: Stacking order. floats with higher `zindex` go on + top on floats with lower indices. Must be larger than + zero. The following screen elements have hard-coded + z-indices: + • 100: insert completion popupmenu + • 200: message scrollback + • 250: cmdline completion popupmenu (when + wildoptions+=pum) The default value for floats are 50. + In general, values below 100 are recommended, unless + there is a good reason to overshadow builtin elements. + • style: (optional) Configure the appearance of the window. + Currently only supports one value: + • "minimal" Nvim will display the window with many UI + options disabled. This is useful when displaying a + temporary float where the text should not be edited. + Disables 'number', 'relativenumber', 'cursorline', + 'cursorcolumn', 'foldcolumn', 'spell' and 'list' + options. 'signcolumn' is changed to `auto` and + 'colorcolumn' is cleared. 'statuscolumn' is changed to + empty. The end-of-buffer region is hidden by setting + `eob` flag of 'fillchars' to a space char, and clearing + the |hl-EndOfBuffer| region in 'winhighlight'. + • border: (`string|string[]`) (defaults to 'winborder' + option) Window border. The string form accepts the same + values as the 'winborder' option. The array form must have + a length of eight or any divisor of eight, specifying the + chars that form the border in a clockwise fashion starting + from the top-left corner. For example, the double-box + style can be specified as: > + [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +< + If fewer than eight chars are given, they will be + repeated. An ASCII border could be specified as: > + [ "/", "-", \"\\\\\", "|" ], +< + Or one char for all sides: > + [ "x" ]. +< + Empty string can be used to hide a specific border. This + example will show only vertical borders, not horizontal: > + [ "", "", "", ">", "", "", "", "<" ] +< + By default, |hl-FloatBorder| highlight is used, which + links to |hl-WinSeparator| when not defined. Each border + side can specify an optional highlight: > + [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +< + • title: (optional) Title in window border, string or list. + List should consist of `[text, highlight]` tuples. If + string, or a tuple lacks a highlight, the default + highlight group is `FloatTitle`. + • title_pos: Title position. Must be set with `title` + option. Value can be one of "left", "center", or "right". + Default is `"left"`. + • footer: (optional) Footer in window border, string or + list. List should consist of `[text, highlight]` tuples. + If string, or a tuple lacks a highlight, the default + highlight group is `FloatFooter`. + • footer_pos: Footer position. Must be set with `footer` + option. Value can be one of "left", "center", or "right". + Default is `"left"`. + • noautocmd: If true then all autocommands are blocked for + the duration of the call. + • fixed: If true when anchor is NW or SW, the float window + would be kept fixed even if the window would be truncated. + • hide: If true the floating window will be hidden and the + cursor will be invisible when focused on it. + • vertical: Split vertically |:vertical|. + • split: Split direction: "left", "right", "above", "below". + • _cmdline_offset: (EXPERIMENTAL) When provided, anchor the + |cmdline-completion| popupmenu to this window, with an + offset in screen cell width. + + Return: ~ + (`integer`) |window-ID|, or 0 on error + +nvim_win_get_config({window}) *nvim_win_get_config()* + Gets window configuration. + + The returned value may be given to |nvim_open_win()|. + + `relative` is empty for normal windows. + + Attributes: ~ + Since: 0.4.0 + + Parameters: ~ + • {window} (`integer`) |window-ID|, or 0 for current window + + Return: ~ + (`vim.api.keyset.win_config`) Map defining the window configuration, + see |nvim_open_win()| + +nvim_win_set_config({window}, {config}) *nvim_win_set_config()* + Configures window layout. Cannot be used to move the last window in a + tabpage to a different one. + + When reconfiguring a window, absent option keys will not be changed. + `row`/`col` and `relative` must be reconfigured together. + + Attributes: ~ + Since: 0.4.0 + + Parameters: ~ + • {window} (`integer`) |window-ID|, or 0 for current window + • {config} (`vim.api.keyset.win_config`) Map defining the window + configuration, see |nvim_open_win()| + + See also: ~ + • |nvim_open_win()| + + ============================================================================== Window Functions *api-window* @@ -3475,701 +4172,4 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* • |virtcol()| for text width. -============================================================================== -Win_config Functions *api-win_config* - -nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - Opens a new split window, or a floating window if `relative` is specified, - or an external window (managed by the UI) if `external` is specified. - - Floats are windows that are drawn above the split layout, at some anchor - position in some other window. Floats can be drawn internally or by - external GUI with the |ui-multigrid| extension. External windows are only - supported with multigrid GUIs, and are displayed as separate top-level - windows. - - For a general overview of floats, see |api-floatwin|. - - The `width` and `height` of the new window must be specified when opening - a floating window, but are optional for normal windows. - - If `relative` and `external` are omitted, a normal "split" window is - created. The `win` property determines which window will be split. If no - `win` is provided or `win == 0`, a window will be created adjacent to the - current window. If -1 is provided, a top-level split will be created. - `vertical` and `split` are only valid for normal windows, and are used to - control split direction. For `vertical`, the exact direction is determined - by |'splitright'| and |'splitbelow'|. Split windows cannot have - `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. - - With relative=editor (row=0,col=0) refers to the top-left corner of the - screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right - corner. Fractional values are allowed, but the builtin implementation - (used by non-multigrid UIs) will always round down to nearest integer. - - Out-of-bounds values, and configurations that make the float not fit - inside the main editor, are allowed. The builtin implementation truncates - values so floats are fully within the main screen grid. External GUIs - could let floats hover outside of the main window like a tooltip, but this - should not be used to specify arbitrary WM screen positions. - - Example (Lua): window-relative float >lua - vim.api.nvim_open_win(0, false, - {relative='win', row=3, col=3, width=12, height=3}) -< - - Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua - vim.api.nvim_open_win(0, false, - {relative='win', width=12, height=3, bufpos={100,10}}) -< - - Example (Lua): vertical split left of the current window >lua - vim.api.nvim_open_win(0, false, { - split = 'left', - win = 0 - }) -< - - Attributes: ~ - not allowed when |textlock| is active - Since: 0.4.0 - - Parameters: ~ - • {buffer} (`integer`) Buffer to display, or 0 for current buffer - • {enter} (`boolean`) Enter the window (make it the current window) - • {config} (`vim.api.keyset.win_config`) Map defining the window - configuration. Keys: - • relative: Sets the window layout to "floating", placed at - (row,col) coordinates relative to: - • "cursor" Cursor position in current window. - • "editor" The global editor grid. - • "laststatus" 'laststatus' if present, or last row. - • "mouse" Mouse position. - • "tabline" Tabline if present, or first row. - • "win" Window given by the `win` field, or current - window. - • win: |window-ID| window to split, or relative window when - creating a float (relative="win"). - • anchor: Decides which corner of the float to place at - (row,col): - • "NW" northwest (default) - • "NE" northeast - • "SW" southwest - • "SE" southeast - • width: Window width (in character cells). Minimum of 1. - • height: Window height (in character cells). Minimum of 1. - • bufpos: Places float relative to buffer text (only when - relative="win"). Takes a tuple of zero-indexed - `[line, column]`. `row` and `col` if given are applied - relative to this position, else they default to: - • `row=1` and `col=0` if `anchor` is "NW" or "NE" - • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus - like a tooltip near the buffer text). - • row: Row position in units of "screen cell height", may be - fractional. - • col: Column position in units of screen cell width, may be - fractional. - • focusable: Enable focus by user actions (wincmds, mouse - events). Defaults to true. Non-focusable windows can be - entered by |nvim_set_current_win()|, or, when the `mouse` - field is set to true, by mouse events. See |focusable|. - • mouse: Specify how this window interacts with mouse - events. Defaults to `focusable` value. - • If false, mouse events pass through this window. - • If true, mouse events interact with this window - normally. - • external: GUI should display the window as an external - top-level window. Currently accepts no other positioning - configuration together with this. - • zindex: Stacking order. floats with higher `zindex` go on - top on floats with lower indices. Must be larger than - zero. The following screen elements have hard-coded - z-indices: - • 100: insert completion popupmenu - • 200: message scrollback - • 250: cmdline completion popupmenu (when - wildoptions+=pum) The default value for floats are 50. - In general, values below 100 are recommended, unless - there is a good reason to overshadow builtin elements. - • style: (optional) Configure the appearance of the window. - Currently only supports one value: - • "minimal" Nvim will display the window with many UI - options disabled. This is useful when displaying a - temporary float where the text should not be edited. - Disables 'number', 'relativenumber', 'cursorline', - 'cursorcolumn', 'foldcolumn', 'spell' and 'list' - options. 'signcolumn' is changed to `auto` and - 'colorcolumn' is cleared. 'statuscolumn' is changed to - empty. The end-of-buffer region is hidden by setting - `eob` flag of 'fillchars' to a space char, and clearing - the |hl-EndOfBuffer| region in 'winhighlight'. - • border: (`string|string[]`) (defaults to 'winborder' - option) Window border. The string form accepts the same - values as the 'winborder' option. The array form must have - a length of eight or any divisor of eight, specifying the - chars that form the border in a clockwise fashion starting - from the top-left corner. For example, the double-box - style can be specified as: > - [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. -< - If fewer than eight chars are given, they will be - repeated. An ASCII border could be specified as: > - [ "/", "-", \"\\\\\", "|" ], -< - Or one char for all sides: > - [ "x" ]. -< - Empty string can be used to hide a specific border. This - example will show only vertical borders, not horizontal: > - [ "", "", "", ">", "", "", "", "<" ] -< - By default, |hl-FloatBorder| highlight is used, which - links to |hl-WinSeparator| when not defined. Each border - side can specify an optional highlight: > - [ ["+", "MyCorner"], ["x", "MyBorder"] ]. -< - • title: (optional) Title in window border, string or list. - List should consist of `[text, highlight]` tuples. If - string, or a tuple lacks a highlight, the default - highlight group is `FloatTitle`. - • title_pos: Title position. Must be set with `title` - option. Value can be one of "left", "center", or "right". - Default is `"left"`. - • footer: (optional) Footer in window border, string or - list. List should consist of `[text, highlight]` tuples. - If string, or a tuple lacks a highlight, the default - highlight group is `FloatFooter`. - • footer_pos: Footer position. Must be set with `footer` - option. Value can be one of "left", "center", or "right". - Default is `"left"`. - • noautocmd: If true then all autocommands are blocked for - the duration of the call. - • fixed: If true when anchor is NW or SW, the float window - would be kept fixed even if the window would be truncated. - • hide: If true the floating window will be hidden and the - cursor will be invisible when focused on it. - • vertical: Split vertically |:vertical|. - • split: Split direction: "left", "right", "above", "below". - • _cmdline_offset: (EXPERIMENTAL) When provided, anchor the - |cmdline-completion| popupmenu to this window, with an - offset in screen cell width. - - Return: ~ - (`integer`) |window-ID|, or 0 on error - -nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. - - The returned value may be given to |nvim_open_win()|. - - `relative` is empty for normal windows. - - Attributes: ~ - Since: 0.4.0 - - Parameters: ~ - • {window} (`integer`) |window-ID|, or 0 for current window - - Return: ~ - (`vim.api.keyset.win_config`) Map defining the window configuration, - see |nvim_open_win()| - -nvim_win_set_config({window}, {config}) *nvim_win_set_config()* - Configures window layout. Cannot be used to move the last window in a - tabpage to a different one. - - When reconfiguring a window, absent option keys will not be changed. - `row`/`col` and `relative` must be reconfigured together. - - Attributes: ~ - Since: 0.4.0 - - Parameters: ~ - • {window} (`integer`) |window-ID|, or 0 for current window - • {config} (`vim.api.keyset.win_config`) Map defining the window - configuration, see |nvim_open_win()| - - See also: ~ - • |nvim_open_win()| - - -============================================================================== -Tabpage Functions *api-tabpage* - -nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* - Removes a tab-scoped (t:) variable - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - • {name} (`string`) Variable name - -nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* - Gets the tabpage number - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - - Return: ~ - (`integer`) Tabpage number - -nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* - Gets a tab-scoped (t:) variable - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - • {name} (`string`) Variable name - - Return: ~ - (`any`) Variable value - -nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* - Gets the current window in a tabpage - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - - Return: ~ - (`integer`) |window-ID| - -nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* - Checks if a tabpage is valid - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - - Return: ~ - (`boolean`) true if the tabpage is valid, false otherwise - -nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* - Gets the windows in a tabpage - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - - Return: ~ - (`integer[]`) List of windows in `tabpage` - - *nvim_tabpage_set_var()* -nvim_tabpage_set_var({tabpage}, {name}, {value}) - Sets a tab-scoped (t:) variable - - Attributes: ~ - Since: 0.1.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - • {name} (`string`) Variable name - • {value} (`any`) Variable value - -nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* - Sets the current window in a tabpage - - Attributes: ~ - Since: 0.10.0 - - Parameters: ~ - • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage - • {win} (`integer`) |window-ID|, must already belong to {tabpage} - - -============================================================================== -Autocmd Functions *api-autocmd* - -nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* - Clears all autocommands selected by {opts}. To delete autocmds see - |nvim_del_autocmd()|. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {opts} (`vim.api.keyset.clear_autocmds`) Parameters - • event: (vim.api.keyset.events|vim.api.keyset.events[]) - Examples: - • event: "pat1" - • event: { "pat1" } - • event: { "pat1", "pat2", "pat3" } - • pattern: (string|table) - • pattern or patterns to match exactly. - • For example, if you have `*.py` as that pattern for the - autocmd, you must pass `*.py` exactly to clear it. - `test.py` will not match the pattern. - • defaults to clearing all patterns. - • NOTE: Cannot be used with {buffer} - • buffer: (bufnr) - • clear only |autocmd-buflocal| autocommands. - • NOTE: Cannot be used with {pattern} - • group: (string|int) The augroup name or id. - • NOTE: If not passed, will only delete autocmds not in any - group. - -nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* - Create or get an autocommand group |autocmd-groups|. - - To get an existing group id, do: >lua - local id = vim.api.nvim_create_augroup('my.lsp.config', { - clear = false - }) -< - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {name} (`string`) String: The name of the group - • {opts} (`vim.api.keyset.create_augroup`) Dict Parameters - • clear (bool) optional: defaults to true. Clear existing - commands if the group already exists |autocmd-groups|. - - Return: ~ - (`integer`) Integer id of the created group. - - See also: ~ - • |autocmd-groups| - -nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* - Creates an |autocommand| event handler, defined by `callback` (Lua - function or Vimscript function name string) or `command` (Ex command - string). - - Example using Lua callback: >lua - vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, { - pattern = {'*.c', '*.h'}, - callback = function(ev) - print(string.format('event fired: %s', vim.inspect(ev))) - end - }) -< - - Example using an Ex command as the handler: >lua - vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, { - pattern = {'*.c', '*.h'}, - command = "echo 'Entering a C or C++ file'", - }) -< - - Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), - thus names like "$HOME" and "~" must be expanded explicitly: >lua - pattern = vim.fn.expand('~') .. '/some/path/*.py' -< - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) - that will trigger the handler (`callback` or `command`). - • {opts} (`vim.api.keyset.create_autocmd`) Options dict: - • group (string|integer) optional: autocommand group name or - id to match against. - • pattern (string|array) optional: pattern(s) to match - literally |autocmd-pattern|. - • buffer (integer) optional: buffer number for buffer-local - autocommands |autocmd-buflocal|. Cannot be used with - {pattern}. - • desc (string) optional: description (for documentation and - troubleshooting). - • callback (function|string) optional: Lua function (or - Vimscript function name, if string) called when the - event(s) is triggered. Lua callback can return a truthy - value (not `false` or `nil`) to delete the autocommand, and - receives one argument, a table with these keys: - *event-args* - • id: (number) autocommand id - • event: (vim.api.keyset.events) name of the triggered - event |autocmd-events| - • group: (number|nil) autocommand group id, if any - • file: (string) (not expanded to a full path) - • match: (string) (expanded to a full path) - • buf: (number) - • data: (any) arbitrary data passed from - |nvim_exec_autocmds()| *event-data* - • command (string) optional: Vim command to execute on event. - Cannot be used with {callback} - • once (boolean) optional: defaults to false. Run the - autocommand only once |autocmd-once|. - • nested (boolean) optional: defaults to false. Run nested - autocommands |autocmd-nested|. - - Return: ~ - (`integer`) Autocommand id (number) - - See also: ~ - • |autocommand| - • |nvim_del_autocmd()| - -nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* - Delete an autocommand group by id. - - To get a group id one can use |nvim_get_autocmds()|. - - NOTE: behavior differs from |:augroup-delete|. When deleting a group, - autocommands contained in this group will also be deleted and cleared. - This group will no longer exist. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {id} (`integer`) Integer The id of the group. - - See also: ~ - • |nvim_del_augroup_by_name()| - • |nvim_create_augroup()| - -nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* - Delete an autocommand group by name. - - NOTE: behavior differs from |:augroup-delete|. When deleting a group, - autocommands contained in this group will also be deleted and cleared. - This group will no longer exist. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {name} (`string`) String The name of the group. - - See also: ~ - • |autocmd-groups| - -nvim_del_autocmd({id}) *nvim_del_autocmd()* - Deletes an autocommand by id. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {id} (`integer`) Integer Autocommand id returned by - |nvim_create_autocmd()| - -nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* - Execute all autocommands for {event} that match the corresponding {opts} - |autocmd-execute|. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) The event - or events to execute - • {opts} (`vim.api.keyset.exec_autocmds`) Dict of autocommand options: - • group (string|integer) optional: the autocommand group name - or id to match against. |autocmd-groups|. - • pattern (string|array) optional: defaults to "*" - |autocmd-pattern|. Cannot be used with {buffer}. - • buffer (integer) optional: buffer number - |autocmd-buflocal|. Cannot be used with {pattern}. - • modeline (bool) optional: defaults to true. Process the - modeline after the autocommands . - • data (any): arbitrary data to send to the autocommand - callback. See |nvim_create_autocmd()| for details. - - See also: ~ - • |:doautocmd| - -nvim_get_autocmds({opts}) *nvim_get_autocmds()* - Get all autocommands that match the corresponding {opts}. - - These examples will get autocommands matching ALL the given criteria: >lua - -- Matches all criteria - autocommands = vim.api.nvim_get_autocmds({ - group = 'MyGroup', - event = {'BufEnter', 'BufWinEnter'}, - pattern = {'*.c', '*.h'} - }) - - -- All commands from one group - autocommands = vim.api.nvim_get_autocmds({ - group = 'MyGroup', - }) -< - - NOTE: When multiple patterns or events are provided, it will find all the - autocommands that match any combination of them. - - Attributes: ~ - Since: 0.7.0 - - Parameters: ~ - • {opts} (`vim.api.keyset.get_autocmds`) Dict with at least one of the - following: - • buffer: (integer) Buffer number or list of buffer numbers - for buffer local autocommands |autocmd-buflocal|. Cannot be - used with {pattern} - • event: (vim.api.keyset.events|vim.api.keyset.events[]) event - or events to match against |autocmd-events|. - • id: (integer) Autocommand ID to match. - • group: (string|table) the autocommand group name or id to - match against. - • pattern: (string|table) pattern or patterns to match against - |autocmd-pattern|. Cannot be used with {buffer} - - Return: ~ - (`vim.api.keyset.get_autocmds.ret[]`) Array of autocommands matching - the criteria, with each item containing the following fields: - • buffer: (integer) the buffer number. - • buflocal: (boolean) true if the autocommand is buffer local. - • command: (string) the autocommand command. Note: this will be empty - if a callback is set. - • callback: (function|string|nil): Lua function or name of a Vim - script function which is executed when this autocommand is - triggered. - • desc: (string) the autocommand description. - • event: (vim.api.keyset.events) the autocommand event. - • id: (integer) the autocommand id (only when defined with the API). - • group: (integer) the autocommand group id. - • group_name: (string) the autocommand group name. - • once: (boolean) whether the autocommand is only run once. - • pattern: (string) the autocommand pattern. If the autocommand is - buffer local |autocmd-buffer-local|: - - -============================================================================== -UI Functions *api-ui* - -nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* - Activates UI events on the channel. - - Entry point of all UI clients. Allows |--embed| to continue startup. - Implies that the client is ready to show the UI. Adds the client to the - list of UIs. |nvim_list_uis()| - - Note: ~ - • If multiple UI clients are attached, the global screen dimensions - degrade to the smallest client. E.g. if client A requests 80x40 but - client B requests 200x100, the global screen has size 80x40. - - Attributes: ~ - |RPC| only - Since: 0.1.0 - - Parameters: ~ - • {width} (`integer`) Requested screen columns - • {height} (`integer`) Requested screen rows - • {options} (`table`) |ui-option| map - -nvim_ui_detach() *nvim_ui_detach()* - Deactivates UI events on the channel. - - Removes the client from the list of UIs. |nvim_list_uis()| - - Attributes: ~ - |RPC| only - Since: 0.1.0 - - *nvim_ui_pum_set_bounds()* -nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) - Tells Nvim the geometry of the popupmenu, to align floating windows with - an external popup menu. - - Note that this method is not to be confused with - |nvim_ui_pum_set_height()|, which sets the number of visible items in the - popup menu, while this function sets the bounding box of the popup menu, - including visual elements such as borders and sliders. Floats need not use - the same font size, nor be anchored to exact grid corners, so one can set - floating-point numbers to the popup menu geometry. - - Attributes: ~ - |RPC| only - Since: 0.5.0 - - Parameters: ~ - • {width} (`number`) Popupmenu width. - • {height} (`number`) Popupmenu height. - • {row} (`number`) Popupmenu row. - • {col} (`number`) Popupmenu height. - -nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* - Tells Nvim the number of elements displaying in the popupmenu, to decide - and movement. - - Attributes: ~ - |RPC| only - Since: 0.4.0 - - Parameters: ~ - • {height} (`integer`) Popupmenu height, must be greater than zero. - -nvim_ui_set_focus({gained}) *nvim_ui_set_focus()* - Tells the nvim server if focus was gained or lost by the GUI - - Attributes: ~ - |RPC| only - Since: 0.9.0 - - Parameters: ~ - • {gained} (`boolean`) - -nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* - - Attributes: ~ - |RPC| only - Since: 0.1.0 - - Parameters: ~ - • {name} (`string`) - • {value} (`any`) - -nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* - Tells Nvim when a terminal event has occurred - - The following terminal events are supported: - • "termresponse": The terminal sent a DA1, OSC, DCS, or APC response - sequence to Nvim. The payload is the received response. Sets - |v:termresponse| and fires |TermResponse|. - - Attributes: ~ - |RPC| only - Since: 0.10.0 - - Parameters: ~ - • {event} (`string`) Event name - • {value} (`any`) Event payload - -nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - - Attributes: ~ - |RPC| only - Since: 0.1.0 - - Parameters: ~ - • {width} (`integer`) - • {height} (`integer`) - - *nvim_ui_try_resize_grid()* -nvim_ui_try_resize_grid({grid}, {width}, {height}) - Tell Nvim to resize a grid. Triggers a grid_resize event with the - requested grid size or the maximum size if it exceeds size limits. - - On invalid grid handle, fails with error. - - Attributes: ~ - |RPC| only - Since: 0.4.0 - - Parameters: ~ - • {grid} (`integer`) The handle of the grid to be changed. - • {width} (`integer`) The new requested width. - • {height} (`integer`) The new requested height. - - vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index e042aa5cfa..716e141f62 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -1262,6 +1262,314 @@ tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()* (`table[]`) tags A list of matching tags +============================================================================== +Lua module: vim.lsp.buf *lsp-buf* + +The `vim.lsp.buf_…` functions perform operations for LSP clients attached to +the current buffer. + + +*vim.lsp.ListOpts* + + Fields: ~ + • {on_list}? (`fun(t: vim.lsp.LocationOpts.OnList)`) list-handler + replacing the default handler. Called for any non-empty + result. This table can be used with |setqflist()| or + |setloclist()|. E.g.: >lua + local function on_list(options) + vim.fn.setqflist({}, ' ', options) + vim.cmd.cfirst() + end + + vim.lsp.buf.definition({ on_list = on_list }) + vim.lsp.buf.references(nil, { on_list = on_list }) +< + • {loclist}? (`boolean`) Whether to use the |location-list| or the + |quickfix| list in the default handler. >lua + vim.lsp.buf.definition({ loclist = true }) + vim.lsp.buf.references(nil, { loclist = false }) +< + +*vim.lsp.LocationOpts* + Extends: |vim.lsp.ListOpts| + + + Fields: ~ + • {reuse_win}? (`boolean`) Jump to existing window if buffer is already + open. + +*vim.lsp.LocationOpts.OnList* + + Fields: ~ + • {items} (`table[]`) Structured like |setqflist-what| + • {title}? (`string`) Title for the list. + • {context}? (`{ bufnr: integer, method: string }`) Subset of `ctx` + from |lsp-handler|. + +*vim.lsp.buf.hover.Opts* + Extends: |vim.lsp.util.open_floating_preview.Opts| + + + Fields: ~ + • {silent}? (`boolean`) + +*vim.lsp.buf.signature_help.Opts* + Extends: |vim.lsp.util.open_floating_preview.Opts| + + + Fields: ~ + • {silent}? (`boolean`) + + + *vim.lsp.buf.add_workspace_folder()* +add_workspace_folder({workspace_folder}) + Add the folder at path to the workspace folders. If {path} is not + provided, the user will be prompted for a path using |input()|. + + Parameters: ~ + • {workspace_folder} (`string?`) + +clear_references() *vim.lsp.buf.clear_references()* + Removes document highlights from current buffer. + +code_action({opts}) *vim.lsp.buf.code_action()* + Selects a code action (LSP: "textDocument/codeAction" request) available + at cursor position. + + Parameters: ~ + • {opts} (`table?`) A table with the following fields: + • {context}? (`lsp.CodeActionContext`) Corresponds to + `CodeActionContext` of the LSP specification: + • {diagnostics}? (`table`) LSP `Diagnostic[]`. Inferred from + the current position if not provided. + • {only}? (`table`) List of LSP `CodeActionKind`s used to + filter the code actions. Most language servers support + values like `refactor` or `quickfix`. + • {triggerKind}? (`integer`) The reason why code actions + were requested. + • {filter}? (`fun(x: lsp.CodeAction|lsp.Command):boolean`) + Predicate taking an `CodeAction` and returning a boolean. + • {apply}? (`boolean`) When set to `true`, and there is just + one remaining action (after filtering), the action is + applied without user query. + • {range}? (`{start: integer[], end: integer[]}`) Range for + which code actions should be requested. If in visual mode + this defaults to the active selection. Table must contain + `start` and `end` keys with {row,col} tuples using mark-like + indexing. See |api-indexing| + + See also: ~ + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction + • vim.lsp.protocol.CodeActionTriggerKind + +declaration({opts}) *vim.lsp.buf.declaration()* + Jumps to the declaration of the symbol under the cursor. + + Note: ~ + • Many servers do not implement this method. Generally, see + |vim.lsp.buf.definition()| instead. + + Parameters: ~ + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + +definition({opts}) *vim.lsp.buf.definition()* + Jumps to the definition of the symbol under the cursor. + + Parameters: ~ + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + +document_highlight() *vim.lsp.buf.document_highlight()* + Send request to the server to resolve document highlights for the current + text document position. This request can be triggered by a key mapping or + by events such as `CursorHold`, e.g.: >vim + autocmd CursorHold lua vim.lsp.buf.document_highlight() + autocmd CursorHoldI lua vim.lsp.buf.document_highlight() + autocmd CursorMoved lua vim.lsp.buf.clear_references() +< + + Note: Usage of |vim.lsp.buf.document_highlight()| requires the following + highlight groups to be defined or you won't be able to see the actual + highlights. |hl-LspReferenceText| |hl-LspReferenceRead| + |hl-LspReferenceWrite| + +document_symbol({opts}) *vim.lsp.buf.document_symbol()* + Lists all symbols in the current buffer in the |location-list|. + + Parameters: ~ + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + +format({opts}) *vim.lsp.buf.format()* + Formats a buffer using the attached (and optionally filtered) language + server clients. + + Parameters: ~ + • {opts} (`table?`) A table with the following fields: + • {formatting_options}? (`table`) Can be used to specify + FormattingOptions. Some unspecified options will be + automatically derived from the current Nvim options. See + https://microsoft.github.io/language-server-protocol/specification/#formattingOptions + • {timeout_ms}? (`integer`, default: `1000`) Time in + milliseconds to block for formatting requests. No effect if + async=true. + • {bufnr}? (`integer`, default: current buffer) Restrict + formatting to the clients attached to the given buffer. + • {filter}? (`fun(client: vim.lsp.Client): boolean?`) + Predicate used to filter clients. Receives a client as + argument and must return a boolean. Clients matching the + predicate are included. Example: >lua + -- Never request typescript-language-server for formatting + vim.lsp.buf.format { + filter = function(client) return client.name ~= "ts_ls" end + } +< + • {async}? (`boolean`, default: false) If true the method + won't block. Editing the buffer while formatting + asynchronous can lead to unexpected changes. + • {id}? (`integer`) Restrict formatting to the client with ID + (client.id) matching this field. + • {name}? (`string`) Restrict formatting to the client with + name (client.name) matching this field. + • {range}? + (`{start:[integer,integer],end:[integer, integer]}|{start:[integer,integer],end:[integer,integer]}[]`, + default: current selection in visual mode, `nil` in other + modes, formatting the full buffer) Range to format. Table + must contain `start` and `end` keys with {row,col} tuples + using (1,0) indexing. Can also be a list of tables that + contain `start` and `end` keys as described above, in which + case `textDocument/rangesFormatting` support is required. + +hover({config}) *vim.lsp.buf.hover()* + Displays hover information about the symbol under the cursor in a floating + window. The window will be dismissed on cursor move. Calling the function + twice will jump into the floating window (thus by default, "KK" will open + the hover window and focus it). In the floating window, all commands and + mappings are available as usual, except that "q" dismisses the window. You + can scroll the contents the same as you would any other buffer. + + Note: to disable hover highlights, add the following to your config: >lua + vim.api.nvim_create_autocmd('ColorScheme', { + callback = function() + vim.api.nvim_set_hl(0, 'LspReferenceTarget', {}) + end, + }) +< + + Parameters: ~ + • {config} (`vim.lsp.buf.hover.Opts?`) See |vim.lsp.buf.hover.Opts|. + +implementation({opts}) *vim.lsp.buf.implementation()* + Lists all the implementations for the symbol under the cursor in the + quickfix window. + + Parameters: ~ + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + +incoming_calls() *vim.lsp.buf.incoming_calls()* + Lists all the call sites of the symbol under the cursor in the |quickfix| + window. If the symbol can resolve to multiple items, the user can pick one + in the |inputlist()|. + +list_workspace_folders() *vim.lsp.buf.list_workspace_folders()* + List workspace folders. + +outgoing_calls() *vim.lsp.buf.outgoing_calls()* + Lists all the items that are called by the symbol under the cursor in the + |quickfix| window. If the symbol can resolve to multiple items, the user + can pick one in the |inputlist()|. + +references({context}, {opts}) *vim.lsp.buf.references()* + Lists all the references to the symbol under the cursor in the quickfix + window. + + Parameters: ~ + • {context} (`lsp.ReferenceContext?`) Context for the request + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + + See also: ~ + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references + + *vim.lsp.buf.remove_workspace_folder()* +remove_workspace_folder({workspace_folder}) + Remove the folder at path from the workspace folders. If {path} is not + provided, the user will be prompted for a path using |input()|. + + Parameters: ~ + • {workspace_folder} (`string?`) + +rename({new_name}, {opts}) *vim.lsp.buf.rename()* + Renames all references to the symbol under the cursor. + + Parameters: ~ + • {new_name} (`string?`) If not provided, the user will be prompted for + a new name using |vim.ui.input()|. + • {opts} (`table?`) Additional options: + • {filter}? (`fun(client: vim.lsp.Client): boolean?`) + Predicate used to filter clients. Receives a client as + argument and must return a boolean. Clients matching the + predicate are included. + • {name}? (`string`) Restrict clients used for rename to + ones where client.name matches this field. + • {bufnr}? (`integer`) (default: current buffer) + +selection_range({direction}) *vim.lsp.buf.selection_range()* + Perform an incremental selection at the cursor position based on ranges + given by the LSP. The `direction` parameter specifies the number of times + to expand the selection. Negative values will shrink the selection. + + Parameters: ~ + • {direction} (`integer`) + +signature_help({config}) *vim.lsp.buf.signature_help()* + Displays signature information about the symbol under the cursor in a + floating window. Allows cycling through signature overloads with ``, + which can be remapped via `(nvim.lsp.ctrl-s)` + + Example: >lua + vim.keymap.set('n', '', '(nvim.lsp.ctrl-s)') +< + + Parameters: ~ + • {config} (`vim.lsp.buf.signature_help.Opts?`) See + |vim.lsp.buf.signature_help.Opts|. + +type_definition({opts}) *vim.lsp.buf.type_definition()* + Jumps to the definition of the type of the symbol under the cursor. + + Parameters: ~ + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + +typehierarchy({kind}) *vim.lsp.buf.typehierarchy()* + Lists all the subtypes or supertypes of the symbol under the cursor in the + |quickfix| window. If the symbol can resolve to multiple items, the user + can pick one using |vim.ui.select()|. + + Parameters: ~ + • {kind} (`"subtypes"|"supertypes"`) + +workspace_diagnostics({opts}) *vim.lsp.buf.workspace_diagnostics()* + Request workspace-wide diagnostics. + + Parameters: ~ + • {opts} (`table?`) A table with the following fields: + • {client_id}? (`integer`) Only request diagnostics from the + indicated client. If nil, the request is sent to all + clients. + + See also: ~ + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_dagnostics + +workspace_symbol({query}, {opts}) *vim.lsp.buf.workspace_symbol()* + Lists all symbols in the current workspace in the quickfix window. + + The list is filtered against {query}; if the argument is omitted from the + call, the user is prompted to enter a string on the command line. An empty + string means no filtering is done. + + Parameters: ~ + • {query} (`string?`) optional + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + + ============================================================================== Lua module: vim.lsp.client *lsp-client* @@ -1601,365 +1909,6 @@ Client:supports_method({method}, {bufnr}) *Client:supports_method()* • {bufnr} (`integer?`) -============================================================================== -Lua module: vim.lsp.buf *lsp-buf* - -The `vim.lsp.buf_…` functions perform operations for LSP clients attached to -the current buffer. - - -*vim.lsp.ListOpts* - - Fields: ~ - • {on_list}? (`fun(t: vim.lsp.LocationOpts.OnList)`) list-handler - replacing the default handler. Called for any non-empty - result. This table can be used with |setqflist()| or - |setloclist()|. E.g.: >lua - local function on_list(options) - vim.fn.setqflist({}, ' ', options) - vim.cmd.cfirst() - end - - vim.lsp.buf.definition({ on_list = on_list }) - vim.lsp.buf.references(nil, { on_list = on_list }) -< - • {loclist}? (`boolean`) Whether to use the |location-list| or the - |quickfix| list in the default handler. >lua - vim.lsp.buf.definition({ loclist = true }) - vim.lsp.buf.references(nil, { loclist = false }) -< - -*vim.lsp.LocationOpts* - Extends: |vim.lsp.ListOpts| - - - Fields: ~ - • {reuse_win}? (`boolean`) Jump to existing window if buffer is already - open. - -*vim.lsp.LocationOpts.OnList* - - Fields: ~ - • {items} (`table[]`) Structured like |setqflist-what| - • {title}? (`string`) Title for the list. - • {context}? (`{ bufnr: integer, method: string }`) Subset of `ctx` - from |lsp-handler|. - -*vim.lsp.buf.hover.Opts* - Extends: |vim.lsp.util.open_floating_preview.Opts| - - - Fields: ~ - • {silent}? (`boolean`) - -*vim.lsp.buf.signature_help.Opts* - Extends: |vim.lsp.util.open_floating_preview.Opts| - - - Fields: ~ - • {silent}? (`boolean`) - - - *vim.lsp.buf.add_workspace_folder()* -add_workspace_folder({workspace_folder}) - Add the folder at path to the workspace folders. If {path} is not - provided, the user will be prompted for a path using |input()|. - - Parameters: ~ - • {workspace_folder} (`string?`) - -clear_references() *vim.lsp.buf.clear_references()* - Removes document highlights from current buffer. - -code_action({opts}) *vim.lsp.buf.code_action()* - Selects a code action (LSP: "textDocument/codeAction" request) available - at cursor position. - - Parameters: ~ - • {opts} (`table?`) A table with the following fields: - • {context}? (`lsp.CodeActionContext`) Corresponds to - `CodeActionContext` of the LSP specification: - • {diagnostics}? (`table`) LSP `Diagnostic[]`. Inferred from - the current position if not provided. - • {only}? (`table`) List of LSP `CodeActionKind`s used to - filter the code actions. Most language servers support - values like `refactor` or `quickfix`. - • {triggerKind}? (`integer`) The reason why code actions - were requested. - • {filter}? (`fun(x: lsp.CodeAction|lsp.Command):boolean`) - Predicate taking an `CodeAction` and returning a boolean. - • {apply}? (`boolean`) When set to `true`, and there is just - one remaining action (after filtering), the action is - applied without user query. - • {range}? (`{start: integer[], end: integer[]}`) Range for - which code actions should be requested. If in visual mode - this defaults to the active selection. Table must contain - `start` and `end` keys with {row,col} tuples using mark-like - indexing. See |api-indexing| - - See also: ~ - • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction - • vim.lsp.protocol.CodeActionTriggerKind - -declaration({opts}) *vim.lsp.buf.declaration()* - Jumps to the declaration of the symbol under the cursor. - - Note: ~ - • Many servers do not implement this method. Generally, see - |vim.lsp.buf.definition()| instead. - - Parameters: ~ - • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. - -definition({opts}) *vim.lsp.buf.definition()* - Jumps to the definition of the symbol under the cursor. - - Parameters: ~ - • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. - -document_highlight() *vim.lsp.buf.document_highlight()* - Send request to the server to resolve document highlights for the current - text document position. This request can be triggered by a key mapping or - by events such as `CursorHold`, e.g.: >vim - autocmd CursorHold lua vim.lsp.buf.document_highlight() - autocmd CursorHoldI lua vim.lsp.buf.document_highlight() - autocmd CursorMoved lua vim.lsp.buf.clear_references() -< - - Note: Usage of |vim.lsp.buf.document_highlight()| requires the following - highlight groups to be defined or you won't be able to see the actual - highlights. |hl-LspReferenceText| |hl-LspReferenceRead| - |hl-LspReferenceWrite| - -document_symbol({opts}) *vim.lsp.buf.document_symbol()* - Lists all symbols in the current buffer in the |location-list|. - - Parameters: ~ - • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. - -format({opts}) *vim.lsp.buf.format()* - Formats a buffer using the attached (and optionally filtered) language - server clients. - - Parameters: ~ - • {opts} (`table?`) A table with the following fields: - • {formatting_options}? (`table`) Can be used to specify - FormattingOptions. Some unspecified options will be - automatically derived from the current Nvim options. See - https://microsoft.github.io/language-server-protocol/specification/#formattingOptions - • {timeout_ms}? (`integer`, default: `1000`) Time in - milliseconds to block for formatting requests. No effect if - async=true. - • {bufnr}? (`integer`, default: current buffer) Restrict - formatting to the clients attached to the given buffer. - • {filter}? (`fun(client: vim.lsp.Client): boolean?`) - Predicate used to filter clients. Receives a client as - argument and must return a boolean. Clients matching the - predicate are included. Example: >lua - -- Never request typescript-language-server for formatting - vim.lsp.buf.format { - filter = function(client) return client.name ~= "ts_ls" end - } -< - • {async}? (`boolean`, default: false) If true the method - won't block. Editing the buffer while formatting - asynchronous can lead to unexpected changes. - • {id}? (`integer`) Restrict formatting to the client with ID - (client.id) matching this field. - • {name}? (`string`) Restrict formatting to the client with - name (client.name) matching this field. - • {range}? - (`{start:[integer,integer],end:[integer, integer]}|{start:[integer,integer],end:[integer,integer]}[]`, - default: current selection in visual mode, `nil` in other - modes, formatting the full buffer) Range to format. Table - must contain `start` and `end` keys with {row,col} tuples - using (1,0) indexing. Can also be a list of tables that - contain `start` and `end` keys as described above, in which - case `textDocument/rangesFormatting` support is required. - -hover({config}) *vim.lsp.buf.hover()* - Displays hover information about the symbol under the cursor in a floating - window. The window will be dismissed on cursor move. Calling the function - twice will jump into the floating window (thus by default, "KK" will open - the hover window and focus it). In the floating window, all commands and - mappings are available as usual, except that "q" dismisses the window. You - can scroll the contents the same as you would any other buffer. - - Note: to disable hover highlights, add the following to your config: >lua - vim.api.nvim_create_autocmd('ColorScheme', { - callback = function() - vim.api.nvim_set_hl(0, 'LspReferenceTarget', {}) - end, - }) -< - - Parameters: ~ - • {config} (`vim.lsp.buf.hover.Opts?`) See |vim.lsp.buf.hover.Opts|. - -implementation({opts}) *vim.lsp.buf.implementation()* - Lists all the implementations for the symbol under the cursor in the - quickfix window. - - Parameters: ~ - • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. - -incoming_calls() *vim.lsp.buf.incoming_calls()* - Lists all the call sites of the symbol under the cursor in the |quickfix| - window. If the symbol can resolve to multiple items, the user can pick one - in the |inputlist()|. - -list_workspace_folders() *vim.lsp.buf.list_workspace_folders()* - List workspace folders. - -outgoing_calls() *vim.lsp.buf.outgoing_calls()* - Lists all the items that are called by the symbol under the cursor in the - |quickfix| window. If the symbol can resolve to multiple items, the user - can pick one in the |inputlist()|. - -references({context}, {opts}) *vim.lsp.buf.references()* - Lists all the references to the symbol under the cursor in the quickfix - window. - - Parameters: ~ - • {context} (`lsp.ReferenceContext?`) Context for the request - • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. - - See also: ~ - • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references - - *vim.lsp.buf.remove_workspace_folder()* -remove_workspace_folder({workspace_folder}) - Remove the folder at path from the workspace folders. If {path} is not - provided, the user will be prompted for a path using |input()|. - - Parameters: ~ - • {workspace_folder} (`string?`) - -rename({new_name}, {opts}) *vim.lsp.buf.rename()* - Renames all references to the symbol under the cursor. - - Parameters: ~ - • {new_name} (`string?`) If not provided, the user will be prompted for - a new name using |vim.ui.input()|. - • {opts} (`table?`) Additional options: - • {filter}? (`fun(client: vim.lsp.Client): boolean?`) - Predicate used to filter clients. Receives a client as - argument and must return a boolean. Clients matching the - predicate are included. - • {name}? (`string`) Restrict clients used for rename to - ones where client.name matches this field. - • {bufnr}? (`integer`) (default: current buffer) - -selection_range({direction}) *vim.lsp.buf.selection_range()* - Perform an incremental selection at the cursor position based on ranges - given by the LSP. The `direction` parameter specifies the number of times - to expand the selection. Negative values will shrink the selection. - - Parameters: ~ - • {direction} (`integer`) - -signature_help({config}) *vim.lsp.buf.signature_help()* - Displays signature information about the symbol under the cursor in a - floating window. Allows cycling through signature overloads with ``, - which can be remapped via `(nvim.lsp.ctrl-s)` - - Example: >lua - vim.keymap.set('n', '', '(nvim.lsp.ctrl-s)') -< - - Parameters: ~ - • {config} (`vim.lsp.buf.signature_help.Opts?`) See - |vim.lsp.buf.signature_help.Opts|. - -type_definition({opts}) *vim.lsp.buf.type_definition()* - Jumps to the definition of the type of the symbol under the cursor. - - Parameters: ~ - • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. - -typehierarchy({kind}) *vim.lsp.buf.typehierarchy()* - Lists all the subtypes or supertypes of the symbol under the cursor in the - |quickfix| window. If the symbol can resolve to multiple items, the user - can pick one using |vim.ui.select()|. - - Parameters: ~ - • {kind} (`"subtypes"|"supertypes"`) - -workspace_diagnostics({opts}) *vim.lsp.buf.workspace_diagnostics()* - Request workspace-wide diagnostics. - - Parameters: ~ - • {opts} (`table?`) A table with the following fields: - • {client_id}? (`integer`) Only request diagnostics from the - indicated client. If nil, the request is sent to all - clients. - - See also: ~ - • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_dagnostics - -workspace_symbol({query}, {opts}) *vim.lsp.buf.workspace_symbol()* - Lists all symbols in the current workspace in the quickfix window. - - The list is filtered against {query}; if the argument is omitted from the - call, the user is prompted to enter a string on the command line. An empty - string means no filtering is done. - - Parameters: ~ - • {query} (`string?`) optional - • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. - - -============================================================================== -Lua module: vim.lsp.diagnostic *lsp-diagnostic* - -This module provides functionality for requesting LSP diagnostics for a -document/workspace and populating them using |vim.Diagnostic|s. -`DiagnosticRelatedInformation` is supported: it is included in the window -shown by |vim.diagnostic.open_float()|. When the cursor is on a line with -related information, |gf| jumps to the problem location. - - -from({diagnostics}) *vim.lsp.diagnostic.from()* - Converts the input `vim.Diagnostic`s to LSP diagnostics. - - Parameters: ~ - • {diagnostics} (`vim.Diagnostic[]`) - - Return: ~ - (`lsp.Diagnostic[]`) - - *vim.lsp.diagnostic.get_namespace()* -get_namespace({client_id}, {is_pull}) - Get the diagnostic namespace associated with an LSP client - |vim.diagnostic| for diagnostics - - Parameters: ~ - • {client_id} (`integer`) The id of the LSP client - • {is_pull} (`boolean?`) Whether the namespace is for a pull or push - client. Defaults to push - - *vim.lsp.diagnostic.on_diagnostic()* -on_diagnostic({error}, {result}, {ctx}) - |lsp-handler| for the method "textDocument/diagnostic" - - See |vim.diagnostic.config()| for configuration options. - - Parameters: ~ - • {error} (`lsp.ResponseError?`) - • {result} (`lsp.DocumentDiagnosticReport`) - • {ctx} (`lsp.HandlerContext`) - - *vim.lsp.diagnostic.on_publish_diagnostics()* -on_publish_diagnostics({_}, {params}, {ctx}) - |lsp-handler| for the method "textDocument/publishDiagnostics" - - See |vim.diagnostic.config()| for configuration options. - - Parameters: ~ - • {params} (`lsp.PublishDiagnosticsParams`) - • {ctx} (`lsp.HandlerContext`) - - ============================================================================== Lua module: vim.lsp.codelens *lsp-codelens* @@ -2112,6 +2061,107 @@ get({opts}) *vim.lsp.completion.get()* Defaults to a trigger kind of `invoked`. +============================================================================== +Lua module: vim.lsp.diagnostic *lsp-diagnostic* + +This module provides functionality for requesting LSP diagnostics for a +document/workspace and populating them using |vim.Diagnostic|s. +`DiagnosticRelatedInformation` is supported: it is included in the window +shown by |vim.diagnostic.open_float()|. When the cursor is on a line with +related information, |gf| jumps to the problem location. + + +from({diagnostics}) *vim.lsp.diagnostic.from()* + Converts the input `vim.Diagnostic`s to LSP diagnostics. + + Parameters: ~ + • {diagnostics} (`vim.Diagnostic[]`) + + Return: ~ + (`lsp.Diagnostic[]`) + + *vim.lsp.diagnostic.get_namespace()* +get_namespace({client_id}, {is_pull}) + Get the diagnostic namespace associated with an LSP client + |vim.diagnostic| for diagnostics + + Parameters: ~ + • {client_id} (`integer`) The id of the LSP client + • {is_pull} (`boolean?`) Whether the namespace is for a pull or push + client. Defaults to push + + *vim.lsp.diagnostic.on_diagnostic()* +on_diagnostic({error}, {result}, {ctx}) + |lsp-handler| for the method "textDocument/diagnostic" + + See |vim.diagnostic.config()| for configuration options. + + Parameters: ~ + • {error} (`lsp.ResponseError?`) + • {result} (`lsp.DocumentDiagnosticReport`) + • {ctx} (`lsp.HandlerContext`) + + *vim.lsp.diagnostic.on_publish_diagnostics()* +on_publish_diagnostics({_}, {params}, {ctx}) + |lsp-handler| for the method "textDocument/publishDiagnostics" + + See |vim.diagnostic.config()| for configuration options. + + Parameters: ~ + • {params} (`lsp.PublishDiagnosticsParams`) + • {ctx} (`lsp.HandlerContext`) + + +============================================================================== +Lua module: vim.lsp.document_color *lsp-document_color* + +This module provides LSP support for highlighting color references in a +document. Highlighting is enabled by default. + + +color_presentation() *vim.lsp.document_color.color_presentation()* + Select from a list of presentations for the color under the cursor. + +enable({enable}, {bufnr}, {opts}) *vim.lsp.document_color.enable()* + Enables document highlighting from the given language client in the given + buffer. + + You can enable document highlighting when a client attaches to a buffer as + follows: >lua + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(args) + vim.lsp.document_color.enable(true, args.buf) + end + }) +< + + To "toggle", pass the inverse of `is_enabled()`: >lua + vim.lsp.document_color.enable(not vim.lsp.document_color.is_enabled()) +< + + Parameters: ~ + • {enable} (`boolean?`) True to enable, false to disable. (default: + `true`) + • {bufnr} (`integer?`) Buffer handle, or 0 for current. (default: 0) + • {opts} (`table?`) A table with the following fields: + • {style}? + (`'background'|'foreground'|'virtual'|string|fun(bufnr: integer, range: Range4, hex_code: string)`) + Highlight style. It can be one of the pre-defined styles, + a string to be used as virtual text, or a function that + receives the buffer handle, the range (start line, start + col, end line, end col) and the resolved hex color. + (default: `'background'`) + +is_enabled({bufnr}) *vim.lsp.document_color.is_enabled()* + Query whether document colors are enabled in the given buffer. + + Parameters: ~ + • {bufnr} (`integer?`) Buffer handle, or 0 for current. (default: 0) + + Return: ~ + (`boolean`) + + ============================================================================== Lua module: vim.lsp.inlay_hint *lsp-inlay_hint* @@ -2178,6 +2228,206 @@ is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()* (`boolean`) +============================================================================== +Lua module: vim.lsp.linked_editing_range *lsp-linked_editing_range* + +The `vim.lsp.linked_editing_range` module enables "linked editing" via a +language server's `textDocument/linkedEditingRange` request. Linked editing +ranges are synchronized text regions, meaning changes in one range are +mirrored in all the others. This is helpful in HTML files for example, where +the language server can update the text of a closing tag if its opening tag +was changed. + +LSP spec: +https://microsoft.github.io/language-server-protocol/specification/#textDocument_linkedEditingRange + + +enable({enable}, {filter}) *vim.lsp.linked_editing_range.enable()* + Enable or disable a linked editing session globally or for a specific + client. The following is a practical usage example: >lua + vim.lsp.start({ + name = 'html', + cmd = '…', + on_attach = function(client) + vim.lsp.linked_editing_range.enable(true, { client_id = client.id }) + end, + }) +< + + Parameters: ~ + • {enable} (`boolean?`) `true` or `nil` to enable, `false` to disable. + • {filter} (`table?`) Optional filters |kwargs|: + • {client_id} (`integer?`) Client ID, or `nil` for all. + + +============================================================================== +Lua module: vim.lsp.log *lsp-log* + +The `vim.lsp.log` module provides logging for the Nvim LSP client. + +When debugging language servers, it is helpful to enable extra-verbose logging +of the LSP client RPC events. Example: >lua + vim.lsp.set_log_level 'trace' + require('vim.lsp.log').set_format_func(vim.inspect) +< + +Then try to run the language server, and open the log with: >vim + :lua vim.cmd('tabnew ' .. vim.lsp.get_log_path()) +< + +(Or use `:LspLog` if you have nvim-lspconfig installed.) + +Note: +• Remember to DISABLE verbose logging ("debug" or "trace" level), else you may + encounter performance issues. +• "ERROR" messages containing "stderr" only indicate that the log was sent to + stderr. Many servers send harmless messages via stderr. + + +get_filename() *vim.lsp.log.get_filename()* + Returns the log filename. + + Return: ~ + (`string`) log filename + +get_level() *vim.lsp.log.get_level()* + Gets the current log level. + + Return: ~ + (`integer`) current log level + +set_format_func({handle}) *vim.lsp.log.set_format_func()* + Sets the formatting function used to format logs. If the formatting + function returns nil, the entry won't be written to the log file. + + Parameters: ~ + • {handle} (`fun(level:string, ...): string?`) Function to apply to log + entries. The default will log the level, date, source and + line number of the caller, followed by the arguments. + +set_level({level}) *vim.lsp.log.set_level()* + Sets the current log level. + + Parameters: ~ + • {level} (`string|integer`) One of |vim.log.levels| + + +============================================================================== +Lua module: vim.lsp.rpc *lsp-rpc* + +*vim.lsp.rpc.PublicClient* + Client RPC object + + Fields: ~ + • {request} (`fun(method: string, params: table?, callback: fun(err?: lsp.ResponseError, result: any), notify_reply_callback?: fun(message_id: integer)):boolean,integer?`) + See |vim.lsp.rpc.request()| + • {notify} (`fun(method: string, params: any): boolean`) See + |vim.lsp.rpc.notify()| + • {is_closing} (`fun(): boolean`) Indicates if the RPC is closing. + • {terminate} (`fun()`) Terminates the RPC client. + + +connect({host_or_path}, {port}) *vim.lsp.rpc.connect()* + Create a LSP RPC client factory that connects to either: + • a named pipe (windows) + • a domain socket (unix) + • a host and port via TCP + + Return a function that can be passed to the `cmd` field for + |vim.lsp.start()|. + + Parameters: ~ + • {host_or_path} (`string`) host to connect to or path to a pipe/domain + socket + • {port} (`integer?`) TCP port to connect to. If absent the + first argument must be a pipe + + Return: ~ + (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) + +format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()* + Constructs an error message from an LSP error object. + + Parameters: ~ + • {err} (`table`) The error object + + Return: ~ + (`string`) error_message The formatted error message + +notify({method}, {params}) *vim.lsp.rpc.notify()* + Sends a notification to the LSP server. + + Parameters: ~ + • {method} (`string`) The invoked LSP method + • {params} (`table?`) Parameters for the invoked LSP method + + Return: ~ + (`boolean`) `true` if notification could be sent, `false` if not + + *vim.lsp.rpc.request()* +request({method}, {params}, {callback}, {notify_reply_callback}) + Sends a request to the LSP server and runs {callback} upon response. + + Parameters: ~ + • {method} (`string`) The invoked LSP method + • {params} (`table?`) Parameters for the invoked LSP + method + • {callback} (`fun(err: lsp.ResponseError?, result: any)`) + Callback to invoke + • {notify_reply_callback} (`fun(message_id: integer)?`) Callback to + invoke as soon as a request is no longer + pending + + Return (multiple): ~ + (`boolean`) success `true` if request could be sent, `false` if not + (`integer?`) message_id if request could be sent, `nil` if not + + *vim.lsp.rpc.rpc_response_error()* +rpc_response_error({code}, {message}, {data}) + Creates an RPC response table `error` to be sent to the LSP response. + + Parameters: ~ + • {code} (`integer`) RPC error code defined, see + `vim.lsp.protocol.ErrorCodes` + • {message} (`string?`) arbitrary message to send to server + • {data} (`any?`) arbitrary data to send to server + + Return: ~ + (`lsp.ResponseError`) + + See also: ~ + • lsp.ErrorCodes See `vim.lsp.protocol.ErrorCodes` + +start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* + Starts an LSP server process and create an LSP RPC client object to + interact with it. Communication with the spawned process happens via + stdio. For communication via TCP, spawn a process manually and use + |vim.lsp.rpc.connect()| + + Parameters: ~ + • {cmd} (`string[]`) Command to start the LSP server. + • {dispatchers} (`table?`) Dispatchers for LSP message types. + • {notification} + (`fun(method: string, params: table)`) + • {server_request} + (`fun(method: string, params: table): any?, lsp.ResponseError?`) + • {on_exit} + (`fun(code: integer, signal: integer)`) + • {on_error} (`fun(code: integer, err: any)`) + • {extra_spawn_params} (`table?`) Additional context for the LSP server + process. + • {cwd}? (`string`) Working directory for the + LSP server process + • {detached}? (`boolean`) Detach the LSP server + process from the current process + • {env}? (`table`) Additional + environment variables for LSP server process. + See |vim.system()| + + Return: ~ + (`vim.lsp.rpc.PublicClient`) See |vim.lsp.rpc.PublicClient|. + + ============================================================================== Lua module: vim.lsp.semantic_tokens *lsp-semantic_tokens* @@ -2258,88 +2508,6 @@ is_enabled({filter}) *vim.lsp.semantic_tokens.is_enabled()* • {client_id}? (`integer`) Client ID, or nil for all -============================================================================== -Lua module: vim.lsp.document_color *lsp-document_color* - -This module provides LSP support for highlighting color references in a -document. Highlighting is enabled by default. - - -color_presentation() *vim.lsp.document_color.color_presentation()* - Select from a list of presentations for the color under the cursor. - -enable({enable}, {bufnr}, {opts}) *vim.lsp.document_color.enable()* - Enables document highlighting from the given language client in the given - buffer. - - You can enable document highlighting when a client attaches to a buffer as - follows: >lua - vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - vim.lsp.document_color.enable(true, args.buf) - end - }) -< - - To "toggle", pass the inverse of `is_enabled()`: >lua - vim.lsp.document_color.enable(not vim.lsp.document_color.is_enabled()) -< - - Parameters: ~ - • {enable} (`boolean?`) True to enable, false to disable. (default: - `true`) - • {bufnr} (`integer?`) Buffer handle, or 0 for current. (default: 0) - • {opts} (`table?`) A table with the following fields: - • {style}? - (`'background'|'foreground'|'virtual'|string|fun(bufnr: integer, range: Range4, hex_code: string)`) - Highlight style. It can be one of the pre-defined styles, - a string to be used as virtual text, or a function that - receives the buffer handle, the range (start line, start - col, end line, end col) and the resolved hex color. - (default: `'background'`) - -is_enabled({bufnr}) *vim.lsp.document_color.is_enabled()* - Query whether document colors are enabled in the given buffer. - - Parameters: ~ - • {bufnr} (`integer?`) Buffer handle, or 0 for current. (default: 0) - - Return: ~ - (`boolean`) - - -============================================================================== -Lua module: vim.lsp.linked_editing_range *lsp-linked_editing_range* - -The `vim.lsp.linked_editing_range` module enables "linked editing" via a -language server's `textDocument/linkedEditingRange` request. Linked editing -ranges are synchronized text regions, meaning changes in one range are -mirrored in all the others. This is helpful in HTML files for example, where -the language server can update the text of a closing tag if its opening tag -was changed. - -LSP spec: -https://microsoft.github.io/language-server-protocol/specification/#textDocument_linkedEditingRange - - -enable({enable}, {filter}) *vim.lsp.linked_editing_range.enable()* - Enable or disable a linked editing session globally or for a specific - client. The following is a practical usage example: >lua - vim.lsp.start({ - name = 'html', - cmd = '…', - on_attach = function(client) - vim.lsp.linked_editing_range.enable(true, { client_id = client.id }) - end, - }) -< - - Parameters: ~ - • {enable} (`boolean?`) `true` or `nil` to enable, `false` to disable. - • {filter} (`table?`) Optional filters |kwargs|: - • {client_id} (`integer?`) Client ID, or `nil` for all. - - ============================================================================== Lua module: vim.lsp.util *lsp-util* @@ -2715,174 +2883,6 @@ symbols_to_items({symbols}, {bufnr}, {position_encoding}) (`vim.quickfix.entry[]`) See |setqflist()| for the format -============================================================================== -Lua module: vim.lsp.log *lsp-log* - -The `vim.lsp.log` module provides logging for the Nvim LSP client. - -When debugging language servers, it is helpful to enable extra-verbose logging -of the LSP client RPC events. Example: >lua - vim.lsp.set_log_level 'trace' - require('vim.lsp.log').set_format_func(vim.inspect) -< - -Then try to run the language server, and open the log with: >vim - :lua vim.cmd('tabnew ' .. vim.lsp.get_log_path()) -< - -(Or use `:LspLog` if you have nvim-lspconfig installed.) - -Note: -• Remember to DISABLE verbose logging ("debug" or "trace" level), else you may - encounter performance issues. -• "ERROR" messages containing "stderr" only indicate that the log was sent to - stderr. Many servers send harmless messages via stderr. - - -get_filename() *vim.lsp.log.get_filename()* - Returns the log filename. - - Return: ~ - (`string`) log filename - -get_level() *vim.lsp.log.get_level()* - Gets the current log level. - - Return: ~ - (`integer`) current log level - -set_format_func({handle}) *vim.lsp.log.set_format_func()* - Sets the formatting function used to format logs. If the formatting - function returns nil, the entry won't be written to the log file. - - Parameters: ~ - • {handle} (`fun(level:string, ...): string?`) Function to apply to log - entries. The default will log the level, date, source and - line number of the caller, followed by the arguments. - -set_level({level}) *vim.lsp.log.set_level()* - Sets the current log level. - - Parameters: ~ - • {level} (`string|integer`) One of |vim.log.levels| - - -============================================================================== -Lua module: vim.lsp.rpc *lsp-rpc* - -*vim.lsp.rpc.PublicClient* - Client RPC object - - Fields: ~ - • {request} (`fun(method: string, params: table?, callback: fun(err?: lsp.ResponseError, result: any), notify_reply_callback?: fun(message_id: integer)):boolean,integer?`) - See |vim.lsp.rpc.request()| - • {notify} (`fun(method: string, params: any): boolean`) See - |vim.lsp.rpc.notify()| - • {is_closing} (`fun(): boolean`) Indicates if the RPC is closing. - • {terminate} (`fun()`) Terminates the RPC client. - - -connect({host_or_path}, {port}) *vim.lsp.rpc.connect()* - Create a LSP RPC client factory that connects to either: - • a named pipe (windows) - • a domain socket (unix) - • a host and port via TCP - - Return a function that can be passed to the `cmd` field for - |vim.lsp.start()|. - - Parameters: ~ - • {host_or_path} (`string`) host to connect to or path to a pipe/domain - socket - • {port} (`integer?`) TCP port to connect to. If absent the - first argument must be a pipe - - Return: ~ - (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) - -format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()* - Constructs an error message from an LSP error object. - - Parameters: ~ - • {err} (`table`) The error object - - Return: ~ - (`string`) error_message The formatted error message - -notify({method}, {params}) *vim.lsp.rpc.notify()* - Sends a notification to the LSP server. - - Parameters: ~ - • {method} (`string`) The invoked LSP method - • {params} (`table?`) Parameters for the invoked LSP method - - Return: ~ - (`boolean`) `true` if notification could be sent, `false` if not - - *vim.lsp.rpc.request()* -request({method}, {params}, {callback}, {notify_reply_callback}) - Sends a request to the LSP server and runs {callback} upon response. - - Parameters: ~ - • {method} (`string`) The invoked LSP method - • {params} (`table?`) Parameters for the invoked LSP - method - • {callback} (`fun(err: lsp.ResponseError?, result: any)`) - Callback to invoke - • {notify_reply_callback} (`fun(message_id: integer)?`) Callback to - invoke as soon as a request is no longer - pending - - Return (multiple): ~ - (`boolean`) success `true` if request could be sent, `false` if not - (`integer?`) message_id if request could be sent, `nil` if not - - *vim.lsp.rpc.rpc_response_error()* -rpc_response_error({code}, {message}, {data}) - Creates an RPC response table `error` to be sent to the LSP response. - - Parameters: ~ - • {code} (`integer`) RPC error code defined, see - `vim.lsp.protocol.ErrorCodes` - • {message} (`string?`) arbitrary message to send to server - • {data} (`any?`) arbitrary data to send to server - - Return: ~ - (`lsp.ResponseError`) - - See also: ~ - • lsp.ErrorCodes See `vim.lsp.protocol.ErrorCodes` - -start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* - Starts an LSP server process and create an LSP RPC client object to - interact with it. Communication with the spawned process happens via - stdio. For communication via TCP, spawn a process manually and use - |vim.lsp.rpc.connect()| - - Parameters: ~ - • {cmd} (`string[]`) Command to start the LSP server. - • {dispatchers} (`table?`) Dispatchers for LSP message types. - • {notification} - (`fun(method: string, params: table)`) - • {server_request} - (`fun(method: string, params: table): any?, lsp.ResponseError?`) - • {on_exit} - (`fun(code: integer, signal: integer)`) - • {on_error} (`fun(code: integer, err: any)`) - • {extra_spawn_params} (`table?`) Additional context for the LSP server - process. - • {cwd}? (`string`) Working directory for the - LSP server process - • {detached}? (`boolean`) Detach the LSP server - process from the current process - • {env}? (`table`) Additional - environment variables for LSP server process. - See |vim.system()| - - Return: ~ - (`vim.lsp.rpc.PublicClient`) See |vim.lsp.rpc.PublicClient|. - - ============================================================================== Lua module: vim.lsp.protocol *lsp-protocol* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index b8635b2e43..f546404f85 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -592,189 +592,6 @@ A subset of the `vim.*` stdlib is available in threads, including: - `vim.is_thread()` returns true from a non-main thread. -============================================================================== -VIM.HL *vim.hl* - -vim.hl.on_yank({opts}) *vim.hl.on_yank()* - Highlight the yanked text during a |TextYankPost| event. - - Add the following to your `init.vim`: >vim - autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300} -< - - Parameters: ~ - • {opts} (`table?`) Optional parameters - • higroup highlight group for yanked region (default - "IncSearch") - • timeout time in ms before highlight is cleared (default 150) - • on_macro highlight when executing macro (default false) - • on_visual highlight when yanking visual selection (default - true) - • event event structure (default vim.v.event) - • priority integer priority (default - |vim.hl.priorities|`.user`) - -vim.hl.priorities *vim.hl.priorities* - Table with default priorities used for highlighting: - • `syntax`: `50`, used for standard syntax highlighting - • `treesitter`: `100`, used for treesitter-based highlighting - • `semantic_tokens`: `125`, used for LSP semantic token highlighting - • `diagnostics`: `150`, used for code analysis such as diagnostics - • `user`: `200`, used for user-triggered highlights such as LSP document - symbols or `on_yank` autocommands - - *vim.hl.range()* -vim.hl.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) - Apply highlight group to range of text. - - Parameters: ~ - • {bufnr} (`integer`) Buffer number to apply highlighting to - • {ns} (`integer`) Namespace to add highlight to - • {higroup} (`string`) Highlight group to use for highlighting - • {start} (`[integer,integer]|string`) Start of region as a (line, - column) tuple or string accepted by |getpos()| - • {finish} (`[integer,integer]|string`) End of region as a (line, - column) tuple or string accepted by |getpos()| - • {opts} (`table?`) A table with the following fields: - • {regtype}? (`string`, default: `'v'` i.e. charwise) Type - of range. See |getregtype()| - • {inclusive}? (`boolean`, default: `false`) Indicates - whether the range is end-inclusive - • {priority}? (`integer`, default: - `vim.hl.priorities.user`) Highlight priority - • {timeout}? (`integer`, default: -1 no timeout) Time in ms - before highlight is cleared - - Return (multiple): ~ - (`uv.uv_timer_t?`) range_timer A timer which manages how much time the - highlight has left - (`fun()?`) range_clear A function which allows clearing the highlight - manually. nil is returned if timeout is not specified - - -============================================================================== -VIM.MPACK *vim.mpack* - -This module provides encoding and decoding of Lua objects to and from -msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. - - -vim.mpack.decode({str}) *vim.mpack.decode()* - Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. - - Parameters: ~ - • {str} (`string`) - - Return: ~ - (`any`) - -vim.mpack.encode({obj}) *vim.mpack.encode()* - Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. - - Parameters: ~ - • {obj} (`any`) - - Return: ~ - (`string`) - - -============================================================================== -VIM.JSON *vim.json* - -This module provides encoding and decoding of Lua objects to and from -JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. - - -vim.json.decode({str}, {opts}) *vim.json.decode()* - Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. - • Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below). - • Decodes empty object as |vim.empty_dict()|. - • Decodes empty array as `{}` (empty Lua table). - - Example: >lua - vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) - -- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } -< - - Parameters: ~ - • {str} (`string`) Stringified JSON data. - • {opts} (`table?`) 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|. - - Return: ~ - (`any`) - -vim.json.encode({obj}, {opts}) *vim.json.encode()* - Encodes (or "packs") Lua object {obj} as JSON in a Lua string. - - Parameters: ~ - • {obj} (`any`) - • {opts} (`table?`) Options table with keys: - • escape_slash: (boolean) (default false) Escape slash - characters "/" in string values. - - Return: ~ - (`string`) - - -============================================================================== -VIM.BASE64 *vim.base64* - -vim.base64.decode({str}) *vim.base64.decode()* - Decode a Base64 encoded string. - - Parameters: ~ - • {str} (`string`) Base64 encoded string - - Return: ~ - (`string`) Decoded string - -vim.base64.encode({str}) *vim.base64.encode()* - Encode {str} using Base64. - - Parameters: ~ - • {str} (`string`) String to encode - - Return: ~ - (`string`) Encoded string - - -============================================================================== -VIM.SPELL *vim.spell* - -vim.spell.check({str}) *vim.spell.check()* - Check {str} for spelling errors. Similar to the Vimscript function - |spellbadword()|. - - Note: The behaviour of this function is dependent on: 'spelllang', - 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to - the buffer. Consider calling this with |nvim_buf_call()|. - - Example: >lua - vim.spell.check("the quik brown fox") - -- => - -- { - -- {'quik', 'bad', 5} - -- } -< - - Parameters: ~ - • {str} (`string`) - - Return: ~ - (`[string, 'bad'|'rare'|'local'|'caps', integer][]`) List of tuples - with three items: - • The badly spelled word. - • The type of the spelling error: "bad" spelling mistake "rare" rare - word "local" word only valid in another region "caps" word should - start with Capital - • The position in {str} where the word begins. - - ============================================================================== VIM *vim.builtin* @@ -1692,169 +1509,6 @@ vim.str_utfindex({s}, {encoding}, {index}, {strict_indexing}) (`integer`) -============================================================================== -Lua module: vim.system *lua-vim-system* - -*vim.SystemCompleted* - - Fields: ~ - • {code} (`integer`) - • {signal} (`integer`) - • {stdout}? (`string`) `nil` if stdout is disabled or has a custom - handler. - • {stderr}? (`string`) `nil` if stderr is disabled or has a custom - handler. - -*vim.SystemObj* - - Fields: ~ - • {cmd} (`string[]`) Command name and args - • {pid} (`integer`) Process ID - • {kill} (`fun(self: vim.SystemObj, signal: integer|string)`) See - |SystemObj:kill()|. - • {wait} (`fun(self: vim.SystemObj, timeout: integer?): vim.SystemCompleted`) - See |SystemObj:wait()|. - • {write} (`fun(self: vim.SystemObj, data: string[]|string?)`) See - |SystemObj:write()|. - • {is_closing} (`fun(self: vim.SystemObj): boolean`) See - |SystemObj:is_closing()|. - - -SystemObj:is_closing() *SystemObj:is_closing()* - Checks if the process handle is closing or already closed. - - This method returns `true` if the underlying process handle is either - `nil` or is in the process of closing. It is useful for determining - whether it is safe to perform operations on the process handle. - - Return: ~ - (`boolean`) - -SystemObj:kill({signal}) *SystemObj:kill()* - Sends a signal to the process. - - The signal can be specified as an integer or as a string. - - Example: >lua - local obj = vim.system({'sleep', '10'}) - obj:kill('TERM') -- sends SIGTERM to the process -< - - Parameters: ~ - • {signal} (`integer|string`) Signal to send to the process. - -SystemObj:wait({timeout}) *SystemObj:wait()* - Waits for the process to complete or until the specified timeout elapses. - - This method blocks execution until the associated process has exited or - the optional `timeout` (in milliseconds) has been reached. If the process - does not exit before the timeout, it is forcefully terminated with SIGKILL - (signal 9), and the exit code is set to 124. - - If no `timeout` is provided, the method will wait indefinitely (or use the - timeout specified in the options when the process was started). - - Example: >lua - local obj = vim.system({'echo', 'hello'}, { text = true }) - local result = obj:wait(1000) -- waits up to 1000ms - print(result.code, result.signal, result.stdout, result.stderr) -< - - Parameters: ~ - • {timeout} (`integer?`) - - Return: ~ - (`vim.SystemCompleted`) See |vim.SystemCompleted|. - -SystemObj:write({data}) *SystemObj:write()* - Writes data to the stdin of the process or closes stdin. - - If `data` is a list of strings, each string is written followed by a - newline. - - If `data` is a string, it is written as-is. - - If `data` is `nil`, the write side of the stream is shut down and the pipe - is closed. - - Example: >lua - local obj = vim.system({'cat'}, { stdin = true }) - obj:write({'hello', 'world'}) -- writes 'hello\nworld\n' to stdin - obj:write(nil) -- closes stdin -< - - Parameters: ~ - • {data} (`string[]|string?`) - -vim.system({cmd}, {opts}, {on_exit}) *vim.system()* - Runs a system command or throws an error if {cmd} cannot be run. - - The command runs directly (not in 'shell') so shell builtins such as - "echo" in cmd.exe, cmdlets in powershell, or "help" in bash, will not work - unless you actually invoke a shell: `vim.system({'bash', '-c', 'help'})`. - - Examples: >lua - local on_exit = function(obj) - print(obj.code) - print(obj.signal) - print(obj.stdout) - print(obj.stderr) - end - - -- Runs asynchronously: - vim.system({'echo', 'hello'}, { text = true }, on_exit) - - -- Runs synchronously: - local obj = vim.system({'echo', 'hello'}, { text = true }):wait() - -- { code = 0, signal = 0, stdout = 'hello\n', stderr = '' } -< - - See |uv.spawn()| for more details. Note: unlike |uv.spawn()|, vim.system - throws an error if {cmd} cannot be run. - - Parameters: ~ - • {cmd} (`string[]`) Command to execute - • {opts} (`table?`) A table with the following fields: - • {cwd}? (`string`) Set the current working directory for - the sub-process. - • {env}? (`table`) Set environment - variables for the new process. Inherits the current - environment with `NVIM` set to |v:servername|. - • {clear_env}? (`boolean`) `env` defines the job - environment exactly, instead of merging current - environment. Note: if `env` is `nil`, the current - environment is used but without `NVIM` set. - • {stdin}? (`string|string[]|true`) If `true`, then a pipe - to stdin is opened and can be written to via the - `write()` method to SystemObj. If `string` or `string[]` - then will be written to stdin and closed. - • {stdout}? (`fun(err:string?, data: string?)|boolean`, - default: `true`) Handle output from stdout. - • {stderr}? (`fun(err:string?, data: string?)|boolean`, - default: `true`) Handle output from stderr. - • {text}? (`boolean`) Handle stdout and stderr as text. - Normalizes line endings by replacing `\r\n` with `\n`. - • {timeout}? (`integer`) Run the command with a time limit - in ms. Upon timeout the process is sent the TERM signal - (15) and the exit code is set to 124. - • {detach}? (`boolean`) Spawn the child process in a - detached state - this will make it a process group - leader, and will effectively enable the child to keep - running after the parent exits. Note that the child - process will still keep the parent's event loop alive - unless the parent process calls |uv.unref()| on the - child's process handle. - • {on_exit} (`fun(out: vim.SystemCompleted)?`) Called when subprocess - exits. When provided, the command runs asynchronously. See - return of SystemObj:wait(). - - Overloads: ~ - • `fun(cmd: string, on_exit: fun(out: vim.SystemCompleted)): vim.SystemObj` - - Return: ~ - (`vim.SystemObj`) See |vim.SystemObj|. - - ============================================================================== Lua module: vim.inspector *vim.inspector* @@ -2517,255 +2171,26 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) ============================================================================== -Lua module: vim.loader *vim.loader* +Lua module: vim.base64 *vim.base64* -vim.loader.enable({enable}) *vim.loader.enable()* - WARNING: This feature is experimental/unstable. - - Enables or disables the experimental Lua module loader: - - Enable (`enable=true`): - • overrides |loadfile()| - • adds the Lua loader using the byte-compilation cache - • adds the libs loader - • removes the default Nvim loader - - Disable (`enable=false`): - • removes the loaders - • adds the default Nvim loader +vim.base64.decode({str}) *vim.base64.decode()* + Decode a Base64 encoded string. Parameters: ~ - • {enable} (`boolean?`) true/nil to enable, false to disable - -vim.loader.find({modname}, {opts}) *vim.loader.find()* - WARNING: This feature is experimental/unstable. - - Finds Lua modules for the given module name. - - Parameters: ~ - • {modname} (`string`) Module name, or `"*"` to find the top-level - modules instead - • {opts} (`table?`) Options for finding a module: - • {rtp}? (`boolean`, default: `true`) Search for modname in - the runtime path. - • {paths}? (`string[]`, default: `{}`) Extra paths to - search for modname - • {patterns}? (`string[]`, default: - `{"/init.lua", ".lua"}`) List of patterns to use when - searching for modules. A pattern is a string added to the - basename of the Lua module being searched. - • {all}? (`boolean`, default: `false`) Search for all - matches. + • {str} (`string`) Base64 encoded string Return: ~ - (`table[]`) A list of objects with the following fields: - • {modpath} (`string`) Path of the module - • {modname} (`string`) Name of the module - • {stat}? (`uv.fs_stat.result`) The fs_stat of the module path. Won't - be returned for `modname="*"` + (`string`) Decoded string -vim.loader.reset({path}) *vim.loader.reset()* - WARNING: This feature is experimental/unstable. - - Resets the cache for the path, or all the paths if path is nil. +vim.base64.encode({str}) *vim.base64.encode()* + Encode {str} using Base64. Parameters: ~ - • {path} (`string?`) path to reset - - -============================================================================== -Lua module: vim.uri *vim.uri* - -vim.uri_decode({str}) *vim.uri_decode()* - URI-decodes a string containing percent escapes. - - Parameters: ~ - • {str} (`string`) string to decode + • {str} (`string`) String to encode Return: ~ - (`string`) decoded string + (`string`) Encoded string -vim.uri_encode({str}, {rfc}) *vim.uri_encode()* - URI-encodes a string using percent escapes. - - Parameters: ~ - • {str} (`string`) string to encode - • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`) - - Return: ~ - (`string`) encoded string - -vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* - Gets a URI from a bufnr. - - Parameters: ~ - • {bufnr} (`integer`) - - Return: ~ - (`string`) URI - -vim.uri_from_fname({path}) *vim.uri_from_fname()* - Gets a URI from a file path. - - Parameters: ~ - • {path} (`string`) Path to file - - Return: ~ - (`string`) URI - -vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()* - Gets the buffer for a uri. Creates a new unloaded buffer if no buffer for - the uri already exists. - - Parameters: ~ - • {uri} (`string`) - - Return: ~ - (`integer`) bufnr - -vim.uri_to_fname({uri}) *vim.uri_to_fname()* - Gets a filename from a URI. - - Parameters: ~ - • {uri} (`string`) - - Return: ~ - (`string`) filename or unchanged URI for non-file URIs - - -============================================================================== -Lua module: vim.ui *vim.ui* - -vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* - Prompts the user for input, allowing arbitrary (potentially asynchronous) - work until `on_confirm`. - - Example: >lua - vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) - vim.o.shiftwidth = tonumber(input) - end) -< - - Parameters: ~ - • {opts} (`table?`) Additional options. See |input()| - • {prompt}? (`string`) Text of the prompt - • {default}? (`string`) Default reply to the input - • {completion}? (`string`) Specifies type of completion - supported for input. Supported types are the same that - can be supplied to a user-defined command using the - "-complete=" argument. See |:command-completion| - • {highlight}? (`function`) Function that will be used - for highlighting user inputs. - • {on_confirm} (`fun(input?: string)`) Called once the user confirms or - abort the input. `input` is what the user typed (it - might be an empty string if nothing was entered), or - `nil` if the user aborted the dialog. - -vim.ui.open({path}, {opt}) *vim.ui.open()* - Opens `path` with the system default handler (macOS `open`, Windows - `explorer.exe`, Linux `xdg-open`, …), or returns (but does not show) an - error message on failure. - - Can also be invoked with `:Open`. *:Open* - - Expands "~/" and environment variables in filesystem paths. - - Examples: >lua - -- Asynchronous. - vim.ui.open("https://neovim.io/") - vim.ui.open("~/path/to/file") - -- Use the "osurl" command to handle the path or URL. - vim.ui.open("gh#neovim/neovim!29490", { cmd = { 'osurl' } }) - -- Synchronous (wait until the process exits). - local cmd, err = vim.ui.open("$VIMRUNTIME") - if cmd then - cmd:wait() - end -< - - Parameters: ~ - • {path} (`string`) Path or URL to open - • {opt} (`table?`) Options - • {cmd}? (`string[]`) Command used to open the path or URL. - - Return (multiple): ~ - (`vim.SystemObj?`) Command object, or nil if not found. See - |vim.SystemObj|. - (`string?`) Error message on failure, or nil on success. - - See also: ~ - • |vim.system()| - -vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* - Prompts the user to pick from a list of items, allowing arbitrary - (potentially asynchronous) work until `on_choice`. - - Example: >lua - vim.ui.select({ 'tabs', 'spaces' }, { - prompt = 'Select tabs or spaces:', - format_item = function(item) - return "I'd like to choose " .. item - end, - }, function(choice) - if choice == 'spaces' then - vim.o.expandtab = true - else - vim.o.expandtab = false - end - end) -< - - Parameters: ~ - • {items} (`any[]`) Arbitrary items - • {opts} (`table`) Additional options - • {prompt}? (`string`) Text of the prompt. Defaults to - `Select one of:` - • {format_item}? (`fun(item: any):string`) Function to - format an individual item from `items`. Defaults to - `tostring`. - • {kind}? (`string`) Arbitrary hint string indicating the - item shape. Plugins reimplementing `vim.ui.select` may - wish to use this to infer the structure or semantics of - `items`, or the context in which select() was called. - • {on_choice} (`fun(item: T?, idx: integer?)`) Called once the user - made a choice. `idx` is the 1-based index of `item` - within `items`. `nil` if the user aborted the dialog. - - -============================================================================== -Lua module: vim._extui *vim._extui* - -WARNING: This is an experimental interface intended to replace the message -grid in the TUI. - -To enable the experimental UI (default opts shown): >lua - require('vim._extui').enable({ - enable = true, -- Whether to enable or disable the UI. - msg = { -- Options related to the message module. - ---@type 'cmd'|'msg' Where to place regular messages, either in the - ---cmdline or in a separate ephemeral message window. - target = 'cmd', - timeout = 4000, -- Time a message is visible in the message window. - }, - }) -< - -There are four separate window types used by this interface: -• "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and - messages if 'cmdheight' > 0. -• "msg": The message window; used for messages when 'cmdheight' == 0. -• "pager": The pager window; used for |:messages| and certain messages that - should be shown in full. -• "dialog": The dialog window; used for prompt messages that expect user - input. - -These four windows are assigned the "cmd", "msg", "pager" and "dialog" -'filetype' respectively. Use a |FileType| autocommand to configure any local -options for these windows and their respective buffers. - -Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do -not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the -spilled lines. To see the full message, the |g<| command can be used. ============================================================================== Lua module: vim.filetype *vim.filetype* @@ -2936,65 +2361,6 @@ vim.filetype.match({args}) *vim.filetype.match()* accepts a buffer number as its only argument. -============================================================================== -Lua module: vim.keymap *vim.keymap* - -vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* - Remove an existing mapping. Examples: >lua - vim.keymap.del('n', 'lhs') - - vim.keymap.del({'n', 'i', 'v'}, 'w', { buffer = 5 }) -< - - Parameters: ~ - • {modes} (`string|string[]`) - • {lhs} (`string`) - • {opts} (`table?`) A table with the following fields: - • {buffer}? (`integer|boolean`) Remove a mapping from the - given buffer. When `0` or `true`, use the current buffer. - - See also: ~ - • |vim.keymap.set()| - -vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* - Defines a |mapping| of |keycodes| to a function or keycodes. - - Examples: >lua - -- Map "x" to a Lua function: - vim.keymap.set('n', 'x', function() print('real lua function') end) - -- Map "x" to multiple modes for the current buffer: - vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buffer = true }) - -- Map to an expression (|:map-|): - vim.keymap.set('i', '', function() - return vim.fn.pumvisible() == 1 and '' or '' - end, { expr = true }) - -- Map "[%%" to a mapping: - vim.keymap.set('n', '[%%', '(MatchitNormalMultiBackward)') -< - - Parameters: ~ - • {mode} (`string|string[]`) Mode "short-name" (see - |nvim_set_keymap()|), or a list thereof. - • {lhs} (`string`) Left-hand side |{lhs}| of the mapping. - • {rhs} (`string|function`) Right-hand side |{rhs}| of the mapping, - can be a Lua function. - • {opts} (`table?`) Table of |:map-arguments|. Same as - |nvim_set_keymap()| {opts}, except: - • {replace_keycodes} defaults to `true` if "expr" is `true`. - - Also accepts: - • {buffer}? (`integer|boolean`) Creates buffer-local mapping, - `0` or `true` for current buffer. - • {remap}? (`boolean`, default: `false`) Make the mapping - recursive. Inverse of {noremap}. - - See also: ~ - • |nvim_set_keymap()| - • |maparg()| - • |mapcheck()| - • |mapset()| - - ============================================================================== Lua module: vim.fs *vim.fs* @@ -3350,828 +2716,63 @@ vim.glob.to_lpeg({pattern}) *vim.glob.to_lpeg()* ============================================================================== -VIM.LPEG *vim.lpeg* +Lua module: vim.hl *vim.hl* +vim.hl.on_yank({opts}) *vim.hl.on_yank()* + Highlight the yanked text during a |TextYankPost| event. -LPeg is a pattern-matching library for Lua, based on Parsing Expression -Grammars (PEGs). https://bford.info/packrat/ - - *lua-lpeg* *vim.lpeg.Pattern* -The LPeg library for parsing expression grammars is included as `vim.lpeg` -(https://www.inf.puc-rio.br/~roberto/lpeg/). - -In addition, its regex-like interface is available as |vim.re| -(https://www.inf.puc-rio.br/~roberto/lpeg/re.html). - - - -Pattern:match({subject}, {init}, {...}) *Pattern:match()* - Matches the given `pattern` against the `subject` string. If the match - succeeds, returns the index in the subject of the first character after - the match, or the captured values (if the pattern captured any value). An - optional numeric argument `init` makes the match start at that position in - the subject string. As usual in Lua libraries, a negative value counts - from the end. Unlike typical pattern-matching functions, `match` works - only in anchored mode; that is, it tries to match the pattern with a - prefix of the given subject string (at position `init`), not with an - arbitrary substring of the subject. So, if we want to find a pattern - anywhere in a string, we must either write a loop in Lua or write a - pattern that matches anywhere. - - Example: >lua - local pattern = lpeg.R('az') ^ 1 * -1 - assert(pattern:match('hello') == 6) - assert(lpeg.match(pattern, 'hello') == 6) - assert(pattern:match('1 hello') == nil) + Add the following to your `init.vim`: >vim + autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300} < Parameters: ~ - • {subject} (`string`) - • {init} (`integer?`) - • {...} (`any`) + • {opts} (`table?`) Optional parameters + • higroup highlight group for yanked region (default + "IncSearch") + • timeout time in ms before highlight is cleared (default 150) + • on_macro highlight when executing macro (default false) + • on_visual highlight when yanking visual selection (default + true) + • event event structure (default vim.v.event) + • priority integer priority (default + |vim.hl.priorities|`.user`) - Return: ~ - (`any`) ... +vim.hl.priorities *vim.hl.priorities* + Table with default priorities used for highlighting: + • `syntax`: `50`, used for standard syntax highlighting + • `treesitter`: `100`, used for treesitter-based highlighting + • `semantic_tokens`: `125`, used for LSP semantic token highlighting + • `diagnostics`: `150`, used for code analysis such as diagnostics + • `user`: `200`, used for user-triggered highlights such as LSP document + symbols or `on_yank` autocommands -vim.lpeg.B({pattern}) *vim.lpeg.B()* - Returns a pattern that matches only if the input string at the current - position is preceded by `patt`. Pattern `patt` must match only strings - with some fixed length, and it cannot contain captures. Like the `and` - predicate, this pattern never consumes any input, independently of success - or failure. + *vim.hl.range()* +vim.hl.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) + Apply highlight group to range of text. Parameters: ~ - • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.lpeg.C({patt}) *vim.lpeg.C()* - Creates a simple capture, which captures the substring of the subject that - matches `patt`. The captured value is a string. If `patt` has other - captures, their values are returned after this one. - - Example: >lua - local function split (s, sep) - sep = lpeg.P(sep) - local elem = lpeg.C((1 - sep) ^ 0) - local p = elem * (sep * elem) ^ 0 - return lpeg.match(p, s) - end - local a, b, c = split('a,b,c', ',') - assert(a == 'a') - assert(b == 'b') - assert(c == 'c') -< - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Carg({n}) *vim.lpeg.Carg()* - Creates an argument capture. This pattern matches the empty string and - produces the value given as the nth extra argument given in the call to - `lpeg.match`. - - Parameters: ~ - • {n} (`integer`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cb({name}) *vim.lpeg.Cb()* - Creates a back capture. This pattern matches the empty string and produces - the values produced by the most recent group capture named `name` (where - `name` can be any Lua value). Most recent means the last complete - outermost group capture with the given name. A Complete capture means that - the entire pattern corresponding to the capture has matched. An Outermost - capture means that the capture is not inside another complete capture. In - the same way that LPeg does not specify when it evaluates captures, it - does not specify whether it reuses values previously produced by the group - or re-evaluates them. - - Parameters: ~ - • {name} (`any`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cc({...}) *vim.lpeg.Cc()* - Creates a constant capture. This pattern matches the empty string and - produces all given values as its captured values. - - Parameters: ~ - • {...} (`any`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cf({patt}, {func}) *vim.lpeg.Cf()* - Creates a fold capture. If `patt` produces a list of captures C1 C2 ... - Cn, this capture will produce the value - `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or - accumulate, or reduce) the captures from `patt` using function `func`. - This capture assumes that `patt` should produce at least one capture with - at least one value (of any type), which becomes the initial value of an - accumulator. (If you need a specific initial value, you may prefix a - constant capture to `patt`.) For each subsequent capture, LPeg calls - `func` with this accumulator as the first argument and all values produced - by the capture as extra arguments; the first result from this call becomes - the new value for the accumulator. The final value of the accumulator - becomes the captured value. - - Example: >lua - local number = lpeg.R('09') ^ 1 / tonumber - local list = number * (',' * number) ^ 0 - local function add(acc, newvalue) return acc + newvalue end - local sum = lpeg.Cf(list, add) - assert(sum:match('10,30,43') == 83) -< - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - • {func} (`fun(acc, newvalue)`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cg({patt}, {name}) *vim.lpeg.Cg()* - Creates a group capture. It groups all values returned by `patt` into a - single capture. The group may be anonymous (if no name is given) or named - with the given name (which can be any non-nil Lua value). - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - • {name} (`string?`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cmt({patt}, {fn}) *vim.lpeg.Cmt()* - Creates a match-time capture. Unlike all other captures, this one is - evaluated immediately when a match occurs (even if it is part of a larger - pattern that fails later). It forces the immediate evaluation of all its - nested captures and then calls `function`. The given function gets as - arguments the entire subject, the current position (after the match of - `patt`), plus any capture values produced by `patt`. The first value - returned by `function` defines how the match happens. If the call returns - a number, the match succeeds and the returned number becomes the new - current position. (Assuming a subject sand current position `i`, the - returned number must be in the range `[i, len(s) + 1]`.) If the call - returns `true`, the match succeeds without consuming any input (so, to - return true is equivalent to return `i`). If the call returns `false`, - `nil`, or no value, the match fails. Any extra values returned by the - function become the values produced by the capture. - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - • {fn} (`fun(s: string, i: integer, ...: any)`) (position: - boolean|integer, ...: any) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cp() *vim.lpeg.Cp()* - Creates a position capture. It matches the empty string and captures the - position in the subject where the match occurs. The captured value is a - number. - - Example: >lua - local I = lpeg.Cp() - local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end - local match_start, match_end = anywhere('world'):match('hello world!') - assert(match_start == 7) - assert(match_end == 12) -< - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Cs({patt}) *vim.lpeg.Cs()* - Creates a substitution capture. This function creates a substitution - capture, which captures the substring of the subject that matches `patt`, - with substitutions. For any capture inside `patt` with a value, the - substring that matched the capture is replaced by the capture value (which - should be a string). The final captured value is the string resulting from - all replacements. - - Example: >lua - local function gsub (s, patt, repl) - patt = lpeg.P(patt) - patt = lpeg.Cs((patt / repl + 1) ^ 0) - return lpeg.match(patt, s) - end - assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!') -< - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.Ct({patt}) *vim.lpeg.Ct()* - Creates a table capture. This capture returns a table with all values from - all anonymous captures made by `patt` inside this table in successive - integer keys, starting at 1. Moreover, for each named capture group - created by `patt`, the first value of the group is put into the table with - the group name as its key. The captured value is only the table. - - Parameters: ~ - • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - - Return: ~ - (`vim.lpeg.Capture`) - -vim.lpeg.locale({tab}) *vim.lpeg.locale()* - Returns a table with patterns for matching some character classes - according to the current locale. The table has fields named `alnum`, - `alpha`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, - `upper`, and `xdigit`, each one containing a correspondent pattern. Each - pattern matches any single character that belongs to its class. If called - with an argument `table`, then it creates those fields inside the given - table and returns that table. - - Example: >lua - lpeg.locale(lpeg) - local space = lpeg.space ^ 0 - local name = lpeg.C(lpeg.alpha ^ 1) * space - local sep = lpeg.S(',;') * space - local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1 - local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset) - local t = list:match('a=b, c = hi; next = pi') - assert(t.a == 'b') - assert(t.c == 'hi') - assert(t.next == 'pi') - local locale = lpeg.locale() - assert(type(locale.digit) == 'userdata') -< - - Parameters: ~ - • {tab} (`table?`) - - Return: ~ - (`vim.lpeg.Locale`) - -vim.lpeg.match({pattern}, {subject}, {init}, {...}) *vim.lpeg.match()* - Matches the given `pattern` against the `subject` string. If the match - succeeds, returns the index in the subject of the first character after - the match, or the captured values (if the pattern captured any value). An - optional numeric argument `init` makes the match start at that position in - the subject string. As usual in Lua libraries, a negative value counts - from the end. Unlike typical pattern-matching functions, `match` works - only in anchored mode; that is, it tries to match the pattern with a - prefix of the given subject string (at position `init`), not with an - arbitrary substring of the subject. So, if we want to find a pattern - anywhere in a string, we must either write a loop in Lua or write a - pattern that matches anywhere. - - Example: >lua - local pattern = lpeg.R('az') ^ 1 * -1 - assert(pattern:match('hello') == 6) - assert(lpeg.match(pattern, 'hello') == 6) - assert(pattern:match('1 hello') == nil) -< - - Parameters: ~ - • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - • {subject} (`string`) - • {init} (`integer?`) - • {...} (`any`) - - Return: ~ - (`any`) ... - -vim.lpeg.P({value}) *vim.lpeg.P()* - Converts the given value into a proper pattern. The following rules are - applied: - • If the argument is a pattern, it is returned unmodified. - • If the argument is a string, it is translated to a pattern that matches - the string literally. - • If the argument is a non-negative number `n`, the result is a pattern - that matches exactly `n` characters. - • If the argument is a negative number `-n`, the result is a pattern that - succeeds only if the input string has less than `n` characters left: - `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus - operation). - • If the argument is a boolean, the result is a pattern that always - succeeds or always fails (according to the boolean value), without - consuming any input. - • If the argument is a table, it is interpreted as a grammar (see - Grammars). - • If the argument is a function, returns a pattern equivalent to a - match-time capture over the empty string. - - Parameters: ~ - • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.lpeg.R({...}) *vim.lpeg.R()* - Returns a pattern that matches any single character belonging to one of - the given ranges. Each `range` is a string `xy` of length 2, representing - all characters with code between the codes of `x` and `y` (both - inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, - and `lpeg.R('az', 'AZ')` matches any ASCII letter. - - Example: >lua - local pattern = lpeg.R('az') ^ 1 * -1 - assert(pattern:match('hello') == 6) -< - - Parameters: ~ - • {...} (`string`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.lpeg.S({string}) *vim.lpeg.S()* - Returns a pattern that matches any single character that appears in the - given string (the `S` stands for Set). As an example, the pattern - `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a - character (that is, a string of length 1), then `lpeg.P(s)` is equivalent - to `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both - `lpeg.S('')` and `lpeg.R()` are patterns that always fail. - - Parameters: ~ - • {string} (`string`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.lpeg.setmaxstack({max}) *vim.lpeg.setmaxstack()* - Sets a limit for the size of the backtrack stack used by LPeg to track - calls and choices. The default limit is `400`. Most well-written patterns - need little backtrack levels and therefore you seldom need to change this - limit; before changing it you should try to rewrite your pattern to avoid - the need for extra space. Nevertheless, a few useful patterns may - overflow. Also, with recursive grammars, subjects with deep recursion may - also need larger limits. - - Parameters: ~ - • {max} (`integer`) - -vim.lpeg.type({value}) *vim.lpeg.type()* - Returns the string `"pattern"` if the given value is a pattern, otherwise - `nil`. - - Parameters: ~ - • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) - - Return: ~ - (`"pattern"?`) - -vim.lpeg.V({v}) *vim.lpeg.V()* - Creates a non-terminal (a variable) for a grammar. This operation creates - a non-terminal (a variable) for a grammar. The created non-terminal refers - to the rule indexed by `v` in the enclosing grammar. - - Example: >lua - local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'}) - assert(b:match('((string))') == 11) - assert(b:match('(') == nil) -< - - Parameters: ~ - • {v} (`boolean|string|number|function|table|thread|userdata|lightuserdata`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.lpeg.version() *vim.lpeg.version()* - Returns a string with the running version of LPeg. - - Return: ~ - (`string`) - - -============================================================================== -VIM.RE *vim.re* - -The `vim.re` module provides a conventional regex-like syntax for pattern -usage within LPeg |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim -|regexp| from Lua.) - -See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original -documentation including regex syntax and examples. - - -vim.re.compile({string}, {defs}) *vim.re.compile()* - Compiles the given {string} and returns an equivalent LPeg pattern. The - given string may define either an expression or a grammar. The optional - {defs} table provides extra Lua values to be used by the pattern. - - Parameters: ~ - • {string} (`string`) - • {defs} (`table?`) - - Return: ~ - (`vim.lpeg.Pattern`) - -vim.re.find({subject}, {pattern}, {init}) *vim.re.find()* - Searches the given {pattern} in the given {subject}. If it finds a match, - returns the index where this occurrence starts and the index where it - ends. Otherwise, returns nil. - - An optional numeric argument {init} makes the search starts at that - position in the subject string. As usual in Lua libraries, a negative - value counts from the end. - - Parameters: ~ - • {subject} (`string`) - • {pattern} (`vim.lpeg.Pattern|string`) - • {init} (`integer?`) + • {bufnr} (`integer`) Buffer number to apply highlighting to + • {ns} (`integer`) Namespace to add highlight to + • {higroup} (`string`) Highlight group to use for highlighting + • {start} (`[integer,integer]|string`) Start of region as a (line, + column) tuple or string accepted by |getpos()| + • {finish} (`[integer,integer]|string`) End of region as a (line, + column) tuple or string accepted by |getpos()| + • {opts} (`table?`) A table with the following fields: + • {regtype}? (`string`, default: `'v'` i.e. charwise) Type + of range. See |getregtype()| + • {inclusive}? (`boolean`, default: `false`) Indicates + whether the range is end-inclusive + • {priority}? (`integer`, default: + `vim.hl.priorities.user`) Highlight priority + • {timeout}? (`integer`, default: -1 no timeout) Time in ms + before highlight is cleared Return (multiple): ~ - (`integer?`) the index where the occurrence starts, nil if no match - (`integer?`) the index where the occurrence ends, nil if no match - -vim.re.gsub({subject}, {pattern}, {replacement}) *vim.re.gsub()* - Does a global substitution, replacing all occurrences of {pattern} in the - given {subject} by {replacement}. - - Parameters: ~ - • {subject} (`string`) - • {pattern} (`vim.lpeg.Pattern|string`) - • {replacement} (`string`) - - Return: ~ - (`string`) - -vim.re.match({subject}, {pattern}, {init}) *vim.re.match()* - Matches the given {pattern} against the given {subject}, returning all - captures. - - Parameters: ~ - • {subject} (`string`) - • {pattern} (`vim.lpeg.Pattern|string`) - • {init} (`integer?`) - - Return: ~ - (`integer|vim.lpeg.Capture?`) - - See also: ~ - • vim.lpeg.match() - -vim.re.updatelocale() *vim.re.updatelocale()* - Updates the pre-defined character classes to the current locale. - - -============================================================================== -VIM.REGEX *vim.regex* - -Vim regexes can be used directly from Lua. Currently they only allow matching -within a single line. - - - *regex:match_line()* -regex:match_line({bufnr}, {line_idx}, {start}, {end_}) - Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is - restricted to byte index range `start` and `end_` if given, otherwise see - |regex:match_str()|. Returned byte indices are relative to `start` if - given. - - Parameters: ~ - • {bufnr} (`integer`) - • {line_idx} (`integer`) - • {start} (`integer?`) - • {end_} (`integer?`) - - Return (multiple): ~ - (`integer?`) match start (byte index) relative to `start`, or `nil` if - no match - (`integer?`) match end (byte index) relative to `start`, or `nil` if - no match - -regex:match_str({str}) *regex:match_str()* - Matches string `str` against this regex. To match the string precisely, - surround the regex with "^" and "$". Returns the byte indices for the - start and end of the match, or `nil` if there is no match. Because any - integer is "truthy", `regex:match_str()` can be directly used as a - condition in an if-statement. - - Parameters: ~ - • {str} (`string`) - - Return (multiple): ~ - (`integer?`) match start (byte index), or `nil` if no match - (`integer?`) match end (byte index), or `nil` if no match - -vim.regex({re}) *vim.regex()* - Parses the Vim regex `re` and returns a regex object. Regexes are "magic" - and case-sensitive by default, regardless of 'magic' and 'ignorecase'. - They can be controlled with flags, see |/magic| and |/ignorecase|. - - Parameters: ~ - • {re} (`string`) - - Return: ~ - (`vim.regex`) - - -============================================================================== -Lua module: vim.secure *vim.secure* - -vim.secure.read({path}) *vim.secure.read()* - If {path} is a file: attempt to read the file, prompting the user if the - file should be trusted. - - If {path} is a directory: return true if the directory is trusted - (non-recursive), prompting the user as necessary. - - The user's choice is persisted in a trust database at - $XDG_STATE_HOME/nvim/trust. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {path} (`string`) Path to a file or directory to read. - - Return: ~ - (`boolean|string?`) If {path} is not trusted or does not exist, - returns `nil`. Otherwise, returns the contents of {path} if it is a - file, or true if {path} is a directory. - - See also: ~ - • |:trust| - -vim.secure.trust({opts}) *vim.secure.trust()* - Manage the trust database. - - The trust database is located at |$XDG_STATE_HOME|/nvim/trust. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {opts} (`table`) A table with the following fields: - • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a - file to the trust database and trust it, - • `'deny'` to add a file to the trust database and deny it, - • `'remove'` to remove file from the trust database - • {path}? (`string`) Path to a file to update. Mutually - exclusive with {bufnr}. Cannot be used when {action} is - "allow". - • {bufnr}? (`integer`) Buffer number to update. Mutually - exclusive with {path}. - - Return (multiple): ~ - (`boolean`) success true if operation was successful - (`string`) msg full path if operation was successful, else error - message - - -============================================================================== -Lua module: vim.version *vim.version* - -The `vim.version` module provides functions for comparing versions and ranges -conforming to the https://semver.org spec. Plugins, and plugin managers, can -use this to check available tools and dependencies on the current system. - -Example: >lua - local v = vim.version.parse(vim.system({'tmux', '-V'}):wait().stdout, {strict=false}) - if vim.version.gt(v, {3, 2, 0}) then - -- ... - end -< - -*vim.version()* returns the version of the current Nvim process. - -VERSION RANGE SPEC *version-range* - -A version "range spec" defines a semantic version range which can be tested -against a version, using |vim.version.range()|. - -Supported range specs are shown in the following table. Note: suffixed -versions (1.2.3-rc1) are not matched. > - 1.2.3 is 1.2.3 - =1.2.3 is 1.2.3 - >1.2.3 greater than 1.2.3 - <1.2.3 before 1.2.3 - >=1.2.3 at least 1.2.3 - <=1.2.3 at most 1.2.3 - ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" - ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" - ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) - ^0.0.1 is =0.0.1 (0.0.x is special) - ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) - ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) - ^1 is >=1.0.0 <2.0.0 "compatible with 1" - ~1 same "reasonably close to 1" - 1.x same - 1.* same - 1 same - * any version - x same - - 1.2.3 - 2.3.4 is >=1.2.3 <2.3.4 - - Partial right: missing pieces treated as x (2.3 => 2.3.x). - 1.2.3 - 2.3 is >=1.2.3 <2.4.0 - 1.2.3 - 2 is >=1.2.3 <3.0.0 - - Partial left: missing pieces treated as 0 (1.2 => 1.2.0). - 1.2 - 2.3.0 is 1.2.0 - 2.3.0 -< - - -*vim.VersionRange* - - Fields: ~ - • {from} (`vim.Version`) - • {to}? (`vim.Version`) - • {has} (`fun(self: vim.VersionRange, version: string|vim.Version): boolean`) - See |VersionRange:has()|. - - -VersionRange:has({version}) *VersionRange:has()* - Check if a version is in the range (inclusive `from`, exclusive `to`). - - Example: >lua - local r = vim.version.range('1.0.0 - 2.0.0') - print(r:has('1.9.9')) -- true - print(r:has('2.0.0')) -- false - print(r:has(vim.version())) -- check against current Nvim version -< - - Or use cmp(), le(), lt(), ge(), gt(), and/or eq() to compare a version - against `.to` and `.from` directly: >lua - local r = vim.version.range('1.0.0 - 2.0.0') -- >=1.0, <2.0 - print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) -< - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {version} (`string|vim.Version`) - - Return: ~ - (`boolean`) - - See also: ~ - • https://github.com/npm/node-semver#ranges - -vim.version.cmp({v1}, {v2}) *vim.version.cmp()* - Parses and compares two version objects (the result of - |vim.version.parse()|, or specified literally as a `{major, minor, patch}` - tuple, e.g. `{1, 0, 3}`). - - Example: >lua - if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then - -- ... - end - local v1 = vim.version.parse('1.0.3-pre') - local v2 = vim.version.parse('0.2.1') - if vim.version.cmp(v1, v2) == 0 then - -- ... - end -< - - Note: ~ - • Per semver, build metadata is ignored when comparing two - otherwise-equivalent versions. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) Version object. - • {v2} (`vim.Version|number[]|string`) Version to compare with `v1`. - - Return: ~ - (`integer`) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. - -vim.version.eq({v1}, {v2}) *vim.version.eq()* - Returns `true` if the given versions are equal. See |vim.version.cmp()| - for usage. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) - • {v2} (`vim.Version|number[]|string`) - - Return: ~ - (`boolean`) - -vim.version.ge({v1}, {v2}) *vim.version.ge()* - Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. - - Attributes: ~ - Since: 0.10.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) - • {v2} (`vim.Version|number[]|string`) - - Return: ~ - (`boolean`) - -vim.version.gt({v1}, {v2}) *vim.version.gt()* - Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) - • {v2} (`vim.Version|number[]|string`) - - Return: ~ - (`boolean`) - -vim.version.intersect({r1}, {r2}) *vim.version.intersect()* - WARNING: This feature is experimental/unstable. - - Computes the common range shared by the given ranges. - - Parameters: ~ - • {r1} (`vim.VersionRange`) First range to intersect. See - |vim.VersionRange|. - • {r2} (`vim.VersionRange`) Second range to intersect. See - |vim.VersionRange|. - - Return: ~ - (`vim.VersionRange?`) Maximal range that is present inside both `r1` - and `r2`. `nil` if such range does not exist. See |vim.VersionRange|. - -vim.version.last({versions}) *vim.version.last()* - TODO: generalize this, move to func.lua - - Parameters: ~ - • {versions} (`vim.Version[]`) - - Return: ~ - (`vim.Version?`) - -vim.version.le({v1}, {v2}) *vim.version.le()* - Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. - - Attributes: ~ - Since: 0.10.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) - • {v2} (`vim.Version|number[]|string`) - - Return: ~ - (`boolean`) - -vim.version.lt({v1}, {v2}) *vim.version.lt()* - Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {v1} (`vim.Version|number[]|string`) - • {v2} (`vim.Version|number[]|string`) - - Return: ~ - (`boolean`) - -vim.version.parse({version}, {opts}) *vim.version.parse()* - Parses a semantic version string and returns a version object which can be - used with other `vim.version` functions. For example "1.0.1-rc1+build.2" - returns: > - { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } -< - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {version} (`string`) Version string to parse. - • {opts} (`table?`) Options for parsing. - • {strict}? (`boolean`, default: `false`) If `true`, no - coercion is attempted on input not conforming to semver - v2.0.0. If `false`, `parse()` attempts to coerce input - such as "1.0", "0-x", "tmux 3.2a" into valid versions. - - Return: ~ - (`vim.Version?`) `Version` object or `nil` if input is invalid. - - See also: ~ - • https://semver.org/spec/v2.0.0.html - -vim.version.range({spec}) *vim.version.range()* - Parses a semver |version-range| "spec" and returns |vim.VersionRange| - object: - - Attributes: ~ - Since: 0.9.0 - - Parameters: ~ - • {spec} (`string`) Version range "spec" - - Return: ~ - (`vim.VersionRange?`) See |vim.VersionRange|. + (`uv.uv_timer_t?`) range_timer A timer which manages how much time the + highlight has left + (`fun()?`) range_clear A function which allows clearing the highlight + manually. nil is returned if timeout is not specified ============================================================================== @@ -4683,6 +3284,795 @@ Iter:totable() *Iter:totable()* (`table`) +============================================================================== +Lua module: vim.json *vim.json* + +This module provides encoding and decoding of Lua objects to and from +JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + + +vim.json.decode({str}, {opts}) *vim.json.decode()* + Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. + • Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below). + • Decodes empty object as |vim.empty_dict()|. + • Decodes empty array as `{}` (empty Lua table). + + Example: >lua + vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) + -- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } +< + + Parameters: ~ + • {str} (`string`) Stringified JSON data. + • {opts} (`table?`) 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|. + + Return: ~ + (`any`) + +vim.json.encode({obj}, {opts}) *vim.json.encode()* + Encodes (or "packs") Lua object {obj} as JSON in a Lua string. + + Parameters: ~ + • {obj} (`any`) + • {opts} (`table?`) Options table with keys: + • escape_slash: (boolean) (default false) Escape slash + characters "/" in string values. + + Return: ~ + (`string`) + + +============================================================================== +Lua module: vim.keymap *vim.keymap* + +vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* + Remove an existing mapping. Examples: >lua + vim.keymap.del('n', 'lhs') + + vim.keymap.del({'n', 'i', 'v'}, 'w', { buffer = 5 }) +< + + Parameters: ~ + • {modes} (`string|string[]`) + • {lhs} (`string`) + • {opts} (`table?`) A table with the following fields: + • {buffer}? (`integer|boolean`) Remove a mapping from the + given buffer. When `0` or `true`, use the current buffer. + + See also: ~ + • |vim.keymap.set()| + +vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* + Defines a |mapping| of |keycodes| to a function or keycodes. + + Examples: >lua + -- Map "x" to a Lua function: + vim.keymap.set('n', 'x', function() print('real lua function') end) + -- Map "x" to multiple modes for the current buffer: + vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buffer = true }) + -- Map to an expression (|:map-|): + vim.keymap.set('i', '', function() + return vim.fn.pumvisible() == 1 and '' or '' + end, { expr = true }) + -- Map "[%%" to a mapping: + vim.keymap.set('n', '[%%', '(MatchitNormalMultiBackward)') +< + + Parameters: ~ + • {mode} (`string|string[]`) Mode "short-name" (see + |nvim_set_keymap()|), or a list thereof. + • {lhs} (`string`) Left-hand side |{lhs}| of the mapping. + • {rhs} (`string|function`) Right-hand side |{rhs}| of the mapping, + can be a Lua function. + • {opts} (`table?`) Table of |:map-arguments|. Same as + |nvim_set_keymap()| {opts}, except: + • {replace_keycodes} defaults to `true` if "expr" is `true`. + + Also accepts: + • {buffer}? (`integer|boolean`) Creates buffer-local mapping, + `0` or `true` for current buffer. + • {remap}? (`boolean`, default: `false`) Make the mapping + recursive. Inverse of {noremap}. + + See also: ~ + • |nvim_set_keymap()| + • |maparg()| + • |mapcheck()| + • |mapset()| + + +============================================================================== +Lua module: vim.loader *vim.loader* + +vim.loader.enable({enable}) *vim.loader.enable()* + WARNING: This feature is experimental/unstable. + + Enables or disables the experimental Lua module loader: + + Enable (`enable=true`): + • overrides |loadfile()| + • adds the Lua loader using the byte-compilation cache + • adds the libs loader + • removes the default Nvim loader + + Disable (`enable=false`): + • removes the loaders + • adds the default Nvim loader + + Parameters: ~ + • {enable} (`boolean?`) true/nil to enable, false to disable + +vim.loader.find({modname}, {opts}) *vim.loader.find()* + WARNING: This feature is experimental/unstable. + + Finds Lua modules for the given module name. + + Parameters: ~ + • {modname} (`string`) Module name, or `"*"` to find the top-level + modules instead + • {opts} (`table?`) Options for finding a module: + • {rtp}? (`boolean`, default: `true`) Search for modname in + the runtime path. + • {paths}? (`string[]`, default: `{}`) Extra paths to + search for modname + • {patterns}? (`string[]`, default: + `{"/init.lua", ".lua"}`) List of patterns to use when + searching for modules. A pattern is a string added to the + basename of the Lua module being searched. + • {all}? (`boolean`, default: `false`) Search for all + matches. + + Return: ~ + (`table[]`) A list of objects with the following fields: + • {modpath} (`string`) Path of the module + • {modname} (`string`) Name of the module + • {stat}? (`uv.fs_stat.result`) The fs_stat of the module path. Won't + be returned for `modname="*"` + +vim.loader.reset({path}) *vim.loader.reset()* + WARNING: This feature is experimental/unstable. + + Resets the cache for the path, or all the paths if path is nil. + + Parameters: ~ + • {path} (`string?`) path to reset + + +============================================================================== +Lua module: vim.lpeg *vim.lpeg* + + +LPeg is a pattern-matching library for Lua, based on Parsing Expression +Grammars (PEGs). https://bford.info/packrat/ + + *lua-lpeg* *vim.lpeg.Pattern* +The LPeg library for parsing expression grammars is included as `vim.lpeg` +(https://www.inf.puc-rio.br/~roberto/lpeg/). + +In addition, its regex-like interface is available as |vim.re| +(https://www.inf.puc-rio.br/~roberto/lpeg/re.html). + + + +Pattern:match({subject}, {init}, {...}) *Pattern:match()* + Matches the given `pattern` against the `subject` string. If the match + succeeds, returns the index in the subject of the first character after + the match, or the captured values (if the pattern captured any value). An + optional numeric argument `init` makes the match start at that position in + the subject string. As usual in Lua libraries, a negative value counts + from the end. Unlike typical pattern-matching functions, `match` works + only in anchored mode; that is, it tries to match the pattern with a + prefix of the given subject string (at position `init`), not with an + arbitrary substring of the subject. So, if we want to find a pattern + anywhere in a string, we must either write a loop in Lua or write a + pattern that matches anywhere. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) + assert(lpeg.match(pattern, 'hello') == 6) + assert(pattern:match('1 hello') == nil) +< + + Parameters: ~ + • {subject} (`string`) + • {init} (`integer?`) + • {...} (`any`) + + Return: ~ + (`any`) ... + +vim.lpeg.B({pattern}) *vim.lpeg.B()* + Returns a pattern that matches only if the input string at the current + position is preceded by `patt`. Pattern `patt` must match only strings + with some fixed length, and it cannot contain captures. Like the `and` + predicate, this pattern never consumes any input, independently of success + or failure. + + Parameters: ~ + • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.C({patt}) *vim.lpeg.C()* + Creates a simple capture, which captures the substring of the subject that + matches `patt`. The captured value is a string. If `patt` has other + captures, their values are returned after this one. + + Example: >lua + local function split (s, sep) + sep = lpeg.P(sep) + local elem = lpeg.C((1 - sep) ^ 0) + local p = elem * (sep * elem) ^ 0 + return lpeg.match(p, s) + end + local a, b, c = split('a,b,c', ',') + assert(a == 'a') + assert(b == 'b') + assert(c == 'c') +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Carg({n}) *vim.lpeg.Carg()* + Creates an argument capture. This pattern matches the empty string and + produces the value given as the nth extra argument given in the call to + `lpeg.match`. + + Parameters: ~ + • {n} (`integer`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cb({name}) *vim.lpeg.Cb()* + Creates a back capture. This pattern matches the empty string and produces + the values produced by the most recent group capture named `name` (where + `name` can be any Lua value). Most recent means the last complete + outermost group capture with the given name. A Complete capture means that + the entire pattern corresponding to the capture has matched. An Outermost + capture means that the capture is not inside another complete capture. In + the same way that LPeg does not specify when it evaluates captures, it + does not specify whether it reuses values previously produced by the group + or re-evaluates them. + + Parameters: ~ + • {name} (`any`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cc({...}) *vim.lpeg.Cc()* + Creates a constant capture. This pattern matches the empty string and + produces all given values as its captured values. + + Parameters: ~ + • {...} (`any`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cf({patt}, {func}) *vim.lpeg.Cf()* + Creates a fold capture. If `patt` produces a list of captures C1 C2 ... + Cn, this capture will produce the value + `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or + accumulate, or reduce) the captures from `patt` using function `func`. + This capture assumes that `patt` should produce at least one capture with + at least one value (of any type), which becomes the initial value of an + accumulator. (If you need a specific initial value, you may prefix a + constant capture to `patt`.) For each subsequent capture, LPeg calls + `func` with this accumulator as the first argument and all values produced + by the capture as extra arguments; the first result from this call becomes + the new value for the accumulator. The final value of the accumulator + becomes the captured value. + + Example: >lua + local number = lpeg.R('09') ^ 1 / tonumber + local list = number * (',' * number) ^ 0 + local function add(acc, newvalue) return acc + newvalue end + local sum = lpeg.Cf(list, add) + assert(sum:match('10,30,43') == 83) +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + • {func} (`fun(acc, newvalue)`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cg({patt}, {name}) *vim.lpeg.Cg()* + Creates a group capture. It groups all values returned by `patt` into a + single capture. The group may be anonymous (if no name is given) or named + with the given name (which can be any non-nil Lua value). + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + • {name} (`string?`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cmt({patt}, {fn}) *vim.lpeg.Cmt()* + Creates a match-time capture. Unlike all other captures, this one is + evaluated immediately when a match occurs (even if it is part of a larger + pattern that fails later). It forces the immediate evaluation of all its + nested captures and then calls `function`. The given function gets as + arguments the entire subject, the current position (after the match of + `patt`), plus any capture values produced by `patt`. The first value + returned by `function` defines how the match happens. If the call returns + a number, the match succeeds and the returned number becomes the new + current position. (Assuming a subject sand current position `i`, the + returned number must be in the range `[i, len(s) + 1]`.) If the call + returns `true`, the match succeeds without consuming any input (so, to + return true is equivalent to return `i`). If the call returns `false`, + `nil`, or no value, the match fails. Any extra values returned by the + function become the values produced by the capture. + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + • {fn} (`fun(s: string, i: integer, ...: any)`) (position: + boolean|integer, ...: any) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cp() *vim.lpeg.Cp()* + Creates a position capture. It matches the empty string and captures the + position in the subject where the match occurs. The captured value is a + number. + + Example: >lua + local I = lpeg.Cp() + local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end + local match_start, match_end = anywhere('world'):match('hello world!') + assert(match_start == 7) + assert(match_end == 12) +< + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cs({patt}) *vim.lpeg.Cs()* + Creates a substitution capture. This function creates a substitution + capture, which captures the substring of the subject that matches `patt`, + with substitutions. For any capture inside `patt` with a value, the + substring that matched the capture is replaced by the capture value (which + should be a string). The final captured value is the string resulting from + all replacements. + + Example: >lua + local function gsub (s, patt, repl) + patt = lpeg.P(patt) + patt = lpeg.Cs((patt / repl + 1) ^ 0) + return lpeg.match(patt, s) + end + assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!') +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Ct({patt}) *vim.lpeg.Ct()* + Creates a table capture. This capture returns a table with all values from + all anonymous captures made by `patt` inside this table in successive + integer keys, starting at 1. Moreover, for each named capture group + created by `patt`, the first value of the group is put into the table with + the group name as its key. The captured value is only the table. + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.locale({tab}) *vim.lpeg.locale()* + Returns a table with patterns for matching some character classes + according to the current locale. The table has fields named `alnum`, + `alpha`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, + `upper`, and `xdigit`, each one containing a correspondent pattern. Each + pattern matches any single character that belongs to its class. If called + with an argument `table`, then it creates those fields inside the given + table and returns that table. + + Example: >lua + lpeg.locale(lpeg) + local space = lpeg.space ^ 0 + local name = lpeg.C(lpeg.alpha ^ 1) * space + local sep = lpeg.S(',;') * space + local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1 + local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset) + local t = list:match('a=b, c = hi; next = pi') + assert(t.a == 'b') + assert(t.c == 'hi') + assert(t.next == 'pi') + local locale = lpeg.locale() + assert(type(locale.digit) == 'userdata') +< + + Parameters: ~ + • {tab} (`table?`) + + Return: ~ + (`vim.lpeg.Locale`) + +vim.lpeg.match({pattern}, {subject}, {init}, {...}) *vim.lpeg.match()* + Matches the given `pattern` against the `subject` string. If the match + succeeds, returns the index in the subject of the first character after + the match, or the captured values (if the pattern captured any value). An + optional numeric argument `init` makes the match start at that position in + the subject string. As usual in Lua libraries, a negative value counts + from the end. Unlike typical pattern-matching functions, `match` works + only in anchored mode; that is, it tries to match the pattern with a + prefix of the given subject string (at position `init`), not with an + arbitrary substring of the subject. So, if we want to find a pattern + anywhere in a string, we must either write a loop in Lua or write a + pattern that matches anywhere. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) + assert(lpeg.match(pattern, 'hello') == 6) + assert(pattern:match('1 hello') == nil) +< + + Parameters: ~ + • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + • {subject} (`string`) + • {init} (`integer?`) + • {...} (`any`) + + Return: ~ + (`any`) ... + +vim.lpeg.P({value}) *vim.lpeg.P()* + Converts the given value into a proper pattern. The following rules are + applied: + • If the argument is a pattern, it is returned unmodified. + • If the argument is a string, it is translated to a pattern that matches + the string literally. + • If the argument is a non-negative number `n`, the result is a pattern + that matches exactly `n` characters. + • If the argument is a negative number `-n`, the result is a pattern that + succeeds only if the input string has less than `n` characters left: + `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus + operation). + • If the argument is a boolean, the result is a pattern that always + succeeds or always fails (according to the boolean value), without + consuming any input. + • If the argument is a table, it is interpreted as a grammar (see + Grammars). + • If the argument is a function, returns a pattern equivalent to a + match-time capture over the empty string. + + Parameters: ~ + • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.R({...}) *vim.lpeg.R()* + Returns a pattern that matches any single character belonging to one of + the given ranges. Each `range` is a string `xy` of length 2, representing + all characters with code between the codes of `x` and `y` (both + inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, + and `lpeg.R('az', 'AZ')` matches any ASCII letter. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) +< + + Parameters: ~ + • {...} (`string`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.S({string}) *vim.lpeg.S()* + Returns a pattern that matches any single character that appears in the + given string (the `S` stands for Set). As an example, the pattern + `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a + character (that is, a string of length 1), then `lpeg.P(s)` is equivalent + to `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both + `lpeg.S('')` and `lpeg.R()` are patterns that always fail. + + Parameters: ~ + • {string} (`string`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.setmaxstack({max}) *vim.lpeg.setmaxstack()* + Sets a limit for the size of the backtrack stack used by LPeg to track + calls and choices. The default limit is `400`. Most well-written patterns + need little backtrack levels and therefore you seldom need to change this + limit; before changing it you should try to rewrite your pattern to avoid + the need for extra space. Nevertheless, a few useful patterns may + overflow. Also, with recursive grammars, subjects with deep recursion may + also need larger limits. + + Parameters: ~ + • {max} (`integer`) + +vim.lpeg.type({value}) *vim.lpeg.type()* + Returns the string `"pattern"` if the given value is a pattern, otherwise + `nil`. + + Parameters: ~ + • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`"pattern"?`) + +vim.lpeg.V({v}) *vim.lpeg.V()* + Creates a non-terminal (a variable) for a grammar. This operation creates + a non-terminal (a variable) for a grammar. The created non-terminal refers + to the rule indexed by `v` in the enclosing grammar. + + Example: >lua + local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'}) + assert(b:match('((string))') == 11) + assert(b:match('(') == nil) +< + + Parameters: ~ + • {v} (`boolean|string|number|function|table|thread|userdata|lightuserdata`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.version() *vim.lpeg.version()* + Returns a string with the running version of LPeg. + + Return: ~ + (`string`) + + +============================================================================== +Lua module: vim.mpack *vim.mpack* + +This module provides encoding and decoding of Lua objects to and from +msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + + +vim.mpack.decode({str}) *vim.mpack.decode()* + Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. + + Parameters: ~ + • {str} (`string`) + + Return: ~ + (`any`) + +vim.mpack.encode({obj}) *vim.mpack.encode()* + Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. + + Parameters: ~ + • {obj} (`any`) + + Return: ~ + (`string`) + + +============================================================================== +Lua module: vim.net *vim.net* + +vim.net.request({url}, {opts}, {on_response}) *vim.net.request()* + Makes an HTTP GET request to the given URL (asynchronous). + + This function operates in one mode: + • Asynchronous (non-blocking): Returns immediately and passes the response + object to the provided `on_response` handler on completetion. + + Parameters: ~ + • {url} (`string`) The URL for the request. + • {opts} (`table?`) Optional parameters: + • `verbose` (boolean|nil): Enables verbose output. + • `retry` (integer|nil): Number of retries on transient + failures (default: 3). + • `outpath` (string|nil): File path to save the + response body to. If set, the `body` value in the + Response Object will be `true` instead of the + response body. + • {on_response} (`fun(err?: string, response?: { body: string|boolean })`) + Callback invoked on request completetion. The `body` + field in the response object contains the raw response + data (text or binary). Called with (err, nil) on + failure, or (nil, { body = string|boolean }) on + success. + + +============================================================================== +Lua module: vim.re *vim.re* + +The `vim.re` module provides a conventional regex-like syntax for pattern +usage within LPeg |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim +|regexp| from Lua.) + +See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original +documentation including regex syntax and examples. + + +vim.re.compile({string}, {defs}) *vim.re.compile()* + Compiles the given {string} and returns an equivalent LPeg pattern. The + given string may define either an expression or a grammar. The optional + {defs} table provides extra Lua values to be used by the pattern. + + Parameters: ~ + • {string} (`string`) + • {defs} (`table?`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.re.find({subject}, {pattern}, {init}) *vim.re.find()* + Searches the given {pattern} in the given {subject}. If it finds a match, + returns the index where this occurrence starts and the index where it + ends. Otherwise, returns nil. + + An optional numeric argument {init} makes the search starts at that + position in the subject string. As usual in Lua libraries, a negative + value counts from the end. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {init} (`integer?`) + + Return (multiple): ~ + (`integer?`) the index where the occurrence starts, nil if no match + (`integer?`) the index where the occurrence ends, nil if no match + +vim.re.gsub({subject}, {pattern}, {replacement}) *vim.re.gsub()* + Does a global substitution, replacing all occurrences of {pattern} in the + given {subject} by {replacement}. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {replacement} (`string`) + + Return: ~ + (`string`) + +vim.re.match({subject}, {pattern}, {init}) *vim.re.match()* + Matches the given {pattern} against the given {subject}, returning all + captures. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {init} (`integer?`) + + Return: ~ + (`integer|vim.lpeg.Capture?`) + + See also: ~ + • vim.lpeg.match() + +vim.re.updatelocale() *vim.re.updatelocale()* + Updates the pre-defined character classes to the current locale. + + +============================================================================== +Lua module: vim.regex *vim.regex* + +Vim regexes can be used directly from Lua. Currently they only allow matching +within a single line. + + + *regex:match_line()* +regex:match_line({bufnr}, {line_idx}, {start}, {end_}) + Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is + restricted to byte index range `start` and `end_` if given, otherwise see + |regex:match_str()|. Returned byte indices are relative to `start` if + given. + + Parameters: ~ + • {bufnr} (`integer`) + • {line_idx} (`integer`) + • {start} (`integer?`) + • {end_} (`integer?`) + + Return (multiple): ~ + (`integer?`) match start (byte index) relative to `start`, or `nil` if + no match + (`integer?`) match end (byte index) relative to `start`, or `nil` if + no match + +regex:match_str({str}) *regex:match_str()* + Matches string `str` against this regex. To match the string precisely, + surround the regex with "^" and "$". Returns the byte indices for the + start and end of the match, or `nil` if there is no match. Because any + integer is "truthy", `regex:match_str()` can be directly used as a + condition in an if-statement. + + Parameters: ~ + • {str} (`string`) + + Return (multiple): ~ + (`integer?`) match start (byte index), or `nil` if no match + (`integer?`) match end (byte index), or `nil` if no match + +vim.regex({re}) *vim.regex()* + Parses the Vim regex `re` and returns a regex object. Regexes are "magic" + and case-sensitive by default, regardless of 'magic' and 'ignorecase'. + They can be controlled with flags, see |/magic| and |/ignorecase|. + + Parameters: ~ + • {re} (`string`) + + Return: ~ + (`vim.regex`) + + +============================================================================== +Lua module: vim.secure *vim.secure* + +vim.secure.read({path}) *vim.secure.read()* + If {path} is a file: attempt to read the file, prompting the user if the + file should be trusted. + + If {path} is a directory: return true if the directory is trusted + (non-recursive), prompting the user as necessary. + + The user's choice is persisted in a trust database at + $XDG_STATE_HOME/nvim/trust. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {path} (`string`) Path to a file or directory to read. + + Return: ~ + (`boolean|string?`) If {path} is not trusted or does not exist, + returns `nil`. Otherwise, returns the contents of {path} if it is a + file, or true if {path} is a directory. + + See also: ~ + • |:trust| + +vim.secure.trust({opts}) *vim.secure.trust()* + Manage the trust database. + + The trust database is located at |$XDG_STATE_HOME|/nvim/trust. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {opts} (`table`) A table with the following fields: + • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a + file to the trust database and trust it, + • `'deny'` to add a file to the trust database and deny it, + • `'remove'` to remove file from the trust database + • {path}? (`string`) Path to a file to update. Mutually + exclusive with {bufnr}. Cannot be used when {action} is + "allow". + • {bufnr}? (`integer`) Buffer number to update. Mutually + exclusive with {path}. + + Return (multiple): ~ + (`boolean`) success true if operation was successful + (`string`) msg full path if operation was successful, else error + message + + ============================================================================== Lua module: vim.snippet *vim.snippet* @@ -4740,6 +4130,201 @@ vim.snippet.stop() *vim.snippet.stop()* Exits the current snippet. +============================================================================== +Lua module: vim.spell *vim.spell* + +vim.spell.check({str}) *vim.spell.check()* + Check {str} for spelling errors. Similar to the Vimscript function + |spellbadword()|. + + Note: The behaviour of this function is dependent on: 'spelllang', + 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to + the buffer. Consider calling this with |nvim_buf_call()|. + + Example: >lua + vim.spell.check("the quik brown fox") + -- => + -- { + -- {'quik', 'bad', 5} + -- } +< + + Parameters: ~ + • {str} (`string`) + + Return: ~ + (`[string, 'bad'|'rare'|'local'|'caps', integer][]`) List of tuples + with three items: + • The badly spelled word. + • The type of the spelling error: "bad" spelling mistake "rare" rare + word "local" word only valid in another region "caps" word should + start with Capital + • The position in {str} where the word begins. + + +============================================================================== +Lua module: vim.system *lua-vim-system* + +*vim.SystemCompleted* + + Fields: ~ + • {code} (`integer`) + • {signal} (`integer`) + • {stdout}? (`string`) `nil` if stdout is disabled or has a custom + handler. + • {stderr}? (`string`) `nil` if stderr is disabled or has a custom + handler. + +*vim.SystemObj* + + Fields: ~ + • {cmd} (`string[]`) Command name and args + • {pid} (`integer`) Process ID + • {kill} (`fun(self: vim.SystemObj, signal: integer|string)`) See + |SystemObj:kill()|. + • {wait} (`fun(self: vim.SystemObj, timeout: integer?): vim.SystemCompleted`) + See |SystemObj:wait()|. + • {write} (`fun(self: vim.SystemObj, data: string[]|string?)`) See + |SystemObj:write()|. + • {is_closing} (`fun(self: vim.SystemObj): boolean`) See + |SystemObj:is_closing()|. + + +SystemObj:is_closing() *SystemObj:is_closing()* + Checks if the process handle is closing or already closed. + + This method returns `true` if the underlying process handle is either + `nil` or is in the process of closing. It is useful for determining + whether it is safe to perform operations on the process handle. + + Return: ~ + (`boolean`) + +SystemObj:kill({signal}) *SystemObj:kill()* + Sends a signal to the process. + + The signal can be specified as an integer or as a string. + + Example: >lua + local obj = vim.system({'sleep', '10'}) + obj:kill('TERM') -- sends SIGTERM to the process +< + + Parameters: ~ + • {signal} (`integer|string`) Signal to send to the process. + +SystemObj:wait({timeout}) *SystemObj:wait()* + Waits for the process to complete or until the specified timeout elapses. + + This method blocks execution until the associated process has exited or + the optional `timeout` (in milliseconds) has been reached. If the process + does not exit before the timeout, it is forcefully terminated with SIGKILL + (signal 9), and the exit code is set to 124. + + If no `timeout` is provided, the method will wait indefinitely (or use the + timeout specified in the options when the process was started). + + Example: >lua + local obj = vim.system({'echo', 'hello'}, { text = true }) + local result = obj:wait(1000) -- waits up to 1000ms + print(result.code, result.signal, result.stdout, result.stderr) +< + + Parameters: ~ + • {timeout} (`integer?`) + + Return: ~ + (`vim.SystemCompleted`) See |vim.SystemCompleted|. + +SystemObj:write({data}) *SystemObj:write()* + Writes data to the stdin of the process or closes stdin. + + If `data` is a list of strings, each string is written followed by a + newline. + + If `data` is a string, it is written as-is. + + If `data` is `nil`, the write side of the stream is shut down and the pipe + is closed. + + Example: >lua + local obj = vim.system({'cat'}, { stdin = true }) + obj:write({'hello', 'world'}) -- writes 'hello\nworld\n' to stdin + obj:write(nil) -- closes stdin +< + + Parameters: ~ + • {data} (`string[]|string?`) + +vim.system({cmd}, {opts}, {on_exit}) *vim.system()* + Runs a system command or throws an error if {cmd} cannot be run. + + The command runs directly (not in 'shell') so shell builtins such as + "echo" in cmd.exe, cmdlets in powershell, or "help" in bash, will not work + unless you actually invoke a shell: `vim.system({'bash', '-c', 'help'})`. + + Examples: >lua + local on_exit = function(obj) + print(obj.code) + print(obj.signal) + print(obj.stdout) + print(obj.stderr) + end + + -- Runs asynchronously: + vim.system({'echo', 'hello'}, { text = true }, on_exit) + + -- Runs synchronously: + local obj = vim.system({'echo', 'hello'}, { text = true }):wait() + -- { code = 0, signal = 0, stdout = 'hello\n', stderr = '' } +< + + See |uv.spawn()| for more details. Note: unlike |uv.spawn()|, vim.system + throws an error if {cmd} cannot be run. + + Parameters: ~ + • {cmd} (`string[]`) Command to execute + • {opts} (`table?`) A table with the following fields: + • {cwd}? (`string`) Set the current working directory for + the sub-process. + • {env}? (`table`) Set environment + variables for the new process. Inherits the current + environment with `NVIM` set to |v:servername|. + • {clear_env}? (`boolean`) `env` defines the job + environment exactly, instead of merging current + environment. Note: if `env` is `nil`, the current + environment is used but without `NVIM` set. + • {stdin}? (`string|string[]|true`) If `true`, then a pipe + to stdin is opened and can be written to via the + `write()` method to SystemObj. If `string` or `string[]` + then will be written to stdin and closed. + • {stdout}? (`fun(err:string?, data: string?)|boolean`, + default: `true`) Handle output from stdout. + • {stderr}? (`fun(err:string?, data: string?)|boolean`, + default: `true`) Handle output from stderr. + • {text}? (`boolean`) Handle stdout and stderr as text. + Normalizes line endings by replacing `\r\n` with `\n`. + • {timeout}? (`integer`) Run the command with a time limit + in ms. Upon timeout the process is sent the TERM signal + (15) and the exit code is set to 124. + • {detach}? (`boolean`) Spawn the child process in a + detached state - this will make it a process group + leader, and will effectively enable the child to keep + running after the parent exits. Note that the child + process will still keep the parent's event loop alive + unless the parent process calls |uv.unref()| on the + child's process handle. + • {on_exit} (`fun(out: vim.SystemCompleted)?`) Called when subprocess + exits. When provided, the command runs asynchronously. See + return of SystemObj:wait(). + + Overloads: ~ + • `fun(cmd: string, on_exit: fun(out: vim.SystemCompleted)): vim.SystemObj` + + Return: ~ + (`vim.SystemObj`) See |vim.SystemObj|. + + ============================================================================== Lua module: vim.text *vim.text* @@ -4862,6 +4447,414 @@ vim.text.indent({size}, {text}, {opts}) *vim.text.indent()* (`integer`) Indent size before modification. +============================================================================== +Lua module: vim.ui *vim.ui* + +vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* + Prompts the user for input, allowing arbitrary (potentially asynchronous) + work until `on_confirm`. + + Example: >lua + vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) + vim.o.shiftwidth = tonumber(input) + end) +< + + Parameters: ~ + • {opts} (`table?`) Additional options. See |input()| + • {prompt}? (`string`) Text of the prompt + • {default}? (`string`) Default reply to the input + • {completion}? (`string`) Specifies type of completion + supported for input. Supported types are the same that + can be supplied to a user-defined command using the + "-complete=" argument. See |:command-completion| + • {highlight}? (`function`) Function that will be used + for highlighting user inputs. + • {on_confirm} (`fun(input?: string)`) Called once the user confirms or + abort the input. `input` is what the user typed (it + might be an empty string if nothing was entered), or + `nil` if the user aborted the dialog. + +vim.ui.open({path}, {opt}) *vim.ui.open()* + Opens `path` with the system default handler (macOS `open`, Windows + `explorer.exe`, Linux `xdg-open`, …), or returns (but does not show) an + error message on failure. + + Can also be invoked with `:Open`. *:Open* + + Expands "~/" and environment variables in filesystem paths. + + Examples: >lua + -- Asynchronous. + vim.ui.open("https://neovim.io/") + vim.ui.open("~/path/to/file") + -- Use the "osurl" command to handle the path or URL. + vim.ui.open("gh#neovim/neovim!29490", { cmd = { 'osurl' } }) + -- Synchronous (wait until the process exits). + local cmd, err = vim.ui.open("$VIMRUNTIME") + if cmd then + cmd:wait() + end +< + + Parameters: ~ + • {path} (`string`) Path or URL to open + • {opt} (`table?`) Options + • {cmd}? (`string[]`) Command used to open the path or URL. + + Return (multiple): ~ + (`vim.SystemObj?`) Command object, or nil if not found. See + |vim.SystemObj|. + (`string?`) Error message on failure, or nil on success. + + See also: ~ + • |vim.system()| + +vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* + Prompts the user to pick from a list of items, allowing arbitrary + (potentially asynchronous) work until `on_choice`. + + Example: >lua + vim.ui.select({ 'tabs', 'spaces' }, { + prompt = 'Select tabs or spaces:', + format_item = function(item) + return "I'd like to choose " .. item + end, + }, function(choice) + if choice == 'spaces' then + vim.o.expandtab = true + else + vim.o.expandtab = false + end + end) +< + + Parameters: ~ + • {items} (`any[]`) Arbitrary items + • {opts} (`table`) Additional options + • {prompt}? (`string`) Text of the prompt. Defaults to + `Select one of:` + • {format_item}? (`fun(item: any):string`) Function to + format an individual item from `items`. Defaults to + `tostring`. + • {kind}? (`string`) Arbitrary hint string indicating the + item shape. Plugins reimplementing `vim.ui.select` may + wish to use this to infer the structure or semantics of + `items`, or the context in which select() was called. + • {on_choice} (`fun(item: T?, idx: integer?)`) Called once the user + made a choice. `idx` is the 1-based index of `item` + within `items`. `nil` if the user aborted the dialog. + + +============================================================================== +Lua module: vim.uri *vim.uri* + +vim.uri_decode({str}) *vim.uri_decode()* + URI-decodes a string containing percent escapes. + + Parameters: ~ + • {str} (`string`) string to decode + + Return: ~ + (`string`) decoded string + +vim.uri_encode({str}, {rfc}) *vim.uri_encode()* + URI-encodes a string using percent escapes. + + Parameters: ~ + • {str} (`string`) string to encode + • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`) + + Return: ~ + (`string`) encoded string + +vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* + Gets a URI from a bufnr. + + Parameters: ~ + • {bufnr} (`integer`) + + Return: ~ + (`string`) URI + +vim.uri_from_fname({path}) *vim.uri_from_fname()* + Gets a URI from a file path. + + Parameters: ~ + • {path} (`string`) Path to file + + Return: ~ + (`string`) URI + +vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()* + Gets the buffer for a uri. Creates a new unloaded buffer if no buffer for + the uri already exists. + + Parameters: ~ + • {uri} (`string`) + + Return: ~ + (`integer`) bufnr + +vim.uri_to_fname({uri}) *vim.uri_to_fname()* + Gets a filename from a URI. + + Parameters: ~ + • {uri} (`string`) + + Return: ~ + (`string`) filename or unchanged URI for non-file URIs + + +============================================================================== +Lua module: vim.version *vim.version* + +The `vim.version` module provides functions for comparing versions and ranges +conforming to the https://semver.org spec. Plugins, and plugin managers, can +use this to check available tools and dependencies on the current system. + +Example: >lua + local v = vim.version.parse(vim.system({'tmux', '-V'}):wait().stdout, {strict=false}) + if vim.version.gt(v, {3, 2, 0}) then + -- ... + end +< + +*vim.version()* returns the version of the current Nvim process. + +VERSION RANGE SPEC *version-range* + +A version "range spec" defines a semantic version range which can be tested +against a version, using |vim.version.range()|. + +Supported range specs are shown in the following table. Note: suffixed +versions (1.2.3-rc1) are not matched. > + 1.2.3 is 1.2.3 + =1.2.3 is 1.2.3 + >1.2.3 greater than 1.2.3 + <1.2.3 before 1.2.3 + >=1.2.3 at least 1.2.3 + <=1.2.3 at most 1.2.3 + ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" + ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" + ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) + ^0.0.1 is =0.0.1 (0.0.x is special) + ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) + ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) + ^1 is >=1.0.0 <2.0.0 "compatible with 1" + ~1 same "reasonably close to 1" + 1.x same + 1.* same + 1 same + * any version + x same + + 1.2.3 - 2.3.4 is >=1.2.3 <2.3.4 + + Partial right: missing pieces treated as x (2.3 => 2.3.x). + 1.2.3 - 2.3 is >=1.2.3 <2.4.0 + 1.2.3 - 2 is >=1.2.3 <3.0.0 + + Partial left: missing pieces treated as 0 (1.2 => 1.2.0). + 1.2 - 2.3.0 is 1.2.0 - 2.3.0 +< + + +*vim.VersionRange* + + Fields: ~ + • {from} (`vim.Version`) + • {to}? (`vim.Version`) + • {has} (`fun(self: vim.VersionRange, version: string|vim.Version): boolean`) + See |VersionRange:has()|. + + +VersionRange:has({version}) *VersionRange:has()* + Check if a version is in the range (inclusive `from`, exclusive `to`). + + Example: >lua + local r = vim.version.range('1.0.0 - 2.0.0') + print(r:has('1.9.9')) -- true + print(r:has('2.0.0')) -- false + print(r:has(vim.version())) -- check against current Nvim version +< + + Or use cmp(), le(), lt(), ge(), gt(), and/or eq() to compare a version + against `.to` and `.from` directly: >lua + local r = vim.version.range('1.0.0 - 2.0.0') -- >=1.0, <2.0 + print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) +< + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {version} (`string|vim.Version`) + + Return: ~ + (`boolean`) + + See also: ~ + • https://github.com/npm/node-semver#ranges + +vim.version.cmp({v1}, {v2}) *vim.version.cmp()* + Parses and compares two version objects (the result of + |vim.version.parse()|, or specified literally as a `{major, minor, patch}` + tuple, e.g. `{1, 0, 3}`). + + Example: >lua + if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then + -- ... + end + local v1 = vim.version.parse('1.0.3-pre') + local v2 = vim.version.parse('0.2.1') + if vim.version.cmp(v1, v2) == 0 then + -- ... + end +< + + Note: ~ + • Per semver, build metadata is ignored when comparing two + otherwise-equivalent versions. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) Version object. + • {v2} (`vim.Version|number[]|string`) Version to compare with `v1`. + + Return: ~ + (`integer`) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. + +vim.version.eq({v1}, {v2}) *vim.version.eq()* + Returns `true` if the given versions are equal. See |vim.version.cmp()| + for usage. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) + +vim.version.ge({v1}, {v2}) *vim.version.ge()* + Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. + + Attributes: ~ + Since: 0.10.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) + +vim.version.gt({v1}, {v2}) *vim.version.gt()* + Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) + +vim.version.intersect({r1}, {r2}) *vim.version.intersect()* + WARNING: This feature is experimental/unstable. + + Computes the common range shared by the given ranges. + + Parameters: ~ + • {r1} (`vim.VersionRange`) First range to intersect. See + |vim.VersionRange|. + • {r2} (`vim.VersionRange`) Second range to intersect. See + |vim.VersionRange|. + + Return: ~ + (`vim.VersionRange?`) Maximal range that is present inside both `r1` + and `r2`. `nil` if such range does not exist. See |vim.VersionRange|. + +vim.version.last({versions}) *vim.version.last()* + TODO: generalize this, move to func.lua + + Parameters: ~ + • {versions} (`vim.Version[]`) + + Return: ~ + (`vim.Version?`) + +vim.version.le({v1}, {v2}) *vim.version.le()* + Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. + + Attributes: ~ + Since: 0.10.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) + +vim.version.lt({v1}, {v2}) *vim.version.lt()* + Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) + +vim.version.parse({version}, {opts}) *vim.version.parse()* + Parses a semantic version string and returns a version object which can be + used with other `vim.version` functions. For example "1.0.1-rc1+build.2" + returns: > + { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } +< + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {version} (`string`) Version string to parse. + • {opts} (`table?`) Options for parsing. + • {strict}? (`boolean`, default: `false`) If `true`, no + coercion is attempted on input not conforming to semver + v2.0.0. If `false`, `parse()` attempts to coerce input + such as "1.0", "0-x", "tmux 3.2a" into valid versions. + + Return: ~ + (`vim.Version?`) `Version` object or `nil` if input is invalid. + + See also: ~ + • https://semver.org/spec/v2.0.0.html + +vim.version.range({spec}) *vim.version.range()* + Parses a semver |version-range| "spec" and returns |vim.VersionRange| + object: + + Attributes: ~ + Since: 0.9.0 + + Parameters: ~ + • {spec} (`string`) Version range "spec" + + Return: ~ + (`vim.VersionRange?`) See |vim.VersionRange|. + + ============================================================================== Lua module: tohtml *vim.tohtml* @@ -4896,31 +4889,38 @@ tohtml.tohtml({winid}, {opt}) *tohtml.tohtml.tohtml()* ============================================================================== -Lua module: vim.net *vim.net* +Lua module: vim._extui *vim._extui* -vim.net.request({url}, {opts}, {on_response}) *vim.net.request()* - Makes an HTTP GET request to the given URL (asynchronous). +WARNING: This is an experimental interface intended to replace the message +grid in the TUI. - This function operates in one mode: - • Asynchronous (non-blocking): Returns immediately and passes the response - object to the provided `on_response` handler on completetion. +To enable the experimental UI (default opts shown): >lua + require('vim._extui').enable({ + enable = true, -- Whether to enable or disable the UI. + msg = { -- Options related to the message module. + ---@type 'cmd'|'msg' Where to place regular messages, either in the + ---cmdline or in a separate ephemeral message window. + target = 'cmd', + timeout = 4000, -- Time a message is visible in the message window. + }, + }) +< - Parameters: ~ - • {url} (`string`) The URL for the request. - • {opts} (`table?`) Optional parameters: - • `verbose` (boolean|nil): Enables verbose output. - • `retry` (integer|nil): Number of retries on transient - failures (default: 3). - • `outpath` (string|nil): File path to save the - response body to. If set, the `body` value in the - Response Object will be `true` instead of the - response body. - • {on_response} (`fun(err?: string, response?: { body: string|boolean })`) - Callback invoked on request completetion. The `body` - field in the response object contains the raw response - data (text or binary). Called with (err, nil) on - failure, or (nil, { body = string|boolean }) on - success. +There are four separate window types used by this interface: +• "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and + messages if 'cmdheight' > 0. +• "msg": The message window; used for messages when 'cmdheight' == 0. +• "pager": The pager window; used for |:messages| and certain messages that + should be shown in full. +• "dialog": The dialog window; used for prompt messages that expect user + input. +These four windows are assigned the "cmd", "msg", "pager" and "dialog" +'filetype' respectively. Use a |FileType| autocommand to configure any local +options for these windows and their respective buffers. + +Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do +not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the +spilled lines. To see the full message, the |g<| command can be used. vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index c029b4921e..c1ae3bf414 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -1247,6 +1247,260 @@ register({lang}, {filetype}) *vim.treesitter.language.register()* • {filetype} (`string|string[]`) Filetype(s) to associate with lang +============================================================================== +Lua module: vim.treesitter.languagetree *treesitter-languagetree* + +A *LanguageTree* contains a tree of parsers: the root treesitter parser for +{lang} and any "injected" language parsers, which themselves may inject other +languages, recursively. For example a Lua buffer containing some Vimscript +commands needs multiple parsers to fully understand its contents. + +To create a LanguageTree (parser object) for a given buffer and language, use: >lua + local parser = vim.treesitter.get_parser(bufnr, lang) +< + +(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. Note: +currently the parser is retained for the lifetime of a buffer but this may +change; a plugin should keep a reference to the parser object if it wants +incremental updates. + +Whenever you need to access the current syntax tree, parse the buffer: >lua + local tree = parser:parse({ start_row, end_row }) +< + +This returns a table of immutable |treesitter-tree| objects representing the +current state of the buffer. When the plugin wants to access the state after a +(possible) edit it must call `parse()` again. If the buffer wasn't edited, the +same tree will be returned again without extra work. If the buffer was parsed +before, incremental parsing will be done of the changed parts. + +Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback, +you must call |vim.treesitter.get_parser()| before you register your callback. +But preferably parsing shouldn't be done directly in the change callback +anyway as they will be very frequent. Rather a plugin that does any kind of +analysis on a tree should use a timer to throttle too frequent updates. + + +LanguageTree:children() *LanguageTree:children()* + Returns a map of language to child tree. + + Return: ~ + (`table`) + +LanguageTree:contains({range}) *LanguageTree:contains()* + Determines whether {range} is contained in the |LanguageTree|. + + Parameters: ~ + • {range} (`table`) A table with the following fields: + • {[1]} (`integer`) start row + • {[2]} (`integer`) start column + • {[3]} (`integer`) end row + • {[4]} (`integer`) end column + + Return: ~ + (`boolean`) + +LanguageTree:destroy() *LanguageTree:destroy()* + Destroys this |LanguageTree| and all its children. + + Any cleanup logic should be performed here. + + Note: This DOES NOT remove this tree from a parent. Instead, + `remove_child` must be called on the parent to remove it. + +LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()* + Invokes the callback for each |LanguageTree| recursively. + + Note: This includes the invoking tree's child trees as well. + + Parameters: ~ + • {fn} (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`) + +LanguageTree:included_regions() *LanguageTree:included_regions()* + Gets the set of included regions managed by this LanguageTree. This can be + different from the regions set by injection query, because a partial + |LanguageTree:parse()| drops the regions outside the requested range. Each + list represents a range in the form of { {start_row}, {start_col}, + {start_bytes}, {end_row}, {end_col}, {end_bytes} }. + + Return: ~ + (`table`) + +LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* + Invalidates this parser and its children. + + Should only be called when the tracked state of the LanguageTree is not + valid against the parse tree in treesitter. Doesn't clear filesystem + cache. Called often, so needs to be fast. + + Parameters: ~ + • {reload} (`boolean?`) + + *LanguageTree:is_valid()* +LanguageTree:is_valid({exclude_children}, {range}) + Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| + reflects the latest state of the source. If invalid, user should call + |LanguageTree:parse()|. + + Parameters: ~ + • {exclude_children} (`boolean?`) whether to ignore the validity of + children (default `false`) + • {range} (`Range?`) range to check for validity + + Return: ~ + (`boolean`) + +LanguageTree:lang() *LanguageTree:lang()* + Gets the language of this tree node. + + Return: ~ + (`string`) + + *LanguageTree:language_for_range()* +LanguageTree:language_for_range({range}) + Gets the appropriate language that contains {range}. + + Parameters: ~ + • {range} (`table`) A table with the following fields: + • {[1]} (`integer`) start row + • {[2]} (`integer`) start column + • {[3]} (`integer`) end row + • {[4]} (`integer`) end column + + Return: ~ + (`vim.treesitter.LanguageTree`) tree Managing {range} + + *LanguageTree:named_node_for_range()* +LanguageTree:named_node_for_range({range}, {opts}) + Gets the smallest named node that contains {range}. + + Parameters: ~ + • {range} (`table`) A table with the following fields: + • {[1]} (`integer`) start row + • {[2]} (`integer`) start column + • {[3]} (`integer`) end row + • {[4]} (`integer`) end column + • {opts} (`table?`) A table with the following fields: + • {ignore_injections}? (`boolean`, default: `true`) Ignore + injected languages + + Return: ~ + (`TSNode?`) + + *LanguageTree:node_for_range()* +LanguageTree:node_for_range({range}, {opts}) + Gets the smallest node that contains {range}. + + Parameters: ~ + • {range} (`table`) A table with the following fields: + • {[1]} (`integer`) start row + • {[2]} (`integer`) start column + • {[3]} (`integer`) end row + • {[4]} (`integer`) end column + • {opts} (`table?`) A table with the following fields: + • {ignore_injections}? (`boolean`, default: `true`) Ignore + injected languages + + Return: ~ + (`TSNode?`) + +LanguageTree:parent() *LanguageTree:parent()* + Returns the parent tree. `nil` for the root tree. + + Return: ~ + (`vim.treesitter.LanguageTree?`) + +LanguageTree:parse({range}, {on_parse}) *LanguageTree:parse()* + Recursively parse all regions in the language tree using + |treesitter-parsers| for the corresponding languages and run injection + queries on the parsed trees to determine whether child trees should be + created and parsed. + + Any region with empty range (`{}`, typically only the root tree) is always + parsed; otherwise (typically injections) only if it intersects {range} (or + if {range} is `true`). + + Parameters: ~ + • {range} (`boolean|Range?`) Parse this range in the parser's + source. Set to `true` to run a complete parse of the + source (Note: Can be slow!) Set to `false|nil` to only + parse regions with empty ranges (typically only the root + tree without injections). + • {on_parse} (`fun(err?: string, trees?: table)?`) + Function invoked when parsing completes. When provided and + `vim.g._ts_force_sync_parsing` is not set, parsing will + run asynchronously. The first argument to the function is + a string representing the error type, in case of a failure + (currently only possible for timeouts). The second + argument is the list of trees returned by the parse (upon + success), or `nil` if the parse timed out (determined by + 'redrawtime'). + + If parsing was still able to finish synchronously (within + 3ms), `parse()` returns the list of trees. Otherwise, it + returns `nil`. + + Return: ~ + (`table?`) + + *LanguageTree:register_cbs()* +LanguageTree:register_cbs({cbs}, {recursive}) + Registers callbacks for the |LanguageTree|. + + Parameters: ~ + • {cbs} (`table`) An + |nvim_buf_attach()|-like table argument with the + following handlers: + • `on_bytes` : see |nvim_buf_attach()|. + • `on_changedtree` : a callback that will be called every + time the tree has syntactical changes. It will be + passed two arguments: a table of the ranges (as node + ranges) that changed and the changed tree. + • `on_child_added` : emitted when a child is added to the + tree. + • `on_child_removed` : emitted when a child is removed + from the tree. + • `on_detach` : emitted when the buffer is detached, see + |nvim_buf_detach_event|. Takes one argument, the number + of the buffer. + • {recursive} (`boolean?`) Apply callbacks recursively for all + children. Any new children will also inherit the + callbacks. + +LanguageTree:source() *LanguageTree:source()* + Returns the source content of the language tree (bufnr or string). + + Return: ~ + (`integer|string`) + + *LanguageTree:tree_for_range()* +LanguageTree:tree_for_range({range}, {opts}) + Gets the tree that contains {range}. + + Parameters: ~ + • {range} (`table`) A table with the following fields: + • {[1]} (`integer`) start row + • {[2]} (`integer`) start column + • {[3]} (`integer`) end row + • {[4]} (`integer`) end column + • {opts} (`table?`) A table with the following fields: + • {ignore_injections}? (`boolean`, default: `true`) Ignore + injected languages + + Return: ~ + (`TSTree?`) + +LanguageTree:trees() *LanguageTree:trees()* + Returns all trees of the regions parsed by this parser. Does not include + child languages. The result is list-like if + • this LanguageTree is the root, in which case the result is empty or a + singleton list; or + • the root LanguageTree is fully parsed. + + Return: ~ + (`table`) + + ============================================================================== Lua module: vim.treesitter.query *lua-treesitter-query* @@ -1608,258 +1862,4 @@ TSQuery:disable_pattern({pattern_index}) *TSQuery:disable_pattern()* • {pattern_index} (`integer`) -============================================================================== -Lua module: vim.treesitter.languagetree *treesitter-languagetree* - -A *LanguageTree* contains a tree of parsers: the root treesitter parser for -{lang} and any "injected" language parsers, which themselves may inject other -languages, recursively. For example a Lua buffer containing some Vimscript -commands needs multiple parsers to fully understand its contents. - -To create a LanguageTree (parser object) for a given buffer and language, use: >lua - local parser = vim.treesitter.get_parser(bufnr, lang) -< - -(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. Note: -currently the parser is retained for the lifetime of a buffer but this may -change; a plugin should keep a reference to the parser object if it wants -incremental updates. - -Whenever you need to access the current syntax tree, parse the buffer: >lua - local tree = parser:parse({ start_row, end_row }) -< - -This returns a table of immutable |treesitter-tree| objects representing the -current state of the buffer. When the plugin wants to access the state after a -(possible) edit it must call `parse()` again. If the buffer wasn't edited, the -same tree will be returned again without extra work. If the buffer was parsed -before, incremental parsing will be done of the changed parts. - -Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback, -you must call |vim.treesitter.get_parser()| before you register your callback. -But preferably parsing shouldn't be done directly in the change callback -anyway as they will be very frequent. Rather a plugin that does any kind of -analysis on a tree should use a timer to throttle too frequent updates. - - -LanguageTree:children() *LanguageTree:children()* - Returns a map of language to child tree. - - Return: ~ - (`table`) - -LanguageTree:contains({range}) *LanguageTree:contains()* - Determines whether {range} is contained in the |LanguageTree|. - - Parameters: ~ - • {range} (`table`) A table with the following fields: - • {[1]} (`integer`) start row - • {[2]} (`integer`) start column - • {[3]} (`integer`) end row - • {[4]} (`integer`) end column - - Return: ~ - (`boolean`) - -LanguageTree:destroy() *LanguageTree:destroy()* - Destroys this |LanguageTree| and all its children. - - Any cleanup logic should be performed here. - - Note: This DOES NOT remove this tree from a parent. Instead, - `remove_child` must be called on the parent to remove it. - -LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()* - Invokes the callback for each |LanguageTree| recursively. - - Note: This includes the invoking tree's child trees as well. - - Parameters: ~ - • {fn} (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`) - -LanguageTree:included_regions() *LanguageTree:included_regions()* - Gets the set of included regions managed by this LanguageTree. This can be - different from the regions set by injection query, because a partial - |LanguageTree:parse()| drops the regions outside the requested range. Each - list represents a range in the form of { {start_row}, {start_col}, - {start_bytes}, {end_row}, {end_col}, {end_bytes} }. - - Return: ~ - (`table`) - -LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* - Invalidates this parser and its children. - - Should only be called when the tracked state of the LanguageTree is not - valid against the parse tree in treesitter. Doesn't clear filesystem - cache. Called often, so needs to be fast. - - Parameters: ~ - • {reload} (`boolean?`) - - *LanguageTree:is_valid()* -LanguageTree:is_valid({exclude_children}, {range}) - Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| - reflects the latest state of the source. If invalid, user should call - |LanguageTree:parse()|. - - Parameters: ~ - • {exclude_children} (`boolean?`) whether to ignore the validity of - children (default `false`) - • {range} (`Range?`) range to check for validity - - Return: ~ - (`boolean`) - -LanguageTree:lang() *LanguageTree:lang()* - Gets the language of this tree node. - - Return: ~ - (`string`) - - *LanguageTree:language_for_range()* -LanguageTree:language_for_range({range}) - Gets the appropriate language that contains {range}. - - Parameters: ~ - • {range} (`table`) A table with the following fields: - • {[1]} (`integer`) start row - • {[2]} (`integer`) start column - • {[3]} (`integer`) end row - • {[4]} (`integer`) end column - - Return: ~ - (`vim.treesitter.LanguageTree`) tree Managing {range} - - *LanguageTree:named_node_for_range()* -LanguageTree:named_node_for_range({range}, {opts}) - Gets the smallest named node that contains {range}. - - Parameters: ~ - • {range} (`table`) A table with the following fields: - • {[1]} (`integer`) start row - • {[2]} (`integer`) start column - • {[3]} (`integer`) end row - • {[4]} (`integer`) end column - • {opts} (`table?`) A table with the following fields: - • {ignore_injections}? (`boolean`, default: `true`) Ignore - injected languages - - Return: ~ - (`TSNode?`) - - *LanguageTree:node_for_range()* -LanguageTree:node_for_range({range}, {opts}) - Gets the smallest node that contains {range}. - - Parameters: ~ - • {range} (`table`) A table with the following fields: - • {[1]} (`integer`) start row - • {[2]} (`integer`) start column - • {[3]} (`integer`) end row - • {[4]} (`integer`) end column - • {opts} (`table?`) A table with the following fields: - • {ignore_injections}? (`boolean`, default: `true`) Ignore - injected languages - - Return: ~ - (`TSNode?`) - -LanguageTree:parent() *LanguageTree:parent()* - Returns the parent tree. `nil` for the root tree. - - Return: ~ - (`vim.treesitter.LanguageTree?`) - -LanguageTree:parse({range}, {on_parse}) *LanguageTree:parse()* - Recursively parse all regions in the language tree using - |treesitter-parsers| for the corresponding languages and run injection - queries on the parsed trees to determine whether child trees should be - created and parsed. - - Any region with empty range (`{}`, typically only the root tree) is always - parsed; otherwise (typically injections) only if it intersects {range} (or - if {range} is `true`). - - Parameters: ~ - • {range} (`boolean|Range?`) Parse this range in the parser's - source. Set to `true` to run a complete parse of the - source (Note: Can be slow!) Set to `false|nil` to only - parse regions with empty ranges (typically only the root - tree without injections). - • {on_parse} (`fun(err?: string, trees?: table)?`) - Function invoked when parsing completes. When provided and - `vim.g._ts_force_sync_parsing` is not set, parsing will - run asynchronously. The first argument to the function is - a string representing the error type, in case of a failure - (currently only possible for timeouts). The second - argument is the list of trees returned by the parse (upon - success), or `nil` if the parse timed out (determined by - 'redrawtime'). - - If parsing was still able to finish synchronously (within - 3ms), `parse()` returns the list of trees. Otherwise, it - returns `nil`. - - Return: ~ - (`table?`) - - *LanguageTree:register_cbs()* -LanguageTree:register_cbs({cbs}, {recursive}) - Registers callbacks for the |LanguageTree|. - - Parameters: ~ - • {cbs} (`table`) An - |nvim_buf_attach()|-like table argument with the - following handlers: - • `on_bytes` : see |nvim_buf_attach()|. - • `on_changedtree` : a callback that will be called every - time the tree has syntactical changes. It will be - passed two arguments: a table of the ranges (as node - ranges) that changed and the changed tree. - • `on_child_added` : emitted when a child is added to the - tree. - • `on_child_removed` : emitted when a child is removed - from the tree. - • `on_detach` : emitted when the buffer is detached, see - |nvim_buf_detach_event|. Takes one argument, the number - of the buffer. - • {recursive} (`boolean?`) Apply callbacks recursively for all - children. Any new children will also inherit the - callbacks. - -LanguageTree:source() *LanguageTree:source()* - Returns the source content of the language tree (bufnr or string). - - Return: ~ - (`integer|string`) - - *LanguageTree:tree_for_range()* -LanguageTree:tree_for_range({range}, {opts}) - Gets the tree that contains {range}. - - Parameters: ~ - • {range} (`table`) A table with the following fields: - • {[1]} (`integer`) start row - • {[2]} (`integer`) start column - • {[3]} (`integer`) end row - • {[4]} (`integer`) end column - • {opts} (`table?`) A table with the following fields: - • {ignore_injections}? (`boolean`, default: `true`) Ignore - injected languages - - Return: ~ - (`TSTree?`) - -LanguageTree:trees() *LanguageTree:trees()* - Returns all trees of the regions parsed by this parser. Does not include - child languages. The result is list-like if - • this LanguageTree is the root, in which case the result is empty or a - singleton list; or - • the root LanguageTree is fully parsed. - - Return: ~ - (`table`) - - vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua index b46c687406..bc53d2cf74 100755 --- a/src/gen/gen_vimdoc.lua +++ b/src/gen/gen_vimdoc.lua @@ -105,17 +105,20 @@ local config = { api = { filename = 'api.txt', section_order = { + -- Sections at the top, in a specific order: 'vim.c', 'vimscript.c', - 'command.c', - 'options.c', - 'buffer.c', - 'extmark.c', - 'window.c', - 'win_config.c', - 'tabpage.c', + + -- Sections in alphanumeric order: 'autocmd.c', + 'buffer.c', + 'command.c', + 'extmark.c', + 'options.c', + 'tabpage.c', 'ui.c', + 'win_config.c', + 'window.c', }, fn_name_pat = 'nvim_.*', files = { 'src/nvim/api' }, @@ -132,66 +135,71 @@ local config = { lua = { filename = 'lua.txt', section_order = { - 'hl.lua', - 'mpack.lua', - 'json.lua', - 'base64.lua', - 'spell.lua', + -- Sections at the top, in a specific order: 'builtin.lua', '_options.lua', '_editor.lua', - '_system.lua', '_inspector.lua', 'shared.lua', - 'loader.lua', - 'uri.lua', - 'ui.lua', - '_extui.lua', + + -- Sections in alphanumeric order: + 'base64.lua', 'filetype.lua', - 'keymap.lua', 'fs.lua', 'glob.lua', + 'hl.lua', + 'iter.lua', + 'json.lua', + 'keymap.lua', + 'loader.lua', 'lpeg.lua', + 'mpack.lua', + 'net.lua', 're.lua', 'regex.lua', 'secure.lua', - 'version.lua', - 'iter.lua', 'snippet.lua', + 'spell.lua', + '_system.lua', 'text.lua', + 'ui.lua', + 'uri.lua', + 'version.lua', + + -- Sections at the end, in a specific order: 'tohtml.lua', - 'net.lua', + '_extui.lua', }, files = { - 'runtime/lua/vim/iter.lua', + 'runtime/lua/tohtml.lua', 'runtime/lua/vim/_editor.lua', - 'runtime/lua/vim/_options.lua', - 'runtime/lua/vim/shared.lua', - 'runtime/lua/vim/loader.lua', - 'runtime/lua/vim/uri.lua', - 'runtime/lua/vim/ui.lua', 'runtime/lua/vim/_extui.lua', + 'runtime/lua/vim/_inspector.lua', + 'runtime/lua/vim/_meta/base64.lua', + 'runtime/lua/vim/_meta/builtin.lua', + 'runtime/lua/vim/_meta/json.lua', + 'runtime/lua/vim/_meta/lpeg.lua', + 'runtime/lua/vim/_meta/mpack.lua', + 'runtime/lua/vim/_meta/re.lua', + 'runtime/lua/vim/_meta/regex.lua', + 'runtime/lua/vim/_meta/spell.lua', + 'runtime/lua/vim/_options.lua', 'runtime/lua/vim/_system.lua', 'runtime/lua/vim/filetype.lua', - 'runtime/lua/vim/keymap.lua', 'runtime/lua/vim/fs.lua', + 'runtime/lua/vim/glob.lua', 'runtime/lua/vim/hl.lua', + 'runtime/lua/vim/iter.lua', + 'runtime/lua/vim/keymap.lua', + 'runtime/lua/vim/loader.lua', + 'runtime/lua/vim/net.lua', 'runtime/lua/vim/secure.lua', - 'runtime/lua/vim/version.lua', - 'runtime/lua/vim/_inspector.lua', + 'runtime/lua/vim/shared.lua', 'runtime/lua/vim/snippet.lua', 'runtime/lua/vim/text.lua', - 'runtime/lua/vim/glob.lua', - 'runtime/lua/vim/_meta/builtin.lua', - 'runtime/lua/vim/_meta/mpack.lua', - 'runtime/lua/vim/_meta/json.lua', - 'runtime/lua/vim/_meta/base64.lua', - 'runtime/lua/vim/_meta/regex.lua', - 'runtime/lua/vim/_meta/lpeg.lua', - 'runtime/lua/vim/_meta/re.lua', - 'runtime/lua/vim/_meta/spell.lua', - 'runtime/lua/tohtml.lua', - 'runtime/lua/vim/net.lua', + 'runtime/lua/vim/ui.lua', + 'runtime/lua/vim/uri.lua', + 'runtime/lua/vim/version.lua', }, fn_xform = function(fun) if contains(fun.module, { 'vim.uri', 'vim.shared', 'vim._editor' }) then @@ -222,20 +230,6 @@ local config = { elseif name == 'builtin' then return 'VIM' end - if - contains(name, { - 'hl', - 'mpack', - 'json', - 'base64', - 'spell', - 'regex', - 'lpeg', - 're', - }) - then - return 'VIM.' .. name:upper() - end if name == 'tohtml' then return 'Lua module: tohtml' end @@ -272,22 +266,27 @@ local config = { lsp = { filename = 'lsp.txt', section_order = { + -- Sections at the top, in a specific order: 'lsp.lua', - 'client.lua', + + -- Sections in alphanumeric order: 'buf.lua', - 'diagnostic.lua', + 'client.lua', 'codelens.lua', 'completion.lua', - 'folding_range.lua', - 'inlay_hint.lua', - 'tagfunc.lua', - 'semantic_tokens.lua', + 'diagnostic.lua', 'document_color.lua', - 'linked_editing_range.lua', + 'folding_range.lua', 'handlers.lua', - 'util.lua', + 'inlay_hint.lua', + 'linked_editing_range.lua', 'log.lua', 'rpc.lua', + 'semantic_tokens.lua', + 'tagfunc.lua', + + -- Sections at the end, in a specific order: + 'util.lua', 'protocol.lua', }, files = { @@ -329,15 +328,18 @@ local config = { treesitter = { filename = 'treesitter.txt', section_order = { + -- Sections at the top, in a specific order: 'tstree.lua', 'tsnode.lua', 'treesitter.lua', + + -- Sections in alphanumeric order: + 'dev.lua', + 'highlighter.lua', 'language.lua', + 'languagetree.lua', 'query.lua', 'tsquery.lua', - 'highlighter.lua', - 'languagetree.lua', - 'dev.lua', }, append_only = { 'tsquery.lua' }, files = {