commit 39e402caa511f311b4f43a6c6f18bacba8c47c49
parent e23794b090e0b3b7f1b26460f317726fd2ebac8d
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 3 Aug 2025 01:03:09 -0400
docs: reorder sections #35140
Problem:
Generated docs sections are ordered randomly. This matters when showing
an outline or table of contents (e.g. `gO`).
Solution:
Specify which sections have an intentional ordering; sort the rest by
name.
Diffstat:
| M | runtime/doc/api.txt | | | 1674 | ++++++++++++++++++++++++++++++++++++++++---------------------------------------- |
| M | runtime/doc/lsp.txt | | | 1482 | ++++++++++++++++++++++++++++++++++++++++---------------------------------------- |
| M | runtime/doc/lua.txt | | | 3680 | ++++++++++++++++++++++++++++++++++++++++---------------------------------------- |
| M | runtime/doc/treesitter.txt | | | 508 | ++++++++++++++++++++++++++++++++++++++++---------------------------------------- |
| M | src/gen/gen_vimdoc.lua | | | 128 | ++++++++++++++++++++++++++++++++++++++++--------------------------------------- |
5 files changed, 3737 insertions(+), 3735 deletions(-)
diff --git 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`)
-
- See also: ~
- • nvim_create_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.
- *nvim_buf_del_user_command()*
-nvim_buf_del_user_command({buffer}, {name})
- Delete a buffer-local user-defined command.
+nvim_create_augroup({name}, {opts}) *nvim_create_augroup()*
+ Create or get an autocommand group |autocmd-groups|.
- Only commands created with |:command-buffer| or
- |nvim_buf_create_user_command()| can be deleted with this function.
+ 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: ~
- • {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.
+ • {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: ~
- (`string`) Command output (non-error, non-shell |:!|) if `output` is
- true, else empty string.
+ (`integer`) Integer id of the created group.
See also: ~
- • |nvim_exec2()|
- • |nvim_command()|
-
- *nvim_create_user_command()*
-nvim_create_user_command({name}, {command}, {opts})
- Creates a global |user-commands| command.
+ • |autocmd-groups|
- For Lua usage see |lua-guide-commands-create|.
+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: >vim
- :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
- :SayHello
- Hello world!
+ 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
+ })
<
- 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
- <args>
- • fargs: (table) The args split by unescaped whitespace
- (when more than one argument is allowed), if any <f-args>
- • nargs: (string) Number of arguments |:command-nargs|
- • bang: (boolean) "true" if the command was executed with a
- ! modifier <bang>
- • line1: (number) The starting line of the command range
- <line1>
- • line2: (number) The final line of the command range
- <line2>
- • range: (number) The number of items in the command range:
- 0, 1, or 2 <range>
- • count: (number) Any count supplied <count>
- • reg: (string) The optional register, if specified <reg>
- • mods: (string) Command modifiers, if any <mods>
- • 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|
+ 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'",
+ })
+<
-nvim_del_user_command({name}) *nvim_del_user_command()*
- Delete a user-defined command.
+ 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: ~
- • {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}
+ • {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) <afile> (not expanded to a full path)
+ • match: (string) <amatch> (expanded to a full path)
+ • buf: (number) <abuf>
+ • data: (any) arbitrary data passed from
+ |nvim_exec_autocmds()| *event-data*
+ • 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: ~
- (`table<string,vim.api.keyset.command_info>`) Map of maps describing
- commands.
+ (`integer`) Autocommand id (number)
See also: ~
- • |nvim_get_all_options_info()|
+ • |autocommand|
+ • |nvim_del_autocmd()|
-nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()*
- Parse command line.
+nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()*
+ Delete an autocommand group by id.
- Doesn't check the validity of command arguments.
+ 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: ~
- |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.
-
- Return: ~
- (`vim.api.keyset.cmd`) Dict containing command information, with these
- keys:
- • cmd: (string) Command name.
- • range: (array) (optional) Command range (<line1> <line2>). 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 <count>. Omitted if command
- cannot take a count.
- • reg: (string) (optional) Command <register>. Omitted if command
- cannot take a register.
- • bang: (boolean) Whether command contains a <bang> (!) 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|.
-
+ • {id} (`integer`) Integer The id of the group.
-==============================================================================
-Options Functions *api-options*
+ See also: ~
+ • |nvim_del_augroup_by_name()|
+ • |nvim_create_augroup()|
-nvim_get_all_options_info() *nvim_get_all_options_info()*
- Gets the option information for all options.
+nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
+ Delete an autocommand group by name.
- The dict has the full option names as keys and option metadata dicts as
- detailed at |nvim_get_option_info2()|.
+ 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.5.0
+ Since: 0.7.0
- Return: ~
- (`table<string,any>`) dict of all options
+ Parameters: ~
+ • {name} (`string`) String The name of the group.
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
+ • |autocmd-groups|
- 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.
+nvim_del_autocmd({id}) *nvim_del_autocmd()*
+ Deletes an autocommand by id.
Attributes: ~
- Since: 0.9.0
+ 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".
-
- Return: ~
- (`vim.api.keyset.get_option_info`) Option Information
+ • {id} (`integer`) Integer Autocommand id returned by
+ |nvim_create_autocmd()|
-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}.
+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: ~
- • {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.
+ • {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 <nomodeline>.
+ • data (any): arbitrary data to send to the autocommand
+ callback. See |nvim_create_autocmd()| for details.
- Return: ~
- (`any`) Option value
+ See also: ~
+ • |:doautocmd|
- *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_get_autocmds({opts}) *nvim_get_autocmds()*
+ Get all autocommands that match the corresponding {opts}.
- Note the options {win} and {buf} cannot be used together.
+ 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: ~
- • {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.
+ • {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|:
==============================================================================
@@ -2797,6 +2705,250 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
==============================================================================
+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
+ <args>
+ • fargs: (table) The args split by unescaped whitespace
+ (when more than one argument is allowed), if any <f-args>
+ • nargs: (string) Number of arguments |:command-nargs|
+ • bang: (boolean) "true" if the command was executed with a
+ ! modifier <bang>
+ • line1: (number) The starting line of the command range
+ <line1>
+ • line2: (number) The final line of the command range
+ <line2>
+ • range: (number) The number of items in the command range:
+ 0, 1, or 2 <range>
+ • count: (number) Any count supplied <count>
+ • reg: (string) The optional register, if specified <reg>
+ • mods: (string) Command modifiers, if any <mods>
+ • 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<string,vim.api.keyset.command_info>`) 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 (<line1> <line2>). 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 <count>. Omitted if command
+ cannot take a count.
+ • reg: (string) (optional) Command <register>. Omitted if command
+ cannot take a register.
+ • bang: (boolean) Whether command contains a <bang> (!) 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*
*nvim_buf_clear_namespace()*
@@ -3183,296 +3335,330 @@ nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()*
==============================================================================
-Window Functions *api-window*
+Options Functions *api-options*
-nvim_win_call({window}, {fun}) *nvim_win_call()*
- Calls a function with window as temporary current window.
+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: ~
- Lua |vim.api| only
Since: 0.5.0
- Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {fun} (`function`) Function to call inside the window (currently
- Lua callable only)
-
Return: ~
- (`any`) Return value of function.
+ (`table<string,any>`) dict of all options
See also: ~
- • |win_execute()|
- • |nvim_buf_call()|
+ • |nvim_get_commands()|
-nvim_win_close({window}, {force}) *nvim_win_close()*
- Closes the window (like |:close| with a |window-ID|).
+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: ~
- not allowed when |textlock| is active
- Since: 0.4.0
+ Since: 0.9.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {force} (`boolean`) Behave like `:close!` The last window of a
- buffer with unwritten changes can be closed. The buffer will
- become hidden, even if 'hidden' is not set.
+ • {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".
-nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
- Removes a window-scoped (w:) variable
+ 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.1.0
+ Since: 0.7.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {name} (`string`) Variable name
+ • {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.
-nvim_win_get_buf({window}) *nvim_win_get_buf()*
- Gets the current buffer in a window
+ 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.1.0
+ Since: 0.7.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {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.
- Return: ~
- (`integer`) Buffer id
-nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
- Gets the (1,0)-indexed, buffer-relative cursor position for a given window
- (different windows showing the same buffer have independent cursor
- positions). |api-indexing|
+==============================================================================
+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: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
-
- Return: ~
- (`[integer, integer]`) (row, col) tuple
-
- See also: ~
- • |getcurpos()|
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
-nvim_win_get_height({window}) *nvim_win_get_height()*
- Gets the window height
+nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
+ Gets the tabpage number
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- (`integer`) Height as a count of rows
+ (`integer`) Tabpage number
-nvim_win_get_number({window}) *nvim_win_get_number()*
- Gets the window number
+nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
+ Gets a tab-scoped (t:) variable
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
Return: ~
- (`integer`) Window number
+ (`any`) Variable value
-nvim_win_get_position({window}) *nvim_win_get_position()*
- Gets the window position in display cells. First position is zero.
+nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
+ Gets the current window in a tabpage
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- (`[integer, integer]`) (row, col) tuple with the window position
+ (`integer`) |window-ID|
-nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
- Gets the window tabpage
+nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
+ Checks if a tabpage is valid
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- (`integer`) Tabpage that contains the window
+ (`boolean`) true if the tabpage is valid, false otherwise
-nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
- Gets a window-scoped (w:) variable
+nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
+ Gets the windows in a tabpage
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {name} (`string`) Variable name
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- (`any`) Variable value
+ (`integer[]`) List of windows in `tabpage`
-nvim_win_get_width({window}) *nvim_win_get_width()*
- Gets the window width
+ *nvim_tabpage_set_var()*
+nvim_tabpage_set_var({tabpage}, {name}, {value})
+ Sets a tab-scoped (t:) variable
Attributes: ~
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
- Return: ~
- (`integer`) Width as a count of columns
+nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()*
+ Sets the current window in a tabpage
-nvim_win_hide({window}) *nvim_win_hide()*
- Closes the window and hide the buffer it contains (like |:hide| with a
- |window-ID|).
+ Attributes: ~
+ Since: 0.10.0
- Like |:hide| the buffer becomes hidden unless another window is editing
- it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close|
- or |nvim_win_close()|, which will close the buffer.
+ Parameters: ~
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {win} (`integer`) |window-ID|, must already belong to {tabpage}
- Attributes: ~
- not allowed when |textlock| is active
- Since: 0.5.0
- Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+==============================================================================
+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()|
-nvim_win_is_valid({window}) *nvim_win_is_valid()*
- Checks if a window is valid
+ 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: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
+ • {width} (`integer`) Requested screen columns
+ • {height} (`integer`) Requested screen rows
+ • {options} (`table<string,any>`) |ui-option| map
- Return: ~
- (`boolean`) true if the window is valid, false otherwise
+nvim_ui_detach() *nvim_ui_detach()*
+ Deactivates UI events on the channel.
-nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
- Sets the current buffer in a window, without side effects
+ Removes the client from the list of UIs. |nvim_list_uis()|
Attributes: ~
- not allowed when |textlock| is active
- Since: 0.3.2
+ |RPC| only
+ Since: 0.1.0
- Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {buffer} (`integer`) Buffer id
+ *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.
-nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
- Sets the (1,0)-indexed cursor position in the window. |api-indexing| This
- scrolls the window even if it is not the current one.
+ 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: ~
- Since: 0.1.0
+ |RPC| only
+ Since: 0.5.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {pos} (`[integer, integer]`) (row, col) tuple representing the new
- position
+ • {width} (`number`) Popupmenu width.
+ • {height} (`number`) Popupmenu height.
+ • {row} (`number`) Popupmenu row.
+ • {col} (`number`) Popupmenu height.
-nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
- Sets the window height.
+nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()*
+ Tells Nvim the number of elements displaying in the popupmenu, to decide
+ <PageUp> and <PageDown> movement.
Attributes: ~
- Since: 0.1.0
+ |RPC| only
+ Since: 0.4.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {height} (`integer`) Height as a count of rows
-
-nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()*
- Set highlight namespace for a window. This will use highlights defined
- with |nvim_set_hl()| for this namespace, but fall back to global
- highlights (ns=0) when missing.
+ • {height} (`integer`) Popupmenu height, must be greater than zero.
- This takes precedence over the 'winhighlight' option.
+nvim_ui_set_focus({gained}) *nvim_ui_set_focus()*
+ Tells the nvim server if focus was gained or lost by the GUI
Attributes: ~
- Since: 0.8.0
+ |RPC| only
+ Since: 0.9.0
Parameters: ~
- • {window} (`integer`)
- • {ns_id} (`integer`) the namespace to use
+ • {gained} (`boolean`)
-nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
- Sets a window-scoped (w:) variable
+nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
Attributes: ~
+ |RPC| only
Since: 0.1.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {name} (`string`) Variable name
- • {value} (`any`) Variable value
+ • {name} (`string`)
+ • {value} (`any`)
-nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
- Sets the window width. This will only succeed if the screen is split
- vertically.
+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: ~
- Since: 0.1.0
+ |RPC| only
+ Since: 0.10.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window
- • {width} (`integer`) Width as a count of columns
+ • {event} (`string`) Event name
+ • {value} (`any`) Event payload
-nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
- Computes the number of screen lines occupied by a range of text in a given
- window. Works for off-screen text and takes folds into account.
+nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
- Diff filler or virtual lines above a line are counted as a part of that
- line, unless the line is on "start_row" and "start_vcol" is specified.
+ Attributes: ~
+ |RPC| only
+ Since: 0.1.0
- Diff filler or virtual lines below the last buffer line are counted in the
- result when "end_row" is omitted.
+ Parameters: ~
+ • {width} (`integer`)
+ • {height} (`integer`)
- Line indexing is similar to |nvim_buf_get_text()|.
+ *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: ~
- Since: 0.10.0
+ |RPC| only
+ Since: 0.4.0
Parameters: ~
- • {window} (`integer`) |window-ID|, or 0 for current window.
- • {opts} (`vim.api.keyset.win_text_height`) Optional parameters:
- • start_row: Starting line index, 0-based inclusive. When
- omitted start at the very top.
- • end_row: Ending line index, 0-based inclusive. When
- omitted end at the very bottom.
- • start_vcol: Starting virtual column index on "start_row",
- 0-based inclusive, rounded down to full screen lines. When
- omitted include the whole line.
- • end_vcol: Ending virtual column index on "end_row",
- 0-based exclusive, rounded up to full screen lines. When 0
- only include diff filler and virtual lines above
- "end_row". When omitted include the whole line.
- • max_height: Don't add the height of lines below the row
- for which this height is reached. Useful to e.g. limit the
- height to the window height, avoiding unnecessary work. Or
- to find out how many buffer lines beyond "start_row" take
- up a certain number of logical lines (returned in
- "end_row" and "end_vcol").
-
- Return: ~
- (`vim.api.keyset.win_text_height_ret`) Dict containing text height
- information, with these keys:
- • all: The total number of screen lines occupied by the range.
- • fill: The number of diff filler or virtual lines among them.
- • end_row: The row on which the returned height is reached (first row
- of a closed fold).
- • end_vcol: Ending virtual column in "end_row" where "max_height" or
- the returned height is reached. 0 if "end_row" is a closed fold.
-
- See also: ~
- • |virtcol()| for text width.
+ • {grid} (`integer`) The handle of the grid to be changed.
+ • {width} (`integer`) The new requested width.
+ • {height} (`integer`) The new requested height.
==============================================================================
@@ -3654,522 +3840,336 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
|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
+ Return: ~
+ (`integer`) |window-ID|, or 0 on error
- Parameters: ~
- • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+nvim_win_get_config({window}) *nvim_win_get_config()*
+ Gets window configuration.
- Return: ~
- (`boolean`) true if the tabpage is valid, false otherwise
+ The returned value may be given to |nvim_open_win()|.
-nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
- Gets the windows in a tabpage
+ `relative` is empty for normal windows.
Attributes: ~
- Since: 0.1.0
+ Since: 0.4.0
Parameters: ~
- • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {window} (`integer`) |window-ID|, or 0 for current window
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
+ (`vim.api.keyset.win_config`) Map defining the window configuration,
+ see |nvim_open_win()|
- Parameters: ~
- • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
- • {name} (`string`) Variable name
- • {value} (`any`) Variable value
+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.
-nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()*
- Sets the current window in a tabpage
+ When reconfiguring a window, absent option keys will not be changed.
+ `row`/`col` and `relative` must be reconfigured together.
Attributes: ~
- Since: 0.10.0
+ Since: 0.4.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()|.
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {config} (`vim.api.keyset.win_config`) Map defining the window
+ configuration, see |nvim_open_win()|
- Attributes: ~
- Since: 0.7.0
+ See also: ~
+ • |nvim_open_win()|
- 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|.
+==============================================================================
+Window Functions *api-window*
- To get an existing group id, do: >lua
- local id = vim.api.nvim_create_augroup('my.lsp.config', {
- clear = false
- })
-<
+nvim_win_call({window}, {fun}) *nvim_win_call()*
+ Calls a function with window as temporary current window.
Attributes: ~
- Since: 0.7.0
+ Lua |vim.api| only
+ Since: 0.5.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|.
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {fun} (`function`) Function to call inside the window (currently
+ Lua callable only)
Return: ~
- (`integer`) Integer id of the created group.
+ (`any`) Return value of function.
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'",
- })
-<
+ • |win_execute()|
+ • |nvim_buf_call()|
- 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'
-<
+nvim_win_close({window}, {force}) *nvim_win_close()*
+ Closes the window (like |:close| with a |window-ID|).
Attributes: ~
- Since: 0.7.0
+ not allowed when |textlock| is active
+ Since: 0.4.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) <afile> (not expanded to a full path)
- • match: (string) <amatch> (expanded to a full path)
- • buf: (number) <abuf>
- • data: (any) arbitrary data passed from
- |nvim_exec_autocmds()| *event-data*
- • 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)
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {force} (`boolean`) Behave like `:close!` The last window of a
+ buffer with unwritten changes can be closed. The buffer will
+ become hidden, even if 'hidden' is not set.
- See also: ~
- • |autocommand|
- • |nvim_del_autocmd()|
+nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
+ Removes a window-scoped (w:) variable
-nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()*
- Delete an autocommand group by id.
+ Attributes: ~
+ Since: 0.1.0
- To get a group id one can use |nvim_get_autocmds()|.
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable 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.
+nvim_win_get_buf({window}) *nvim_win_get_buf()*
+ Gets the current buffer in a window
Attributes: ~
- Since: 0.7.0
+ Since: 0.1.0
Parameters: ~
- • {id} (`integer`) Integer The id of the group.
-
- See also: ~
- • |nvim_del_augroup_by_name()|
- • |nvim_create_augroup()|
+ • {window} (`integer`) |window-ID|, or 0 for current window
-nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
- Delete an autocommand group by name.
+ Return: ~
+ (`integer`) Buffer id
- 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.
+nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
+ Gets the (1,0)-indexed, buffer-relative cursor position for a given window
+ (different windows showing the same buffer have independent cursor
+ positions). |api-indexing|
Attributes: ~
- Since: 0.7.0
+ Since: 0.1.0
Parameters: ~
- • {name} (`string`) String The name of the group.
+ • {window} (`integer`) |window-ID|, or 0 for current window
+
+ Return: ~
+ (`[integer, integer]`) (row, col) tuple
See also: ~
- • |autocmd-groups|
+ • |getcurpos()|
-nvim_del_autocmd({id}) *nvim_del_autocmd()*
- Deletes an autocommand by id.
+nvim_win_get_height({window}) *nvim_win_get_height()*
+ Gets the window height
Attributes: ~
- Since: 0.7.0
+ Since: 0.1.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
+ • {window} (`integer`) |window-ID|, or 0 for current window
- 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 <nomodeline>.
- • data (any): arbitrary data to send to the autocommand
- callback. See |nvim_create_autocmd()| for details.
+ Return: ~
+ (`integer`) Height as a count of rows
- See also: ~
- • |:doautocmd|
+nvim_win_get_number({window}) *nvim_win_get_number()*
+ Gets the window number
-nvim_get_autocmds({opts}) *nvim_get_autocmds()*
- Get all autocommands that match the corresponding {opts}.
+ Attributes: ~
+ Since: 0.1.0
- 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'}
- })
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
- -- All commands from one group
- autocommands = vim.api.nvim_get_autocmds({
- group = 'MyGroup',
- })
-<
+ Return: ~
+ (`integer`) Window number
- NOTE: When multiple patterns or events are provided, it will find all the
- autocommands that match any combination of them.
+nvim_win_get_position({window}) *nvim_win_get_position()*
+ Gets the window position in display cells. First position is zero.
Attributes: ~
- Since: 0.7.0
+ Since: 0.1.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}
+ • {window} (`integer`) |window-ID|, or 0 for current window
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|:
+ (`[integer, integer]`) (row, col) tuple with the window position
+nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
+ Gets the window tabpage
-==============================================================================
-UI Functions *api-ui*
+ Attributes: ~
+ Since: 0.1.0
-nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
- Activates UI events on the channel.
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
- 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()|
+ Return: ~
+ (`integer`) Tabpage that contains the window
- 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.
+nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
+ Gets a window-scoped (w:) variable
Attributes: ~
- |RPC| only
Since: 0.1.0
Parameters: ~
- • {width} (`integer`) Requested screen columns
- • {height} (`integer`) Requested screen rows
- • {options} (`table<string,any>`) |ui-option| map
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable name
-nvim_ui_detach() *nvim_ui_detach()*
- Deactivates UI events on the channel.
+ Return: ~
+ (`any`) Variable value
- Removes the client from the list of UIs. |nvim_list_uis()|
+nvim_win_get_width({window}) *nvim_win_get_width()*
+ Gets the window width
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.
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
- 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.
+ Return: ~
+ (`integer`) Width as a count of columns
+
+nvim_win_hide({window}) *nvim_win_hide()*
+ Closes the window and hide the buffer it contains (like |:hide| with a
+ |window-ID|).
+
+ Like |:hide| the buffer becomes hidden unless another window is editing
+ it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close|
+ or |nvim_win_close()|, which will close the buffer.
Attributes: ~
- |RPC| only
+ not allowed when |textlock| is active
Since: 0.5.0
Parameters: ~
- • {width} (`number`) Popupmenu width.
- • {height} (`number`) Popupmenu height.
- • {row} (`number`) Popupmenu row.
- • {col} (`number`) Popupmenu height.
+ • {window} (`integer`) |window-ID|, or 0 for current window
-nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()*
- Tells Nvim the number of elements displaying in the popupmenu, to decide
- <PageUp> and <PageDown> movement.
+nvim_win_is_valid({window}) *nvim_win_is_valid()*
+ Checks if a window is valid
Attributes: ~
- |RPC| only
- Since: 0.4.0
+ Since: 0.1.0
Parameters: ~
- • {height} (`integer`) Popupmenu height, must be greater than zero.
+ • {window} (`integer`) |window-ID|, or 0 for current window
-nvim_ui_set_focus({gained}) *nvim_ui_set_focus()*
- Tells the nvim server if focus was gained or lost by the GUI
+ Return: ~
+ (`boolean`) true if the window is valid, false otherwise
+
+nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
+ Sets the current buffer in a window, without side effects
Attributes: ~
- |RPC| only
- Since: 0.9.0
+ not allowed when |textlock| is active
+ Since: 0.3.2
Parameters: ~
- • {gained} (`boolean`)
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {buffer} (`integer`) Buffer id
-nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
+nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
+ Sets the (1,0)-indexed cursor position in the window. |api-indexing| This
+ scrolls the window even if it is not the current one.
Attributes: ~
- |RPC| only
Since: 0.1.0
Parameters: ~
- • {name} (`string`)
- • {value} (`any`)
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {pos} (`[integer, integer]`) (row, col) tuple representing the new
+ position
-nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()*
- Tells Nvim when a terminal event has occurred
+nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
+ Sets the window height.
- 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: ~
+ Since: 0.1.0
+
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {height} (`integer`) Height as a count of rows
+
+nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()*
+ Set highlight namespace for a window. This will use highlights defined
+ with |nvim_set_hl()| for this namespace, but fall back to global
+ highlights (ns=0) when missing.
+
+ This takes precedence over the 'winhighlight' option.
Attributes: ~
- |RPC| only
- Since: 0.10.0
+ Since: 0.8.0
Parameters: ~
- • {event} (`string`) Event name
- • {value} (`any`) Event payload
+ • {window} (`integer`)
+ • {ns_id} (`integer`) the namespace to use
-nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
+nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
+ Sets a window-scoped (w:) variable
Attributes: ~
- |RPC| only
Since: 0.1.0
Parameters: ~
- • {width} (`integer`)
- • {height} (`integer`)
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
- *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.
+nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
+ Sets the window width. This will only succeed if the screen is split
+ vertically.
- On invalid grid handle, fails with error.
+ Attributes: ~
+ Since: 0.1.0
+
+ Parameters: ~
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {width} (`integer`) Width as a count of columns
+
+nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
+ Computes the number of screen lines occupied by a range of text in a given
+ window. Works for off-screen text and takes folds into account.
+
+ Diff filler or virtual lines above a line are counted as a part of that
+ line, unless the line is on "start_row" and "start_vcol" is specified.
+
+ Diff filler or virtual lines below the last buffer line are counted in the
+ result when "end_row" is omitted.
+
+ Line indexing is similar to |nvim_buf_get_text()|.
Attributes: ~
- |RPC| only
- Since: 0.4.0
+ Since: 0.10.0
Parameters: ~
- • {grid} (`integer`) The handle of the grid to be changed.
- • {width} (`integer`) The new requested width.
- • {height} (`integer`) The new requested height.
+ • {window} (`integer`) |window-ID|, or 0 for current window.
+ • {opts} (`vim.api.keyset.win_text_height`) Optional parameters:
+ • start_row: Starting line index, 0-based inclusive. When
+ omitted start at the very top.
+ • end_row: Ending line index, 0-based inclusive. When
+ omitted end at the very bottom.
+ • start_vcol: Starting virtual column index on "start_row",
+ 0-based inclusive, rounded down to full screen lines. When
+ omitted include the whole line.
+ • end_vcol: Ending virtual column index on "end_row",
+ 0-based exclusive, rounded up to full screen lines. When 0
+ only include diff filler and virtual lines above
+ "end_row". When omitted include the whole line.
+ • max_height: Don't add the height of lines below the row
+ for which this height is reached. Useful to e.g. limit the
+ height to the window height, avoiding unnecessary work. Or
+ to find out how many buffer lines beyond "start_row" take
+ up a certain number of logical lines (returned in
+ "end_row" and "end_vcol").
+
+ Return: ~
+ (`vim.api.keyset.win_text_height_ret`) Dict containing text height
+ information, with these keys:
+ • all: The total number of screen lines occupied by the range.
+ • fill: The number of diff filler or virtual lines among them.
+ • end_row: The row on which the returned height is reached (first row
+ of a closed fold).
+ • end_vcol: Ending virtual column in "end_row" where "max_height" or
+ the returned height is reached. 0 if "end_row" is a closed fold.
+
+ See also: ~
+ • |virtcol()| for text width.
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
@@ -1263,394 +1263,55 @@ tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()*
==============================================================================
-Lua module: vim.lsp.client *lsp-client*
+Lua module: vim.lsp.buf *lsp-buf*
-*vim.lsp.Client*
+The `vim.lsp.buf_…` functions perform operations for LSP clients attached to
+the current buffer.
+
+
+*vim.lsp.ListOpts*
Fields: ~
- • {attached_buffers} (`table<integer,true>`)
- • {capabilities} (`lsp.ClientCapabilities`) Capabilities
- provided by the client (editor or tool), at
- startup.
- • {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`)
- Client commands. See |vim.lsp.ClientConfig|.
- • {config} (`vim.lsp.ClientConfig`) Copy of the config
- passed to |vim.lsp.start()|. See
- |vim.lsp.ClientConfig|.
- • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities
- provided at runtime (after startup).
- • {flags} (`table`) A table with flags for the client.
- The current (experimental) flags are:
- • {allow_incremental_sync}? (`boolean`,
- default: `true`) Allow using incremental
- sync for buffer edits
- • {debounce_text_changes} (`integer`, default:
- `150`) Debounce `didChange` notifications to
- the server by the given number in
- milliseconds. No debounce occurs if `nil`.
- • {exit_timeout} (`integer|false`, default:
- `false`) Milliseconds to wait for server to
- exit cleanly after sending the "shutdown"
- request before sending kill -15. If set to
- false, nvim exits immediately after sending
- the "shutdown" request to the server.
- • {get_language_id} (`fun(bufnr: integer, filetype: string): string`)
- See |vim.lsp.ClientConfig|.
- • {handlers} (`table<string,lsp.Handler>`) See
- |vim.lsp.ClientConfig|.
- • {id} (`integer`) The id allocated to the client.
- • {initialized} (`true?`)
- • {name} (`string`) See |vim.lsp.ClientConfig|.
- • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) See
- |vim.lsp.ClientConfig|.
- • {progress} (`vim.lsp.Client.Progress`) A ring buffer
- (|vim.ringbuf()|) containing progress messages
- sent by the server. See
- |vim.lsp.Client.Progress|.
- • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
- The current pending requests in flight to the
- server. Entries are key-value pairs with the
- key being the request id while the value is a
- table with `type`, `bufnr`, and `method`
- key-value pairs. `type` is either "pending"
- for an active request, or "cancel" for a
- cancel request. It will be "complete"
- ephemerally while executing |LspRequest|
- autocmds when replies are received from the
- server.
- • {root_dir} (`string?`) See |vim.lsp.ClientConfig|.
- • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
- object, for low level interaction with the
- client. See |vim.lsp.rpc.start()|.
- • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
- server sent on `initialize` describing the
- server's capabilities.
- • {server_info} (`lsp.ServerInfo?`) Response from the server
- sent on `initialize` describing server
- information (e.g. version).
- • {settings} (`lsp.LSPObject`) See |vim.lsp.ClientConfig|.
- • {workspace_folders} (`lsp.WorkspaceFolder[]?`) See
- |vim.lsp.ClientConfig|.
- • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`)
- See |Client:request()|.
- • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`)
- See |Client:request_sync()|.
- • {notify} (`fun(self: vim.lsp.Client, method: string, params: table?): boolean`)
- See |Client:notify()|.
- • {cancel_request} (`fun(self: vim.lsp.Client, id: integer): boolean`)
- See |Client:cancel_request()|.
- • {stop} (`fun(self: vim.lsp.Client, force: boolean?)`)
- See |Client:stop()|.
- • {is_stopped} (`fun(self: vim.lsp.Client): boolean`) See
- |Client:is_stopped()|.
- • {exec_cmd} (`fun(self: vim.lsp.Client, command: lsp.Command, context: {bufnr?: integer}?, handler: lsp.Handler?)`)
- See |Client:exec_cmd()|.
- • {on_attach} (`fun(self: vim.lsp.Client, bufnr: integer)`)
- See |Client:on_attach()|.
- • {supports_method} (`fun(self: vim.lsp.Client, method: string, bufnr: integer?)`)
- See |Client:supports_method()|.
+ • {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.Client.Progress*
- Extends: |vim.Ringbuf|
+ 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: ~
- • {pending} (`table<lsp.ProgressToken,lsp.LSPAny>`)
+ • {reuse_win}? (`boolean`) Jump to existing window if buffer is already
+ open.
-*vim.lsp.ClientConfig*
+*vim.lsp.LocationOpts.OnList*
Fields: ~
- • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
- Callback invoked before the LSP "initialize"
- phase, where `params` contains the parameters
- being sent to the server and `config` is the
- config that was passed to |vim.lsp.start()|.
- You can use this to modify parameters before
- they are sent.
- • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
- default capabilities defined by
- |vim.lsp.protocol.make_client_capabilities()|,
- passed to the language server on
- initialization. Hint: use
- make_client_capabilities() and modify its
- result.
- • Note: To send an empty dictionary use
- |vim.empty_dict()|, else it will be encoded
- as an array.
- • {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers, config: vim.lsp.ClientConfig): vim.lsp.rpc.PublicClient`)
- Command `string[]` that launches the language
- server (treated as in |jobstart()|, must be
- absolute or on `$PATH`, shell constructs like
- "~" are not expanded), or function that creates
- an RPC client. Function receives a
- `dispatchers` table and the resolved `config`,
- and must return a table with member functions
- `request`, `notify`, `is_closing` and
- `terminate`. See |vim.lsp.rpc.request()|,
- |vim.lsp.rpc.notify()|. For TCP there is a
- builtin RPC client factory:
- |vim.lsp.rpc.connect()|
- • {cmd_cwd}? (`string`, default: cwd) Directory to launch
- the `cmd` process. Not related to `root_dir`.
- • {cmd_env}? (`table`) Environment variables passed to the
- LSP process on spawn. Non-string values are
- coerced to string. Example: >lua
- { PORT = 8080; HOST = '0.0.0.0'; }
-<
- • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`)
- Map of client-defined commands overriding the
- global |vim.lsp.commands|.
- • {detached}? (`boolean`, default: `true`) Daemonize the
- server process so that it runs in a separate
- process group from Nvim. Nvim will shutdown the
- process on exit, but if Nvim fails to exit
- cleanly this could leave behind orphaned server
- processes.
- • {flags}? (`table`) A table with flags for the client.
- The current (experimental) flags are:
- • {allow_incremental_sync}? (`boolean`,
- default: `true`) Allow using incremental sync
- for buffer edits
- • {debounce_text_changes} (`integer`, default:
- `150`) Debounce `didChange` notifications to
- the server by the given number in
- milliseconds. No debounce occurs if `nil`.
- • {exit_timeout} (`integer|false`, default:
- `false`) Milliseconds to wait for server to
- exit cleanly after sending the "shutdown"
- request before sending kill -15. If set to
- false, nvim exits immediately after sending
- the "shutdown" request to the server.
- • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
- Language ID as string. Defaults to the buffer
- filetype.
- • {handlers}? (`table<string,function>`) Map of LSP method
- names to |lsp-handler|s.
- • {init_options}? (`lsp.LSPObject`) Values to pass in the
- initialization request as
- `initializationOptions`. See `initialize` in
- the LSP spec.
- • {name}? (`string`, default: client-id) Name in logs and
- user messages.
- • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position
- encoding" in LSP spec. The encoding that the
- LSP server expects, used for communication. Not
- validated. Can be modified in `on_init` before
- text is sent to the server.
- • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
- Callback invoked when client attaches to a
- buffer.
- • {on_error}? (`fun(code: integer, err: string)`) Callback
- invoked when the client operation throws an
- error. `code` is a number describing the error.
- Other arguments may be passed depending on the
- error kind. See `vim.lsp.rpc.client_errors` for
- possible errors. Use
- `vim.lsp.rpc.client_errors[code]` to get
- human-friendly name.
- • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
- Callback invoked on client exit.
- • code: exit code of the process
- • signal: number describing the signal used to
- terminate (if any)
- • client_id: client handle
- • {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>`)
- Callback invoked after LSP "initialize", where
- `result` is a table of `capabilities` and
- anything else the server may send. For example,
- clangd sends `init_result.offsetEncoding` if
- `capabilities.offsetEncoding` was sent to it.
- You can only modify the
- `client.offset_encoding` here before any
- notifications are sent.
- • {root_dir}? (`string`) Directory where the LSP server will
- base its workspaceFolders, rootUri, and
- rootPath on initialization.
- • {settings}? (`lsp.LSPObject`) Map of language
- server-specific settings, decided by the
- client. Sent to the LS if requested via
- `workspace/configuration`. Keys are
- case-sensitive.
- • {trace}? (`'off'|'messages'|'verbose'`, default: "off")
- Passed directly to the language server in the
- initialize request. Invalid/empty values will
- • {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
- folders passed to the language server. For
- backwards compatibility rootUri and rootPath
- are derived from the first workspace folder in
- this list. Can be `null` if the client supports
- workspace folders but none are configured. See
- `workspaceFolders` in LSP spec.
- • {workspace_required}? (`boolean`, default: `false`) Server requires a
- workspace (no "single file" support). Note:
- Without a workspace, cross-file features
- (navigation, hover) may or may not work
- depending on the language server, even if the
- server doesn't require a workspace.
+ • {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|
-Client:cancel_request({id}) *Client:cancel_request()*
- Cancels a request with a given request id.
- Parameters: ~
- • {id} (`integer`) id of request to cancel
-
- Return: ~
- (`boolean`) status indicating if the notification was successful.
-
- See also: ~
- • |Client:notify()|
-
-Client:exec_cmd({command}, {context}, {handler}) *Client:exec_cmd()*
- Execute a lsp command, either via client command function (if available)
- or via workspace/executeCommand (if supported by the server)
-
- Parameters: ~
- • {command} (`lsp.Command`)
- • {context} (`{bufnr?: integer}?`)
- • {handler} (`lsp.Handler?`) only called if a server command
-
-Client:is_stopped() *Client:is_stopped()*
- Checks whether a client is stopped.
-
- Return: ~
- (`boolean`) true if client is stopped or in the process of being
- stopped; false otherwise
-
-Client:notify({method}, {params}) *Client:notify()*
- Sends a notification to an LSP server.
-
- Parameters: ~
- • {method} (`string`) LSP method name.
- • {params} (`table?`) LSP request params.
-
- Return: ~
- (`boolean`) status indicating if the notification was successful. If
- it is false, then the client has shutdown.
-
-Client:on_attach({bufnr}) *Client:on_attach()*
- Runs the on_attach function from the client's config if it was defined.
- Useful for buffer-local setup.
-
- Parameters: ~
- • {bufnr} (`integer`) Buffer number
-
- *Client:request()*
-Client:request({method}, {params}, {handler}, {bufnr})
- Sends a request to the server.
-
- This is a thin wrapper around {client.rpc.request} with some additional
- checks for capabilities and handler availability.
-
- Parameters: ~
- • {method} (`string`) LSP method name.
- • {params} (`table?`) LSP request params.
- • {handler} (`lsp.Handler?`) Response |lsp-handler| for this method.
- • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for current.
-
- Return (multiple): ~
- (`boolean`) status indicates whether the request was successful. If it
- is `false`, then it will always be `false` (the client has shutdown).
- (`integer?`) request_id Can be used with |Client:cancel_request()|.
- `nil` is request failed.
-
- See also: ~
- • |vim.lsp.buf_request_all()|
-
- *Client:request_sync()*
-Client:request_sync({method}, {params}, {timeout_ms}, {bufnr})
- Sends a request to the server and synchronously waits for the response.
-
- This is a wrapper around |Client:request()|
-
- Parameters: ~
- • {method} (`string`) LSP method name.
- • {params} (`table`) LSP request params.
- • {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a
- result. Defaults to 1000
- • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for
- current.
-
- Return (multiple): ~
- (`{err: lsp.ResponseError?, result:any}?`) `result` and `err` from the
- |lsp-handler|. `nil` is the request was unsuccessful
- (`string?`) err On timeout, cancel or error, where `err` is a string
- describing the failure reason.
-
- See also: ~
- • |vim.lsp.buf_request_sync()|
-
-Client:stop({force}) *Client:stop()*
- Stops a client, optionally with force.
-
- By default, it will just request the server to shutdown without force. If
- you request to stop a client which has previously been requested to
- shutdown, it will automatically escalate and force shutdown.
-
- Parameters: ~
- • {force} (`boolean?`)
-
-Client:supports_method({method}, {bufnr}) *Client:supports_method()*
- Checks if a client supports a given method. Always returns true for
- unknown off-spec methods.
-
- Note: Some language server capabilities can be file specific.
-
- Parameters: ~
- • {method} (`string`)
- • {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`)
+ Fields: ~
+ • {silent}? (`boolean`)
*vim.lsp.buf.signature_help.Opts*
Extends: |vim.lsp.util.open_floating_preview.Opts|
@@ -1832,132 +1493,420 @@ 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?`)
+ 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 `<C-s>`,
+ which can be remapped via `<Plug>(nvim.lsp.ctrl-s)`
+
+ Example: >lua
+ vim.keymap.set('n', '<C-b>', '<Plug>(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*
+
+*vim.lsp.Client*
+
+ Fields: ~
+ • {attached_buffers} (`table<integer,true>`)
+ • {capabilities} (`lsp.ClientCapabilities`) Capabilities
+ provided by the client (editor or tool), at
+ startup.
+ • {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`)
+ Client commands. See |vim.lsp.ClientConfig|.
+ • {config} (`vim.lsp.ClientConfig`) Copy of the config
+ passed to |vim.lsp.start()|. See
+ |vim.lsp.ClientConfig|.
+ • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities
+ provided at runtime (after startup).
+ • {flags} (`table`) A table with flags for the client.
+ The current (experimental) flags are:
+ • {allow_incremental_sync}? (`boolean`,
+ default: `true`) Allow using incremental
+ sync for buffer edits
+ • {debounce_text_changes} (`integer`, default:
+ `150`) Debounce `didChange` notifications to
+ the server by the given number in
+ milliseconds. No debounce occurs if `nil`.
+ • {exit_timeout} (`integer|false`, default:
+ `false`) Milliseconds to wait for server to
+ exit cleanly after sending the "shutdown"
+ request before sending kill -15. If set to
+ false, nvim exits immediately after sending
+ the "shutdown" request to the server.
+ • {get_language_id} (`fun(bufnr: integer, filetype: string): string`)
+ See |vim.lsp.ClientConfig|.
+ • {handlers} (`table<string,lsp.Handler>`) See
+ |vim.lsp.ClientConfig|.
+ • {id} (`integer`) The id allocated to the client.
+ • {initialized} (`true?`)
+ • {name} (`string`) See |vim.lsp.ClientConfig|.
+ • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) See
+ |vim.lsp.ClientConfig|.
+ • {progress} (`vim.lsp.Client.Progress`) A ring buffer
+ (|vim.ringbuf()|) containing progress messages
+ sent by the server. See
+ |vim.lsp.Client.Progress|.
+ • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
+ The current pending requests in flight to the
+ server. Entries are key-value pairs with the
+ key being the request id while the value is a
+ table with `type`, `bufnr`, and `method`
+ key-value pairs. `type` is either "pending"
+ for an active request, or "cancel" for a
+ cancel request. It will be "complete"
+ ephemerally while executing |LspRequest|
+ autocmds when replies are received from the
+ server.
+ • {root_dir} (`string?`) See |vim.lsp.ClientConfig|.
+ • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
+ object, for low level interaction with the
+ client. See |vim.lsp.rpc.start()|.
+ • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
+ server sent on `initialize` describing the
+ server's capabilities.
+ • {server_info} (`lsp.ServerInfo?`) Response from the server
+ sent on `initialize` describing server
+ information (e.g. version).
+ • {settings} (`lsp.LSPObject`) See |vim.lsp.ClientConfig|.
+ • {workspace_folders} (`lsp.WorkspaceFolder[]?`) See
+ |vim.lsp.ClientConfig|.
+ • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`)
+ See |Client:request()|.
+ • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`)
+ See |Client:request_sync()|.
+ • {notify} (`fun(self: vim.lsp.Client, method: string, params: table?): boolean`)
+ See |Client:notify()|.
+ • {cancel_request} (`fun(self: vim.lsp.Client, id: integer): boolean`)
+ See |Client:cancel_request()|.
+ • {stop} (`fun(self: vim.lsp.Client, force: boolean?)`)
+ See |Client:stop()|.
+ • {is_stopped} (`fun(self: vim.lsp.Client): boolean`) See
+ |Client:is_stopped()|.
+ • {exec_cmd} (`fun(self: vim.lsp.Client, command: lsp.Command, context: {bufnr?: integer}?, handler: lsp.Handler?)`)
+ See |Client:exec_cmd()|.
+ • {on_attach} (`fun(self: vim.lsp.Client, bufnr: integer)`)
+ See |Client:on_attach()|.
+ • {supports_method} (`fun(self: vim.lsp.Client, method: string, bufnr: integer?)`)
+ See |Client:supports_method()|.
+
+*vim.lsp.Client.Progress*
+ Extends: |vim.Ringbuf|
+
+
+ Fields: ~
+ • {pending} (`table<lsp.ProgressToken,lsp.LSPAny>`)
+
+*vim.lsp.ClientConfig*
+
+ Fields: ~
+ • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
+ Callback invoked before the LSP "initialize"
+ phase, where `params` contains the parameters
+ being sent to the server and `config` is the
+ config that was passed to |vim.lsp.start()|.
+ You can use this to modify parameters before
+ they are sent.
+ • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
+ default capabilities defined by
+ |vim.lsp.protocol.make_client_capabilities()|,
+ passed to the language server on
+ initialization. Hint: use
+ make_client_capabilities() and modify its
+ result.
+ • Note: To send an empty dictionary use
+ |vim.empty_dict()|, else it will be encoded
+ as an array.
+ • {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers, config: vim.lsp.ClientConfig): vim.lsp.rpc.PublicClient`)
+ Command `string[]` that launches the language
+ server (treated as in |jobstart()|, must be
+ absolute or on `$PATH`, shell constructs like
+ "~" are not expanded), or function that creates
+ an RPC client. Function receives a
+ `dispatchers` table and the resolved `config`,
+ and must return a table with member functions
+ `request`, `notify`, `is_closing` and
+ `terminate`. See |vim.lsp.rpc.request()|,
+ |vim.lsp.rpc.notify()|. For TCP there is a
+ builtin RPC client factory:
+ |vim.lsp.rpc.connect()|
+ • {cmd_cwd}? (`string`, default: cwd) Directory to launch
+ the `cmd` process. Not related to `root_dir`.
+ • {cmd_env}? (`table`) Environment variables passed to the
+ LSP process on spawn. Non-string values are
+ coerced to string. Example: >lua
+ { PORT = 8080; HOST = '0.0.0.0'; }
+<
+ • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`)
+ Map of client-defined commands overriding the
+ global |vim.lsp.commands|.
+ • {detached}? (`boolean`, default: `true`) Daemonize the
+ server process so that it runs in a separate
+ process group from Nvim. Nvim will shutdown the
+ process on exit, but if Nvim fails to exit
+ cleanly this could leave behind orphaned server
+ processes.
+ • {flags}? (`table`) A table with flags for the client.
+ The current (experimental) flags are:
+ • {allow_incremental_sync}? (`boolean`,
+ default: `true`) Allow using incremental sync
+ for buffer edits
+ • {debounce_text_changes} (`integer`, default:
+ `150`) Debounce `didChange` notifications to
+ the server by the given number in
+ milliseconds. No debounce occurs if `nil`.
+ • {exit_timeout} (`integer|false`, default:
+ `false`) Milliseconds to wait for server to
+ exit cleanly after sending the "shutdown"
+ request before sending kill -15. If set to
+ false, nvim exits immediately after sending
+ the "shutdown" request to the server.
+ • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
+ Language ID as string. Defaults to the buffer
+ filetype.
+ • {handlers}? (`table<string,function>`) Map of LSP method
+ names to |lsp-handler|s.
+ • {init_options}? (`lsp.LSPObject`) Values to pass in the
+ initialization request as
+ `initializationOptions`. See `initialize` in
+ the LSP spec.
+ • {name}? (`string`, default: client-id) Name in logs and
+ user messages.
+ • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position
+ encoding" in LSP spec. The encoding that the
+ LSP server expects, used for communication. Not
+ validated. Can be modified in `on_init` before
+ text is sent to the server.
+ • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
+ Callback invoked when client attaches to a
+ buffer.
+ • {on_error}? (`fun(code: integer, err: string)`) Callback
+ invoked when the client operation throws an
+ error. `code` is a number describing the error.
+ Other arguments may be passed depending on the
+ error kind. See `vim.lsp.rpc.client_errors` for
+ possible errors. Use
+ `vim.lsp.rpc.client_errors[code]` to get
+ human-friendly name.
+ • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
+ Callback invoked on client exit.
+ • code: exit code of the process
+ • signal: number describing the signal used to
+ terminate (if any)
+ • client_id: client handle
+ • {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>`)
+ Callback invoked after LSP "initialize", where
+ `result` is a table of `capabilities` and
+ anything else the server may send. For example,
+ clangd sends `init_result.offsetEncoding` if
+ `capabilities.offsetEncoding` was sent to it.
+ You can only modify the
+ `client.offset_encoding` here before any
+ notifications are sent.
+ • {root_dir}? (`string`) Directory where the LSP server will
+ base its workspaceFolders, rootUri, and
+ rootPath on initialization.
+ • {settings}? (`lsp.LSPObject`) Map of language
+ server-specific settings, decided by the
+ client. Sent to the LS if requested via
+ `workspace/configuration`. Keys are
+ case-sensitive.
+ • {trace}? (`'off'|'messages'|'verbose'`, default: "off")
+ Passed directly to the language server in the
+ initialize request. Invalid/empty values will
+ • {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
+ folders passed to the language server. For
+ backwards compatibility rootUri and rootPath
+ are derived from the first workspace folder in
+ this list. Can be `null` if the client supports
+ workspace folders but none are configured. See
+ `workspaceFolders` in LSP spec.
+ • {workspace_required}? (`boolean`, default: `false`) Server requires a
+ workspace (no "single file" support). Note:
+ Without a workspace, cross-file features
+ (navigation, hover) may or may not work
+ depending on the language server, even if the
+ server doesn't require a workspace.
+
-rename({new_name}, {opts}) *vim.lsp.buf.rename()*
- Renames all references to the symbol under the cursor.
+Client:cancel_request({id}) *Client:cancel_request()*
+ Cancels a request with a given request id.
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.
+ • {id} (`integer`) id of request to cancel
- Parameters: ~
- • {direction} (`integer`)
+ Return: ~
+ (`boolean`) status indicating if the notification was successful.
-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 `<C-s>`,
- which can be remapped via `<Plug>(nvim.lsp.ctrl-s)`
+ See also: ~
+ • |Client:notify()|
- Example: >lua
- vim.keymap.set('n', '<C-b>', '<Plug>(nvim.lsp.ctrl-s)')
-<
+Client:exec_cmd({command}, {context}, {handler}) *Client:exec_cmd()*
+ Execute a lsp command, either via client command function (if available)
+ or via workspace/executeCommand (if supported by the server)
Parameters: ~
- • {config} (`vim.lsp.buf.signature_help.Opts?`) See
- |vim.lsp.buf.signature_help.Opts|.
+ • {command} (`lsp.Command`)
+ • {context} (`{bufnr?: integer}?`)
+ • {handler} (`lsp.Handler?`) only called if a server command
-type_definition({opts}) *vim.lsp.buf.type_definition()*
- Jumps to the definition of the type of the symbol under the cursor.
+Client:is_stopped() *Client:is_stopped()*
+ Checks whether a client is stopped.
- Parameters: ~
- • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|.
+ Return: ~
+ (`boolean`) true if client is stopped or in the process of being
+ stopped; false otherwise
-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()|.
+Client:notify({method}, {params}) *Client:notify()*
+ Sends a notification to an LSP server.
Parameters: ~
- • {kind} (`"subtypes"|"supertypes"`)
+ • {method} (`string`) LSP method name.
+ • {params} (`table?`) LSP request params.
-workspace_diagnostics({opts}) *vim.lsp.buf.workspace_diagnostics()*
- Request workspace-wide diagnostics.
+ Return: ~
+ (`boolean`) status indicating if the notification was successful. If
+ it is false, then the client has shutdown.
- 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.
+Client:on_attach({bufnr}) *Client:on_attach()*
+ Runs the on_attach function from the client's config if it was defined.
+ Useful for buffer-local setup.
- See also: ~
- • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_dagnostics
+ Parameters: ~
+ • {bufnr} (`integer`) Buffer number
-workspace_symbol({query}, {opts}) *vim.lsp.buf.workspace_symbol()*
- Lists all symbols in the current workspace in the quickfix window.
+ *Client:request()*
+Client:request({method}, {params}, {handler}, {bufnr})
+ Sends a request to the server.
- 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.
+ This is a thin wrapper around {client.rpc.request} with some additional
+ checks for capabilities and handler availability.
Parameters: ~
- • {query} (`string?`) optional
- • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|.
-
+ • {method} (`string`) LSP method name.
+ • {params} (`table?`) LSP request params.
+ • {handler} (`lsp.Handler?`) Response |lsp-handler| for this method.
+ • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for current.
-==============================================================================
-Lua module: vim.lsp.diagnostic *lsp-diagnostic*
+ Return (multiple): ~
+ (`boolean`) status indicates whether the request was successful. If it
+ is `false`, then it will always be `false` (the client has shutdown).
+ (`integer?`) request_id Can be used with |Client:cancel_request()|.
+ `nil` is request failed.
-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.
+ See also: ~
+ • |vim.lsp.buf_request_all()|
+ *Client:request_sync()*
+Client:request_sync({method}, {params}, {timeout_ms}, {bufnr})
+ Sends a request to the server and synchronously waits for the response.
-from({diagnostics}) *vim.lsp.diagnostic.from()*
- Converts the input `vim.Diagnostic`s to LSP diagnostics.
+ This is a wrapper around |Client:request()|
Parameters: ~
- • {diagnostics} (`vim.Diagnostic[]`)
-
- Return: ~
- (`lsp.Diagnostic[]`)
+ • {method} (`string`) LSP method name.
+ • {params} (`table`) LSP request params.
+ • {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a
+ result. Defaults to 1000
+ • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for
+ current.
- *vim.lsp.diagnostic.get_namespace()*
-get_namespace({client_id}, {is_pull})
- Get the diagnostic namespace associated with an LSP client
- |vim.diagnostic| for diagnostics
+ Return (multiple): ~
+ (`{err: lsp.ResponseError?, result:any}?`) `result` and `err` from the
+ |lsp-handler|. `nil` is the request was unsuccessful
+ (`string?`) err On timeout, cancel or error, where `err` is a string
+ describing the failure reason.
- 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
+ See also: ~
+ • |vim.lsp.buf_request_sync()|
- *vim.lsp.diagnostic.on_diagnostic()*
-on_diagnostic({error}, {result}, {ctx})
- |lsp-handler| for the method "textDocument/diagnostic"
+Client:stop({force}) *Client:stop()*
+ Stops a client, optionally with force.
- See |vim.diagnostic.config()| for configuration options.
+ By default, it will just request the server to shutdown without force. If
+ you request to stop a client which has previously been requested to
+ shutdown, it will automatically escalate and force shutdown.
Parameters: ~
- • {error} (`lsp.ResponseError?`)
- • {result} (`lsp.DocumentDiagnosticReport`)
- • {ctx} (`lsp.HandlerContext`)
+ • {force} (`boolean?`)
- *vim.lsp.diagnostic.on_publish_diagnostics()*
-on_publish_diagnostics({_}, {params}, {ctx})
- |lsp-handler| for the method "textDocument/publishDiagnostics"
+Client:supports_method({method}, {bufnr}) *Client:supports_method()*
+ Checks if a client supports a given method. Always returns true for
+ unknown off-spec methods.
- See |vim.diagnostic.config()| for configuration options.
+ Note: Some language server capabilities can be file specific.
Parameters: ~
- • {params} (`lsp.PublishDiagnosticsParams`)
- • {ctx} (`lsp.HandlerContext`)
+ • {method} (`string`)
+ • {bufnr} (`integer?`)
==============================================================================
@@ -2079,37 +2028,138 @@ enable({enable}, {client_id}, {bufnr}, {opts})
`triggerCharacters` field. You can override it on LspAttach, see
|lsp-autocompletion|.
- Parameters: ~
- • {enable} (`boolean`) True to enable, false to disable
- • {client_id} (`integer`) Client ID
- • {bufnr} (`integer`) Buffer handle, or 0 for the current buffer
- • {opts} (`table?`) A table with the following fields:
- • {autotrigger}? (`boolean`) (default: false) When true,
- completion triggers automatically based on the server's
- `triggerCharacters`.
- • {convert}? (`fun(item: lsp.CompletionItem): table`)
- Transforms an LSP CompletionItem to |complete-items|.
+ Parameters: ~
+ • {enable} (`boolean`) True to enable, false to disable
+ • {client_id} (`integer`) Client ID
+ • {bufnr} (`integer`) Buffer handle, or 0 for the current buffer
+ • {opts} (`table?`) A table with the following fields:
+ • {autotrigger}? (`boolean`) (default: false) When true,
+ completion triggers automatically based on the server's
+ `triggerCharacters`.
+ • {convert}? (`fun(item: lsp.CompletionItem): table`)
+ Transforms an LSP CompletionItem to |complete-items|.
+
+get({opts}) *vim.lsp.completion.get()*
+ Triggers LSP completion once in the current buffer, if LSP completion is
+ enabled (see |lsp-attach| |lsp-completion|).
+
+ Used by the default LSP |omnicompletion| provider |vim.lsp.omnifunc()|,
+ thus |i_CTRL-X_CTRL-O| invokes this in LSP-enabled buffers. Use CTRL-Y to
+ select an item from the completion menu. |complete_CTRL-Y|
+
+ To invoke manually with CTRL-space, use this mapping: >lua
+ -- Use CTRL-space to trigger LSP completion.
+ -- Use CTRL-Y to select an item. |complete_CTRL-Y|
+ vim.keymap.set('i', '<c-space>', function()
+ vim.lsp.completion.get()
+ end)
+<
+
+ Parameters: ~
+ • {opts} (`table?`) A table with the following fields:
+ • {ctx}? (`lsp.CompletionContext`) Completion context.
+ 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.
-get({opts}) *vim.lsp.completion.get()*
- Triggers LSP completion once in the current buffer, if LSP completion is
- enabled (see |lsp-attach| |lsp-completion|).
+enable({enable}, {bufnr}, {opts}) *vim.lsp.document_color.enable()*
+ Enables document highlighting from the given language client in the given
+ buffer.
- Used by the default LSP |omnicompletion| provider |vim.lsp.omnifunc()|,
- thus |i_CTRL-X_CTRL-O| invokes this in LSP-enabled buffers. Use CTRL-Y to
- select an item from the completion menu. |complete_CTRL-Y|
+ 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 invoke manually with CTRL-space, use this mapping: >lua
- -- Use CTRL-space to trigger LSP completion.
- -- Use CTRL-Y to select an item. |complete_CTRL-Y|
- vim.keymap.set('i', '<c-space>', function()
- vim.lsp.completion.get()
- end)
+ To "toggle", pass the inverse of `is_enabled()`: >lua
+ vim.lsp.document_color.enable(not vim.lsp.document_color.is_enabled())
<
Parameters: ~
- • {opts} (`table?`) A table with the following fields:
- • {ctx}? (`lsp.CompletionContext`) Completion context.
- Defaults to a trigger kind of `invoked`.
+ • {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`)
==============================================================================
@@ -2175,7 +2225,207 @@ is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()*
buffer, or nil for all.
Return: ~
- (`boolean`)
+ (`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<string,string>`) Additional
+ environment variables for LSP server process.
+ See |vim.system()|
+
+ Return: ~
+ (`vim.lsp.rpc.PublicClient`) See |vim.lsp.rpc.PublicClient|.
==============================================================================
@@ -2259,88 +2509,6 @@ is_enabled({filter}) *vim.lsp.semantic_tokens.is_enabled()*
==============================================================================
-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*
*vim.lsp.util.open_floating_preview.Opts*
@@ -2716,174 +2884,6 @@ symbols_to_items({symbols}, {bufnr}, {position_encoding})
==============================================================================
-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<string,string>`) 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*
*vim.lsp.protocol.make_client_capabilities()*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -593,189 +593,6 @@ A subset of the `vim.*` stdlib is available in threads, including:
==============================================================================
-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<string,any>?`) Options table with keys:
- • luanil: (table) Table with keys:
- • object: (boolean) When true, converts `null` in JSON
- objects to Lua `nil` instead of |vim.NIL|.
- • array: (boolean) When true, converts `null` in JSON arrays
- to Lua `nil` instead of |vim.NIL|.
-
- 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<string,any>?`) 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*
@@ -1693,219 +1510,56 @@ vim.str_utfindex({s}, {encoding}, {index}, {strict_indexing})
==============================================================================
-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*
+Lua module: vim.inspector *vim.inspector*
- 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()|.
+vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
+ Get all the items at a given buffer position.
+ Can also be pretty-printed with `:Inspect!`. *:Inspect!*
-SystemObj:is_closing() *SystemObj:is_closing()*
- Checks if the process handle is closing or already closed.
+ Attributes: ~
+ Since: 0.9.0
- 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.
+ Parameters: ~
+ • {bufnr} (`integer?`) defaults to the current buffer
+ • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
+ the current cursor
+ • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
+ the current cursor
+ • {filter} (`table?`) Table with key-value pairs to filter the items
+ • {syntax} (`boolean`, default: `true`) Include syntax based
+ highlight groups.
+ • {treesitter} (`boolean`, default: `true`) Include
+ treesitter based highlight groups.
+ • {extmarks} (`boolean|"all"`, default: true) Include
+ extmarks. When `all`, then extmarks without a `hl_group`
+ will also be included.
+ • {semantic_tokens} (`boolean`, default: true) Include
+ semantic token highlights.
Return: ~
- (`boolean`)
+ (`table`) a table with the following key-value pairs. Items are in
+ "traversal order":
+ • treesitter: a list of treesitter captures
+ • syntax: a list of syntax groups
+ • semantic_tokens: a list of semantic tokens
+ • extmarks: a list of extmarks
+ • buffer: the buffer used to get the items
+ • row: the row used to get the items
+ • col: the col used to get the items
-SystemObj:kill({signal}) *SystemObj:kill()*
- Sends a signal to the process.
+vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()*
+ Show all the items at a given buffer position.
- The signal can be specified as an integer or as a string.
+ Can also be shown with `:Inspect`. *:Inspect*
- Example: >lua
- local obj = vim.system({'sleep', '10'})
- obj:kill('TERM') -- sends SIGTERM to the process
+ Example: To bind this function to the vim-scriptease inspired `zS` in
+ Normal mode: >lua
+ vim.keymap.set('n', 'zS', vim.show_pos)
<
- 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<string,string|number>`) 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*
-
-vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
- Get all the items at a given buffer position.
-
- Can also be pretty-printed with `:Inspect!`. *:Inspect!*
-
- Attributes: ~
- Since: 0.9.0
-
- Parameters: ~
- • {bufnr} (`integer?`) defaults to the current buffer
- • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
- the current cursor
- • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
- the current cursor
- • {filter} (`table?`) Table with key-value pairs to filter the items
- • {syntax} (`boolean`, default: `true`) Include syntax based
- highlight groups.
- • {treesitter} (`boolean`, default: `true`) Include
- treesitter based highlight groups.
- • {extmarks} (`boolean|"all"`, default: true) Include
- extmarks. When `all`, then extmarks without a `hl_group`
- will also be included.
- • {semantic_tokens} (`boolean`, default: true) Include
- semantic token highlights.
-
- Return: ~
- (`table`) a table with the following key-value pairs. Items are in
- "traversal order":
- • treesitter: a list of treesitter captures
- • syntax: a list of syntax groups
- • semantic_tokens: a list of semantic tokens
- • extmarks: a list of extmarks
- • buffer: the buffer used to get the items
- • row: the row used to get the items
- • col: the col used to get the items
-
-vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()*
- Show all the items at a given buffer position.
-
- Can also be shown with `:Inspect`. *:Inspect*
-
- Example: To bind this function to the vim-scriptease inspired `zS` in
- Normal mode: >lua
- vim.keymap.set('n', 'zS', vim.show_pos)
-<
-
- Attributes: ~
- Since: 0.9.0
+ Attributes: ~
+ Since: 0.9.0
Parameters: ~
• {bufnr} (`integer?`) defaults to the current buffer
@@ -2517,286 +2171,57 @@ vim.validate({name}, {value}, {validator}, {optional}, {message})
==============================================================================
-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
+Lua module: vim.base64 *vim.base64*
- 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
+ • {str} (`string`) Base64 encoded string
-vim.loader.find({modname}, {opts}) *vim.loader.find()*
- WARNING: This feature is experimental/unstable.
+ Return: ~
+ (`string`) Decoded string
- Finds Lua modules for the given module name.
+vim.base64.encode({str}) *vim.base64.encode()*
+ Encode {str} using Base64.
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`) String to encode
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
+ (`string`) Encoded string
==============================================================================
-Lua module: vim.uri *vim.uri*
-
-vim.uri_decode({str}) *vim.uri_decode()*
- URI-decodes a string containing percent escapes.
+Lua module: vim.filetype *vim.filetype*
- Parameters: ~
- • {str} (`string`) string to decode
+vim.filetype.add({filetypes}) *vim.filetype.add()*
+ Add new filetype mappings.
- Return: ~
- (`string`) decoded string
+ Filetype mappings can be added either by extension or by filename (either
+ the "tail" or the full file path). The full file path is checked first,
+ followed by the file name. If a match is not found using the filename,
+ then the filename is matched against the list of |lua-pattern|s (sorted by
+ priority) until a match is found. Lastly, if pattern matching does not
+ find a filetype, then the file extension is used.
-vim.uri_encode({str}, {rfc}) *vim.uri_encode()*
- URI-encodes a string using percent escapes.
+ The filetype can be either a string (in which case it is used as the
+ filetype directly) or a function. If a function, it takes the full path
+ and buffer number of the file as arguments (along with captures from the
+ matched pattern, if any) and should return a string that will be used as
+ the buffer's filetype. Optionally, the function can return a second
+ function value which, when called, modifies the state of the buffer. This
+ can be used to, for example, set filetype-specific buffer variables. This
+ function will be called by Nvim before setting the buffer's filetype.
- Parameters: ~
- • {str} (`string`) string to encode
- • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`)
+ Filename patterns can specify an optional priority to resolve cases when a
+ file path matches multiple patterns. Higher priorities are matched first.
+ When omitted, the priority defaults to 0. A pattern can contain
+ environment variables of the form "${SOME_VAR}" that will be automatically
+ expanded. If the environment variable is not set, the pattern won't be
+ matched.
- 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*
-
-vim.filetype.add({filetypes}) *vim.filetype.add()*
- Add new filetype mappings.
-
- Filetype mappings can be added either by extension or by filename (either
- the "tail" or the full file path). The full file path is checked first,
- followed by the file name. If a match is not found using the filename,
- then the filename is matched against the list of |lua-pattern|s (sorted by
- priority) until a match is found. Lastly, if pattern matching does not
- find a filetype, then the file extension is used.
-
- The filetype can be either a string (in which case it is used as the
- filetype directly) or a function. If a function, it takes the full path
- and buffer number of the file as arguments (along with captures from the
- matched pattern, if any) and should return a string that will be used as
- the buffer's filetype. Optionally, the function can return a second
- function value which, when called, modifies the state of the buffer. This
- can be used to, for example, set filetype-specific buffer variables. This
- function will be called by Nvim before setting the buffer's filetype.
-
- Filename patterns can specify an optional priority to resolve cases when a
- file path matches multiple patterns. Higher priorities are matched first.
- When omitted, the priority defaults to 0. A pattern can contain
- environment variables of the form "${SOME_VAR}" that will be automatically
- expanded. If the environment variable is not set, the pattern won't be
- matched.
-
- See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
+ See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
Example: >lua
vim.filetype.add({
@@ -2937,97 +2362,38 @@ vim.filetype.match({args}) *vim.filetype.match()*
==============================================================================
-Lua module: vim.keymap *vim.keymap*
+Lua module: vim.fs *vim.fs*
-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'}, '<leader>w', { buffer = 5 })
+ *vim.fs.exists()*
+Use |uv.fs_stat()| to check a file's type, and whether it exists.
+
+Example: >lua
+ if vim.uv.fs_stat(file) then
+ vim.print('file exists')
+ end
<
+
+vim.fs.abspath({path}) *vim.fs.abspath()*
+ Convert path to an absolute path. A tilde (~) character at the beginning
+ of the path is expanded to the user's home directory. Does not check if
+ the path exists, normalize the path, resolve symlinks or hardlinks
+ (including `.` and `..`), or expand environment variables. If the path is
+ already absolute, it is returned unchanged. Also converts `\` path
+ separators to `/`.
+
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.
+ • {path} (`string`) Path
- See also: ~
- • |vim.keymap.set()|
+ Return: ~
+ (`string`) Absolute path
-vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
- Defines a |mapping| of |keycodes| to a function or keycodes.
+vim.fs.basename({file}) *vim.fs.basename()*
+ Return the basename of the given path
- Examples: >lua
- -- Map "x" to a Lua function:
- vim.keymap.set('n', 'x', function() print('real lua function') end)
- -- Map "<leader>x" to multiple modes for the current buffer:
- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
- -- Map <Tab> to an expression (|:map-<expr>|):
- vim.keymap.set('i', '<Tab>', function()
- return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
- end, { expr = true })
- -- Map "[%%" to a <Plug> mapping:
- vim.keymap.set('n', '[%%', '<Plug>(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*
-
-
- *vim.fs.exists()*
-Use |uv.fs_stat()| to check a file's type, and whether it exists.
-
-Example: >lua
- if vim.uv.fs_stat(file) then
- vim.print('file exists')
- end
-<
-
-
-vim.fs.abspath({path}) *vim.fs.abspath()*
- Convert path to an absolute path. A tilde (~) character at the beginning
- of the path is expanded to the user's home directory. Does not check if
- the path exists, normalize the path, resolve symlinks or hardlinks
- (including `.` and `..`), or expand environment variables. If the path is
- already absolute, it is returned unchanged. Also converts `\` path
- separators to `/`.
-
- Parameters: ~
- • {path} (`string`) Path
-
- Return: ~
- (`string`) Absolute path
-
-vim.fs.basename({file}) *vim.fs.basename()*
- Return the basename of the given path
-
- Attributes: ~
- Since: 0.8.0
+ Attributes: ~
+ Since: 0.8.0
Parameters: ~
• {file} (`string?`) Path
@@ -3350,1516 +2716,2143 @@ 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/
+ Add the following to your `init.vim`: >vim
+ autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300}
+<
- *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/).
+ 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`)
-In addition, its regex-like interface is available as |vim.re|
-(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+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
-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.
+ 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
- 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`)
+==============================================================================
+Lua module: vim.iter *vim.iter*
- Return: ~
- (`any`) ...
+*vim.iter()* is an interface for |iterable|s: it wraps a table or function
+argument into an *Iter* object with methods (such as |Iter:filter()| and
+|Iter:map()|) that transform the underlying source data. These methods can be
+chained to create iterator "pipelines": the output of each pipeline stage is
+input to the next stage. The first stage depends on the type passed to
+`vim.iter()`:
+• Lists or arrays (|lua-list|) yield only the value of each element.
+ • Holes (nil values) are allowed (but discarded).
+ • Use pairs() to treat array/list tables as dicts (preserve holes and
+ non-contiguous integer keys): `vim.iter(pairs(…))`.
+ • Use |Iter:enumerate()| to also pass the index to the next stage.
+ • Or initialize with ipairs(): `vim.iter(ipairs(…))`.
+• Non-list tables (|lua-dict|) yield both the key and value of each element.
+• Function |iterator|s yield all values returned by the underlying function.
+• Tables with a |__call()| metamethod are treated as function iterators.
-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.
+The iterator pipeline terminates when the underlying |iterable| is exhausted
+(for function iterators this means it returned nil).
- Parameters: ~
- • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table`)
+Note: `vim.iter()` scans table input to decide if it is a list or a dict; to
+avoid this cost you can wrap the table with an iterator e.g.
+`vim.iter(ipairs({…}))`, but that precludes the use of |list-iterator|
+operations such as |Iter:rev()|).
- Return: ~
- (`vim.lpeg.Pattern`)
+Examples: >lua
+ local it = vim.iter({ 1, 2, 3, 4, 5 })
+ it:map(function(v)
+ return v * 3
+ end)
+ it:rev()
+ it:skip(2)
+ it:totable()
+ -- { 9, 6, 3 }
-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.
+ -- ipairs() is a function iterator which returns both the index (i) and the value (v)
+ vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
+ if i > 2 then return v end
+ end):totable()
+ -- { 3, 4, 5 }
- 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')
+ local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
+ it:map(function(s) return tonumber(s) end)
+ for i, d in it:enumerate() do
+ print(string.format("Column %d is %d", i, d))
+ end
+ -- Column 1 is 1
+ -- Column 2 is 2
+ -- Column 3 is 3
+ -- Column 4 is 4
+ -- Column 5 is 5
+
+ vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
+ return k == 'z'
+ end)
+ -- true
+
+ local rb = vim.ringbuf(3)
+ rb:push("a")
+ rb:push("b")
+ vim.iter(rb):totable()
+ -- { "a", "b" }
<
- Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
- Return: ~
- (`vim.lpeg.Capture`)
+Iter:all({pred}) *Iter:all()*
+ Returns true if all items in the iterator match the given predicate.
-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: ~
+ • {pred} (`fun(...):boolean`) Predicate function. Takes all values
+ returned from the previous stage in the pipeline as arguments
+ and returns true if the predicate matches.
+
+Iter:any({pred}) *Iter:any()*
+ Returns true if any of the items in the iterator match the given
+ predicate.
Parameters: ~
- • {n} (`integer`)
+ • {pred} (`fun(...):boolean`) Predicate function. Takes all values
+ returned from the previous stage in the pipeline as arguments
+ and returns true if the predicate matches.
- Return: ~
- (`vim.lpeg.Capture`)
+Iter:each({f}) *Iter:each()*
+ Calls a function once for each item in the pipeline, draining the
+ iterator.
-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.
+ For functions with side effects. To modify the values in the iterator, use
+ |Iter:map()|.
Parameters: ~
- • {name} (`any`)
+ • {f} (`fun(...)`) Function to execute for each item in the pipeline.
+ Takes all of the values returned by the previous stage in the
+ pipeline as arguments.
- Return: ~
- (`vim.lpeg.Capture`)
+Iter:enumerate() *Iter:enumerate()*
+ Yields the item index (count) and value for each item of an iterator
+ pipeline.
-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.
+ For list tables, this is more efficient: >lua
+ vim.iter(ipairs(t))
+<
- Parameters: ~
- • {...} (`any`)
+ instead of: >lua
+ vim.iter(t):enumerate()
+<
+
+ Example: >lua
+
+ local it = vim.iter(vim.gsplit('abc', '')):enumerate()
+ it:next()
+ -- 1 'a'
+ it:next()
+ -- 2 'b'
+ it:next()
+ -- 3 'c'
+<
Return: ~
- (`vim.lpeg.Capture`)
+ (`Iter`)
-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.
+Iter:filter({f}) *Iter:filter()*
+ Filters an iterator pipeline.
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)
+ local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
<
Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
- • {func} (`fun(acc, newvalue)`)
+ • {f} (`fun(...):boolean`) Takes all values returned from the previous
+ stage in the pipeline and returns false or nil if the current
+ iterator element should be removed.
Return: ~
- (`vim.lpeg.Capture`)
+ (`Iter`)
-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).
+Iter:find({f}) *Iter:find()*
+ Find the first value in the iterator that satisfies the given predicate.
- Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
- • {name} (`string?`)
+ Advances the iterator. Returns nil and drains the iterator if no value is
+ found.
- Return: ~
- (`vim.lpeg.Capture`)
+ Examples: >lua
-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.
+ local it = vim.iter({ 3, 6, 9, 12 })
+ it:find(12)
+ -- 12
+
+ local it = vim.iter({ 3, 6, 9, 12 })
+ it:find(20)
+ -- nil
+
+ local it = vim.iter({ 3, 6, 9, 12 })
+ it:find(function(v) return v % 4 == 0 end)
+ -- 12
+<
Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
- • {fn} (`fun(s: string, i: integer, ...: any)`) (position:
- boolean|integer, ...: any)
+ • {f} (`any`)
Return: ~
- (`vim.lpeg.Capture`)
+ (`any`)
-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.
+Iter:flatten({depth}) *Iter:flatten()*
+ Flattens a |list-iterator|, un-nesting nested values up to the given
+ {depth}. Errors if it attempts to flatten a dict-like value.
- 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)
+ Examples: >lua
+ vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable()
+ -- { 1, 2, { 3 } }
+
+ vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
+ -- { 1, { a = 2 }, 3 }
+
+ vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()
+ -- error: attempt to flatten a dict-like table
<
+ Parameters: ~
+ • {depth} (`number?`) Depth to which |list-iterator| should be
+ flattened (defaults to 1)
+
Return: ~
- (`vim.lpeg.Capture`)
+ (`Iter`)
-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.
+Iter:fold({init}, {f}) *Iter:fold()*
+ Folds ("reduces") an iterator into a single value. *Iter:reduce()*
- 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!')
+ Examples: >lua
+ -- Create a new table with only even values
+ vim.iter({ a = 1, b = 2, c = 3, d = 4 })
+ :filter(function(k, v) return v % 2 == 0 end)
+ :fold({}, function(acc, k, v)
+ acc[k] = v
+ return acc
+ end) --> { b = 2, d = 4 }
+
+ -- Get the "maximum" item of an iterable.
+ vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
+ :fold({}, function(acc, v)
+ acc.max = math.max(v, acc.max or v)
+ return acc
+ end) --> { max = 42 }
<
Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+ • {init} (`any`) Initial value of the accumulator.
+ • {f} (`fun(acc:A, ...):A`) Accumulation function.
Return: ~
- (`vim.lpeg.Capture`)
+ (`any`)
-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.
+Iter:join({delim}) *Iter:join()*
+ Collect the iterator into a delimited string.
+
+ Each element in the iterator is joined into a string separated by {delim}.
+
+ Consumes the iterator.
Parameters: ~
- • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+ • {delim} (`string`) Delimiter
Return: ~
- (`vim.lpeg.Capture`)
+ (`string`)
-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.
+Iter:last() *Iter:last()*
+ Drains the iterator and returns the last item.
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?`)
+ local it = vim.iter(vim.gsplit('abcdefg', ''))
+ it:last()
+ -- 'g'
+
+ local it = vim.iter({ 3, 6, 9, 12, 15 })
+ it:last()
+ -- 15
+<
Return: ~
- (`vim.lpeg.Locale`)
+ (`any`)
-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.
+ See also: ~
+ • |Iter:rpeek()|
+
+Iter:map({f}) *Iter:map()*
+ Maps the items of an iterator pipeline to the values returned by `f`.
+
+ If the map function returns nil, the value is filtered from the iterator.
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)
+ local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
+ if v % 2 == 0 then
+ return v * 3
+ end
+ end)
+ it:totable()
+ -- { 6, 12 }
<
Parameters: ~
- • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
- • {subject} (`string`)
- • {init} (`integer?`)
- • {...} (`any`)
+ • {f} (`fun(...):...:any`) Mapping function. Takes all values returned
+ from the previous stage in the pipeline as arguments and returns
+ one or more new values, which are used in the next pipeline
+ stage. Nil return values are filtered from the output.
Return: ~
- (`any`) ...
+ (`Iter`)
-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.
+Iter:next() *Iter:next()*
+ Gets the next value from the iterator.
- Parameters: ~
- • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+ Example: >lua
+
+ local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)
+ it:next()
+ -- 1
+ it:next()
+ -- 2
+ it:next()
+ -- 3
+<
Return: ~
- (`vim.lpeg.Pattern`)
+ (`any`)
-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.
+Iter:nth({n}) *Iter:nth()*
+ Gets the nth value of an iterator (and advances to it).
+
+ If `n` is negative, offsets from the end of a |list-iterator|.
Example: >lua
- local pattern = lpeg.R('az') ^ 1 * -1
- assert(pattern:match('hello') == 6)
+ local it = vim.iter({ 3, 6, 9, 12 })
+ it:nth(2)
+ -- 6
+ it:nth(2)
+ -- 12
+
+ local it2 = vim.iter({ 3, 6, 9, 12 })
+ it2:nth(-2)
+ -- 9
+ it2:nth(-2)
+ -- 3
<
Parameters: ~
- • {...} (`string`)
+ • {n} (`number`) Index of the value to return. May be negative if the
+ source is a |list-iterator|.
Return: ~
- (`vim.lpeg.Pattern`)
+ (`any`)
-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.
+Iter:peek() *Iter:peek()*
+ Gets the next value in a |list-iterator| without consuming it.
- Parameters: ~
- • {string} (`string`)
+ Example: >lua
+
+ local it = vim.iter({ 3, 6, 9, 12 })
+ it:peek()
+ -- 3
+ it:peek()
+ -- 3
+ it:next()
+ -- 3
+<
Return: ~
- (`vim.lpeg.Pattern`)
+ (`any`)
-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.
+Iter:pop() *Iter:pop()*
+ "Pops" a value from a |list-iterator| (gets the last value and decrements
+ the tail).
- Parameters: ~
- • {max} (`integer`)
+ Example: >lua
+ local it = vim.iter({1, 2, 3, 4})
+ it:pop()
+ -- 4
+ it:pop()
+ -- 3
+<
-vim.lpeg.type({value}) *vim.lpeg.type()*
- Returns the string `"pattern"` if the given value is a pattern, otherwise
- `nil`.
+ Return: ~
+ (`any`)
- Parameters: ~
- • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+Iter:rev() *Iter:rev()*
+ Reverses a |list-iterator| pipeline.
+
+ Example: >lua
+
+ local it = vim.iter({ 3, 6, 9, 12 }):rev()
+ it:totable()
+ -- { 12, 9, 6, 3 }
+<
Return: ~
- (`"pattern"?`)
+ (`Iter`)
-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.
+Iter:rfind({f}) *Iter:rfind()*
+ Gets the first value satisfying a predicate, from the end of a
+ |list-iterator|.
- Example: >lua
- local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
- assert(b:match('((string))') == 11)
- assert(b:match('(') == nil)
+ Advances the iterator. Returns nil and drains the iterator if no value is
+ found.
+
+ Examples: >lua
+
+ local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
+ it:rfind(1)
+ -- 5 1
+ it:rfind(1)
+ -- 1 1
<
Parameters: ~
- • {v} (`boolean|string|number|function|table|thread|userdata|lightuserdata`)
+ • {f} (`any`)
Return: ~
- (`vim.lpeg.Pattern`)
-
-vim.lpeg.version() *vim.lpeg.version()*
- Returns a string with the running version of LPeg.
+ (`any`)
- Return: ~
- (`string`)
+ See also: ~
+ • |Iter:find()|
+Iter:rpeek() *Iter:rpeek()*
+ Gets the last value of a |list-iterator| without consuming it.
-==============================================================================
-VIM.RE *vim.re*
+ Example: >lua
+ local it = vim.iter({1, 2, 3, 4})
+ it:rpeek()
+ -- 4
+ it:rpeek()
+ -- 4
+ it:pop()
+ -- 4
+<
-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.)
+ Return: ~
+ (`any`)
-See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
-documentation including regex syntax and examples.
+ See also: ~
+ • |Iter:last()|
+Iter:rskip({n}) *Iter:rskip()*
+ Discards `n` values from the end of a |list-iterator| pipeline.
-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.
+ Example: >lua
+ local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2)
+ it:next()
+ -- 1
+ it:pop()
+ -- 3
+<
Parameters: ~
- • {string} (`string`)
- • {defs} (`table?`)
+ • {n} (`number`) Number of values to skip.
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.
+ (`Iter`)
- 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.
+Iter:skip({n}) *Iter:skip()*
+ Skips `n` values of an iterator pipeline, or all values satisfying a
+ predicate of a |list-iterator|.
- Parameters: ~
- • {subject} (`string`)
- • {pattern} (`vim.lpeg.Pattern|string`)
- • {init} (`integer?`)
+ Example: >lua
- Return (multiple): ~
- (`integer?`) the index where the occurrence starts, nil if no match
- (`integer?`) the index where the occurrence ends, nil if no match
+ local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
+ it:next()
+ -- 9
-vim.re.gsub({subject}, {pattern}, {replacement}) *vim.re.gsub()*
- Does a global substitution, replacing all occurrences of {pattern} in the
- given {subject} by {replacement}.
+ local function pred(x) return x < 10 end
+ local it2 = vim.iter({ 3, 6, 9, 12 }):skip(pred)
+ it2:next()
+ -- 12
+<
Parameters: ~
- • {subject} (`string`)
- • {pattern} (`vim.lpeg.Pattern|string`)
- • {replacement} (`string`)
+ • {n} (`integer|fun(...):boolean`) Number of values to skip or a
+ predicate.
Return: ~
- (`string`)
+ (`Iter`)
-vim.re.match({subject}, {pattern}, {init}) *vim.re.match()*
- Matches the given {pattern} against the given {subject}, returning all
- captures.
+Iter:slice({first}, {last}) *Iter:slice()*
+ Sets the start and end of a |list-iterator| pipeline.
+
+ Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
Parameters: ~
- • {subject} (`string`)
- • {pattern} (`vim.lpeg.Pattern|string`)
- • {init} (`integer?`)
+ • {first} (`number`)
+ • {last} (`number`)
Return: ~
- (`integer|vim.lpeg.Capture?`)
-
- See also: ~
- • vim.lpeg.match()
+ (`Iter`)
-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.
+Iter:take({n}) *Iter:take()*
+ Transforms an iterator to yield only the first n values, or all values
+ satisfying a predicate.
+ Example: >lua
+ local it = vim.iter({ 1, 2, 3, 4 }):take(2)
+ it:next()
+ -- 1
+ it:next()
+ -- 2
+ it:next()
+ -- nil
- *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.
+ local function pred(x) return x < 2 end
+ local it2 = vim.iter({ 1, 2, 3, 4 }):take(pred)
+ it2:next()
+ -- 1
+ it2:next()
+ -- nil
+<
Parameters: ~
- • {bufnr} (`integer`)
- • {line_idx} (`integer`)
- • {start} (`integer?`)
- • {end_} (`integer?`)
+ • {n} (`integer|fun(...):boolean`) Number of values to take or a
+ predicate.
- 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
+ Return: ~
+ (`Iter`)
-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.
+Iter:totable() *Iter:totable()*
+ Collect the iterator into a table.
- Parameters: ~
- • {str} (`string`)
+ The resulting table depends on the initial source in the iterator
+ pipeline. Array-like tables and function iterators will be collected into
+ an array-like table. If multiple values are returned from the final stage
+ in the iterator pipeline, each value will be included in a table.
- Return (multiple): ~
- (`integer?`) match start (byte index), or `nil` if no match
- (`integer?`) match end (byte index), or `nil` if no match
+ Examples: >lua
+ vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
+ -- { 100, 20, 50 }
-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|.
+ vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
+ -- { { 1, 2 }, { 2, 4 }, { 3, 6 } }
- Parameters: ~
- • {re} (`string`)
+ vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
+ -- { { 'a', 1 }, { 'c', 3 } }
+<
+
+ The generated table is an array-like table with consecutive, numeric
+ indices. To create a map-like table with arbitrary keys, use
+ |Iter:fold()|.
Return: ~
- (`vim.regex`)
+ (`table`)
==============================================================================
-Lua module: vim.secure *vim.secure*
+Lua module: vim.json *vim.json*
-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.
+This module provides encoding and decoding of Lua objects to and from
+JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
- 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.
+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).
- Attributes: ~
- Since: 0.9.0
+ Example: >lua
+ vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
+ -- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
+<
Parameters: ~
- • {path} (`string`) Path to a file or directory to read.
+ • {str} (`string`) Stringified JSON data.
+ • {opts} (`table<string,any>?`) Options table with keys:
+ • luanil: (table) Table with keys:
+ • object: (boolean) When true, converts `null` in JSON
+ objects to Lua `nil` instead of |vim.NIL|.
+ • array: (boolean) When true, converts `null` in JSON arrays
+ to Lua `nil` instead of |vim.NIL|.
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.
+ (`any`)
- Attributes: ~
- Since: 0.9.0
+vim.json.encode({obj}, {opts}) *vim.json.encode()*
+ Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
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}.
+ • {obj} (`any`)
+ • {opts} (`table<string,any>?`) Options table with keys:
+ • escape_slash: (boolean) (default false) Escape slash
+ characters "/" in string values.
- Return (multiple): ~
- (`boolean`) success true if operation was successful
- (`string`) msg full path if operation was successful, else error
- message
+ Return: ~
+ (`string`)
==============================================================================
-Lua module: vim.version *vim.version*
+Lua module: vim.keymap *vim.keymap*
-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.
+vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()*
+ Remove an existing mapping. Examples: >lua
+ vim.keymap.del('n', 'lhs')
-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.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
<
-*vim.version()* returns the version of the current Nvim process.
+ 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.
-VERSION RANGE SPEC *version-range*
+ See also: ~
+ • |vim.keymap.set()|
-A version "range spec" defines a semantic version range which can be tested
-against a version, using |vim.version.range()|.
+vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
+ Defines a |mapping| of |keycodes| to a function or keycodes.
-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
+ Examples: >lua
+ -- Map "x" to a Lua function:
+ vim.keymap.set('n', 'x', function() print('real lua function') end)
+ -- Map "<leader>x" to multiple modes for the current buffer:
+ vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
+ -- Map <Tab> to an expression (|:map-<expr>|):
+ vim.keymap.set('i', '<Tab>', function()
+ return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
+ end, { expr = true })
+ -- Map "[%%" to a <Plug> mapping:
+ vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
+<
- 1.2.3 - 2.3.4 is >=1.2.3 <2.3.4
+ 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`.
- 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
+ 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}.
- Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
- 1.2 - 2.3.0 is 1.2.0 - 2.3.0
-<
+ See also: ~
+ • |nvim_set_keymap()|
+ • |maparg()|
+ • |mapcheck()|
+ • |mapset()|
-*vim.VersionRange*
+==============================================================================
+Lua module: vim.loader *vim.loader*
- Fields: ~
- • {from} (`vim.Version`)
- • {to}? (`vim.Version`)
- • {has} (`fun(self: vim.VersionRange, version: string|vim.Version): boolean`)
- See |VersionRange:has()|.
+vim.loader.enable({enable}) *vim.loader.enable()*
+ WARNING: This feature is experimental/unstable.
+ Enables or disables the experimental Lua module loader:
-VersionRange:has({version}) *VersionRange:has()*
- Check if a version is in the range (inclusive `from`, exclusive `to`).
+ Enable (`enable=true`):
+ • overrides |loadfile()|
+ • adds the Lua loader using the byte-compilation cache
+ • adds the libs loader
+ • removes the default Nvim loader
- 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
-<
+ Disable (`enable=false`):
+ • removes the loaders
+ • adds the default Nvim loader
- 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))
-<
+ Parameters: ~
+ • {enable} (`boolean?`) true/nil to enable, false to disable
- Attributes: ~
- Since: 0.9.0
+vim.loader.find({modname}, {opts}) *vim.loader.find()*
+ WARNING: This feature is experimental/unstable.
+
+ Finds Lua modules for the given module name.
Parameters: ~
- • {version} (`string|vim.Version`)
+ • {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: ~
- (`boolean`)
+ (`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="*"`
- See also: ~
- • https://github.com/npm/node-semver#ranges
+vim.loader.reset({path}) *vim.loader.reset()*
+ WARNING: This feature is experimental/unstable.
-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}`).
+ Resets the cache for the path, or all the paths if path is nil.
- 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
-<
+ Parameters: ~
+ • {path} (`string?`) path to reset
- Note: ~
- • Per semver, build metadata is ignored when comparing two
- otherwise-equivalent versions.
- Attributes: ~
- Since: 0.9.0
+==============================================================================
+Lua module: vim.lpeg *vim.lpeg*
- 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`.
+LPeg is a pattern-matching library for Lua, based on Parsing Expression
+Grammars (PEGs). https://bford.info/packrat/
-vim.version.eq({v1}, {v2}) *vim.version.eq()*
- Returns `true` if the given versions are equal. See |vim.version.cmp()|
- for usage.
+ *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/).
- Attributes: ~
- Since: 0.9.0
+In addition, its regex-like interface is available as |vim.re|
+(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
- 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.
+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.
- Attributes: ~
- Since: 0.10.0
+ 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: ~
- • {v1} (`vim.Version|number[]|string`)
- • {v2} (`vim.Version|number[]|string`)
+ • {subject} (`string`)
+ • {init} (`integer?`)
+ • {...} (`any`)
Return: ~
- (`boolean`)
-
-vim.version.gt({v1}, {v2}) *vim.version.gt()*
- Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
+ (`any`) ...
- Attributes: ~
- Since: 0.9.0
+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: ~
- • {v1} (`vim.Version|number[]|string`)
- • {v2} (`vim.Version|number[]|string`)
+ • {pattern} (`vim.lpeg.Pattern|string|integer|boolean|table`)
Return: ~
- (`boolean`)
+ (`vim.lpeg.Pattern`)
-vim.version.intersect({r1}, {r2}) *vim.version.intersect()*
- WARNING: This feature is experimental/unstable.
+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.
- Computes the common range shared by the given ranges.
+ 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: ~
- • {r1} (`vim.VersionRange`) First range to intersect. See
- |vim.VersionRange|.
- • {r2} (`vim.VersionRange`) Second range to intersect. See
- |vim.VersionRange|.
+ • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
Return: ~
- (`vim.VersionRange?`) Maximal range that is present inside both `r1`
- and `r2`. `nil` if such range does not exist. See |vim.VersionRange|.
+ (`vim.lpeg.Capture`)
-vim.version.last({versions}) *vim.version.last()*
- TODO: generalize this, move to func.lua
+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: ~
- • {versions} (`vim.Version[]`)
+ • {n} (`integer`)
Return: ~
- (`vim.Version?`)
-
-vim.version.le({v1}, {v2}) *vim.version.le()*
- Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
+ (`vim.lpeg.Capture`)
- Attributes: ~
- Since: 0.10.0
+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: ~
- • {v1} (`vim.Version|number[]|string`)
- • {v2} (`vim.Version|number[]|string`)
+ • {name} (`any`)
Return: ~
- (`boolean`)
-
-vim.version.lt({v1}, {v2}) *vim.version.lt()*
- Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
+ (`vim.lpeg.Capture`)
- Attributes: ~
- Since: 0.9.0
+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: ~
- • {v1} (`vim.Version|number[]|string`)
- • {v2} (`vim.Version|number[]|string`)
+ • {...} (`any`)
Return: ~
- (`boolean`)
+ (`vim.lpeg.Capture`)
-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" }
-<
+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.
- Attributes: ~
- Since: 0.9.0
+ 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: ~
- • {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.
+ • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+ • {func} (`fun(acc, newvalue)`)
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:
+ (`vim.lpeg.Capture`)
- Attributes: ~
- Since: 0.9.0
+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: ~
- • {spec} (`string`) Version range "spec"
+ • {patt} (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
+ • {name} (`string?`)
Return: ~
- (`vim.VersionRange?`) See |vim.VersionRange|.
+ (`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.iter *vim.iter*
+Lua module: vim.regex *vim.regex*
-*vim.iter()* is an interface for |iterable|s: it wraps a table or function
-argument into an *Iter* object with methods (such as |Iter:filter()| and
-|Iter:map()|) that transform the underlying source data. These methods can be
-chained to create iterator "pipelines": the output of each pipeline stage is
-input to the next stage. The first stage depends on the type passed to
-`vim.iter()`:
-• Lists or arrays (|lua-list|) yield only the value of each element.
- • Holes (nil values) are allowed (but discarded).
- • Use pairs() to treat array/list tables as dicts (preserve holes and
- non-contiguous integer keys): `vim.iter(pairs(…))`.
- • Use |Iter:enumerate()| to also pass the index to the next stage.
- • Or initialize with ipairs(): `vim.iter(ipairs(…))`.
-• Non-list tables (|lua-dict|) yield both the key and value of each element.
-• Function |iterator|s yield all values returned by the underlying function.
-• Tables with a |__call()| metamethod are treated as function iterators.
+Vim regexes can be used directly from Lua. Currently they only allow matching
+within a single line.
-The iterator pipeline terminates when the underlying |iterable| is exhausted
-(for function iterators this means it returned nil).
-Note: `vim.iter()` scans table input to decide if it is a list or a dict; to
-avoid this cost you can wrap the table with an iterator e.g.
-`vim.iter(ipairs({…}))`, but that precludes the use of |list-iterator|
-operations such as |Iter:rev()|).
+ *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.
-Examples: >lua
- local it = vim.iter({ 1, 2, 3, 4, 5 })
- it:map(function(v)
- return v * 3
- end)
- it:rev()
- it:skip(2)
- it:totable()
- -- { 9, 6, 3 }
+ Parameters: ~
+ • {bufnr} (`integer`)
+ • {line_idx} (`integer`)
+ • {start} (`integer?`)
+ • {end_} (`integer?`)
- -- ipairs() is a function iterator which returns both the index (i) and the value (v)
- vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
- if i > 2 then return v end
- end):totable()
- -- { 3, 4, 5 }
+ 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
- local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
- it:map(function(s) return tonumber(s) end)
- for i, d in it:enumerate() do
- print(string.format("Column %d is %d", i, d))
- end
- -- Column 1 is 1
- -- Column 2 is 2
- -- Column 3 is 3
- -- Column 4 is 4
- -- Column 5 is 5
+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*
+
+*vim.snippet.ActiveFilter*
+
+ Fields: ~
+ • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
+ previous, 1 for next.
+
+
+vim.snippet.active({filter}) *vim.snippet.active()*
+ Returns `true` if there's an active snippet in the current buffer,
+ applying the given filter if provided.
+
+ Parameters: ~
+ • {filter} (`vim.snippet.ActiveFilter?`) Filter to constrain the search
+ with:
+ • `direction` (vim.snippet.Direction): Navigation direction.
+ Will return `true` if the snippet can be jumped in the
+ given direction. See |vim.snippet.ActiveFilter|.
+
+ Return: ~
+ (`boolean`)
+
+vim.snippet.expand({input}) *vim.snippet.expand()*
+ Expands the given snippet text. Refer to
+ https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax
+ for the specification of valid input.
+
+ Tabstops are highlighted with |hl-SnippetTabstop|.
+
+ Parameters: ~
+ • {input} (`string`)
+
+vim.snippet.jump({direction}) *vim.snippet.jump()*
+ Jumps to the next (or previous) placeholder in the current snippet, if
+ possible.
+
+ By default `<Tab>` is setup to jump if a snippet is active. The default
+ mapping looks like: >lua
+ vim.keymap.set({ 'i', 's' }, '<Tab>', function()
+ if vim.snippet.active({ direction = 1 }) then
+ return '<Cmd>lua vim.snippet.jump(1)<CR>'
+ else
+ return '<Tab>'
+ end
+ end, { descr = '...', expr = true, silent = true })
+<
+
+ Parameters: ~
+ • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
+ previous, 1 for next.
+
+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.
- vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
- return k == 'z'
- end)
- -- true
- local rb = vim.ringbuf(3)
- rb:push("a")
- rb:push("b")
- vim.iter(rb):totable()
- -- { "a", "b" }
-<
+==============================================================================
+Lua module: vim.system *lua-vim-system*
+*vim.SystemCompleted*
-Iter:all({pred}) *Iter:all()*
- Returns true if all items in the iterator match the given predicate.
+ 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.
- Parameters: ~
- • {pred} (`fun(...):boolean`) Predicate function. Takes all values
- returned from the previous stage in the pipeline as arguments
- and returns true if the predicate matches.
+*vim.SystemObj*
-Iter:any({pred}) *Iter:any()*
- Returns true if any of the items in the iterator match the given
- predicate.
+ 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()|.
- Parameters: ~
- • {pred} (`fun(...):boolean`) Predicate function. Takes all values
- returned from the previous stage in the pipeline as arguments
- and returns true if the predicate matches.
-Iter:each({f}) *Iter:each()*
- Calls a function once for each item in the pipeline, draining the
- iterator.
+SystemObj:is_closing() *SystemObj:is_closing()*
+ Checks if the process handle is closing or already closed.
- For functions with side effects. To modify the values in the iterator, use
- |Iter:map()|.
+ 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.
- Parameters: ~
- • {f} (`fun(...)`) Function to execute for each item in the pipeline.
- Takes all of the values returned by the previous stage in the
- pipeline as arguments.
+ Return: ~
+ (`boolean`)
-Iter:enumerate() *Iter:enumerate()*
- Yields the item index (count) and value for each item of an iterator
- pipeline.
+SystemObj:kill({signal}) *SystemObj:kill()*
+ Sends a signal to the process.
- For list tables, this is more efficient: >lua
- vim.iter(ipairs(t))
-<
+ The signal can be specified as an integer or as a string.
- instead of: >lua
- vim.iter(t):enumerate()
+ Example: >lua
+ local obj = vim.system({'sleep', '10'})
+ obj:kill('TERM') -- sends SIGTERM to the process
<
- Example: >lua
+ Parameters: ~
+ • {signal} (`integer|string`) Signal to send to the process.
- local it = vim.iter(vim.gsplit('abc', '')):enumerate()
- it:next()
- -- 1 'a'
- it:next()
- -- 2 'b'
- it:next()
- -- 3 'c'
-<
+SystemObj:wait({timeout}) *SystemObj:wait()*
+ Waits for the process to complete or until the specified timeout elapses.
- Return: ~
- (`Iter`)
+ 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.
-Iter:filter({f}) *Iter:filter()*
- Filters an iterator pipeline.
+ 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 bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
+ 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: ~
- • {f} (`fun(...):boolean`) Takes all values returned from the previous
- stage in the pipeline and returns false or nil if the current
- iterator element should be removed.
+ • {timeout} (`integer?`)
Return: ~
- (`Iter`)
+ (`vim.SystemCompleted`) See |vim.SystemCompleted|.
-Iter:find({f}) *Iter:find()*
- Find the first value in the iterator that satisfies the given predicate.
+SystemObj:write({data}) *SystemObj:write()*
+ Writes data to the stdin of the process or closes stdin.
- Advances the iterator. Returns nil and drains the iterator if no value is
- found.
+ If `data` is a list of strings, each string is written followed by a
+ newline.
- Examples: >lua
+ If `data` is a string, it is written as-is.
- local it = vim.iter({ 3, 6, 9, 12 })
- it:find(12)
- -- 12
+ If `data` is `nil`, the write side of the stream is shut down and the pipe
+ is closed.
- local it = vim.iter({ 3, 6, 9, 12 })
- it:find(20)
- -- nil
+ Example: >lua
+ local obj = vim.system({'cat'}, { stdin = true })
+ obj:write({'hello', 'world'}) -- writes 'hello\nworld\n' to stdin
+ obj:write(nil) -- closes stdin
+<
- local it = vim.iter({ 3, 6, 9, 12 })
- it:find(function(v) return v % 4 == 0 end)
- -- 12
+ 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: ~
- • {f} (`any`)
+ • {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<string,string|number>`) 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: ~
- (`any`)
+ (`vim.SystemObj`) See |vim.SystemObj|.
-Iter:flatten({depth}) *Iter:flatten()*
- Flattens a |list-iterator|, un-nesting nested values up to the given
- {depth}. Errors if it attempts to flatten a dict-like value.
- Examples: >lua
- vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable()
- -- { 1, 2, { 3 } }
+==============================================================================
+Lua module: vim.text *vim.text*
- vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
- -- { 1, { a = 2 }, 3 }
+vim.text.diff({a}, {b}, {opts}) *vim.text.diff()*
+ Run diff on strings {a} and {b}. Any indices returned by this function,
+ either directly or via callback arguments, are 1-based.
- vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()
- -- error: attempt to flatten a dict-like table
+ Examples: >lua
+ vim.text.diff('a\n', 'b\nc\n')
+ -- =>
+ -- @@ -1 +1,2 @@
+ -- -a
+ -- +b
+ -- +c
+
+ vim.text.diff('a\n', 'b\nc\n', {result_type = 'indices'})
+ -- =>
+ -- {
+ -- {1, 1, 1, 2}
+ -- }
<
Parameters: ~
- • {depth} (`number?`) Depth to which |list-iterator| should be
- flattened (defaults to 1)
+ • {a} (`string`) First string to compare
+ • {b} (`string`) Second string to compare
+ • {opts} (`table?`) Optional parameters:
+ • {on_hunk}?
+ (`fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?`)
+ Invoked for each hunk in the diff. Return a negative number
+ to cancel the callback for any remaining hunks. Arguments:
+ • `start_a` (`integer`): Start line of hunk in {a}.
+ • `count_a` (`integer`): Hunk size in {a}.
+ • `start_b` (`integer`): Start line of hunk in {b}.
+ • `count_b` (`integer`): Hunk size in {b}.
+ • {result_type}? (`'unified'|'indices'`, default: `'unified'`)
+ Form of the returned diff:
+ • `unified`: String in unified format.
+ • `indices`: Array of hunk locations. Note: This option is
+ ignored if `on_hunk` is used.
+ • {linematch}? (`boolean|integer`) Run linematch on the
+ resulting hunks from xdiff. When integer, only hunks upto
+ this size in lines are run through linematch. Requires
+ `result_type = indices`, ignored otherwise.
+ • {algorithm}? (`'myers'|'minimal'|'patience'|'histogram'`,
+ default: `'myers'`) Diff algorithm to use. Values:
+ • `myers`: the default algorithm
+ • `minimal`: spend extra time to generate the smallest
+ possible diff
+ • `patience`: patience diff algorithm
+ • `histogram`: histogram diff algorithm
+ • {ctxlen}? (`integer`) Context length
+ • {interhunkctxlen}? (`integer`) Inter hunk context length
+ • {ignore_whitespace}? (`boolean`) Ignore whitespace
+ • {ignore_whitespace_change}? (`boolean`) Ignore whitespace
+ change
+ • {ignore_whitespace_change_at_eol}? (`boolean`) Ignore
+ whitespace change at end-of-line.
+ • {ignore_cr_at_eol}? (`boolean`) Ignore carriage return at
+ end-of-line
+ • {ignore_blank_lines}? (`boolean`) Ignore blank lines
+ • {indent_heuristic}? (`boolean`) Use the indent heuristic for
+ the internal diff library.
Return: ~
- (`Iter`)
-
-Iter:fold({init}, {f}) *Iter:fold()*
- Folds ("reduces") an iterator into a single value. *Iter:reduce()*
-
- Examples: >lua
- -- Create a new table with only even values
- vim.iter({ a = 1, b = 2, c = 3, d = 4 })
- :filter(function(k, v) return v % 2 == 0 end)
- :fold({}, function(acc, k, v)
- acc[k] = v
- return acc
- end) --> { b = 2, d = 4 }
+ (`string|integer[][]?`) See {opts.result_type}. `nil` if
+ {opts.on_hunk} is given.
- -- Get the "maximum" item of an iterable.
- vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
- :fold({}, function(acc, v)
- acc.max = math.max(v, acc.max or v)
- return acc
- end) --> { max = 42 }
-<
+vim.text.hexdecode({enc}) *vim.text.hexdecode()*
+ Hex decode a string.
Parameters: ~
- • {init} (`any`) Initial value of the accumulator.
- • {f} (`fun(acc:A, ...):A`) Accumulation function.
-
- Return: ~
- (`any`)
-
-Iter:join({delim}) *Iter:join()*
- Collect the iterator into a delimited string.
+ • {enc} (`string`) String to decode
- Each element in the iterator is joined into a string separated by {delim}.
+ Return (multiple): ~
+ (`string?`) Decoded string
+ (`string?`) Error message, if any
- Consumes the iterator.
+vim.text.hexencode({str}) *vim.text.hexencode()*
+ Hex encode a string.
Parameters: ~
- • {delim} (`string`) Delimiter
+ • {str} (`string`) String to encode
Return: ~
- (`string`)
-
-Iter:last() *Iter:last()*
- Drains the iterator and returns the last item.
+ (`string`) Hex encoded string
- Example: >lua
+vim.text.indent({size}, {text}, {opts}) *vim.text.indent()*
+ Sets the indent (i.e. the common leading whitespace) of non-empty lines in
+ `text` to `size` spaces/tabs.
- local it = vim.iter(vim.gsplit('abcdefg', ''))
- it:last()
- -- 'g'
+ Indent is calculated by number of consecutive indent chars.
+ • The first indented, non-empty line decides the indent char (space/tab):
+ • `SPC SPC TAB …` = two-space indent.
+ • `TAB SPC …` = one-tab indent.
+ • Set `opts.expandtab` to treat tabs as spaces.
- local it = vim.iter({ 3, 6, 9, 12, 15 })
- it:last()
- -- 15
+ To "dedent" (remove the common indent), pass `size=0`: >lua
+ vim.print(vim.text.indent(0, ' a\n b\n'))
<
- Return: ~
- (`any`)
-
- See also: ~
- • |Iter:rpeek()|
-
-Iter:map({f}) *Iter:map()*
- Maps the items of an iterator pipeline to the values returned by `f`.
-
- If the map function returns nil, the value is filtered from the iterator.
+ To adjust relative-to an existing indent, call indent() twice: >lua
+ local indented, old_indent = vim.text.indent(0, ' a\n b\n')
+ indented = vim.text.indent(old_indent + 2, indented)
+ vim.print(indented)
+<
- Example: >lua
- local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
- if v % 2 == 0 then
- return v * 3
- end
- end)
- it:totable()
- -- { 6, 12 }
+ To ignore the final, blank line when calculating the indent, use gsub()
+ before calling indent(): >lua
+ local text = ' a\n b\n '
+ vim.print(vim.text.indent(0, (text:gsub('\n[\t ]+\n?$', '\n'))))
<
Parameters: ~
- • {f} (`fun(...):...:any`) Mapping function. Takes all values returned
- from the previous stage in the pipeline as arguments and returns
- one or more new values, which are used in the next pipeline
- stage. Nil return values are filtered from the output.
-
- Return: ~
- (`Iter`)
-
-Iter:next() *Iter:next()*
- Gets the next value from the iterator.
-
- Example: >lua
+ • {size} (`integer`) Number of spaces.
+ • {text} (`string`) Text to indent.
+ • {opts} (`{ expandtab?: integer }?`)
- local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)
- it:next()
- -- 1
- it:next()
- -- 2
- it:next()
- -- 3
-<
+ Return (multiple): ~
+ (`string`) Indented text.
+ (`integer`) Indent size before modification.
- Return: ~
- (`any`)
-Iter:nth({n}) *Iter:nth()*
- Gets the nth value of an iterator (and advances to it).
+==============================================================================
+Lua module: vim.ui *vim.ui*
- If `n` is negative, offsets from the end of a |list-iterator|.
+vim.ui.input({opts}, {on_confirm}) *vim.ui.input()*
+ Prompts the user for input, allowing arbitrary (potentially asynchronous)
+ work until `on_confirm`.
Example: >lua
- local it = vim.iter({ 3, 6, 9, 12 })
- it:nth(2)
- -- 6
- it:nth(2)
- -- 12
-
- local it2 = vim.iter({ 3, 6, 9, 12 })
- it2:nth(-2)
- -- 9
- it2:nth(-2)
- -- 3
+ vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
+ vim.o.shiftwidth = tonumber(input)
+ end)
<
Parameters: ~
- • {n} (`number`) Index of the value to return. May be negative if the
- source is a |list-iterator|.
+ • {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.
- Return: ~
- (`any`)
+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.
-Iter:peek() *Iter:peek()*
- Gets the next value in a |list-iterator| without consuming it.
+ Can also be invoked with `:Open`. *:Open*
- Example: >lua
+ Expands "~/" and environment variables in filesystem paths.
- local it = vim.iter({ 3, 6, 9, 12 })
- it:peek()
- -- 3
- it:peek()
- -- 3
- it:next()
- -- 3
+ 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
<
- Return: ~
- (`any`)
+ Parameters: ~
+ • {path} (`string`) Path or URL to open
+ • {opt} (`table?`) Options
+ • {cmd}? (`string[]`) Command used to open the path or URL.
-Iter:pop() *Iter:pop()*
- "Pops" a value from a |list-iterator| (gets the last value and decrements
- the tail).
+ 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
- local it = vim.iter({1, 2, 3, 4})
- it:pop()
- -- 4
- it:pop()
- -- 3
+ 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)
<
- Return: ~
- (`any`)
+ 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.
-Iter:rev() *Iter:rev()*
- Reverses a |list-iterator| pipeline.
- Example: >lua
+==============================================================================
+Lua module: vim.uri *vim.uri*
- local it = vim.iter({ 3, 6, 9, 12 }):rev()
- it:totable()
- -- { 12, 9, 6, 3 }
-<
+vim.uri_decode({str}) *vim.uri_decode()*
+ URI-decodes a string containing percent escapes.
+
+ Parameters: ~
+ • {str} (`string`) string to decode
Return: ~
- (`Iter`)
+ (`string`) decoded string
-Iter:rfind({f}) *Iter:rfind()*
- Gets the first value satisfying a predicate, from the end of a
- |list-iterator|.
+vim.uri_encode({str}, {rfc}) *vim.uri_encode()*
+ URI-encodes a string using percent escapes.
- Advances the iterator. Returns nil and drains the iterator if no value is
- found.
+ Parameters: ~
+ • {str} (`string`) string to encode
+ • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`)
- Examples: >lua
+ Return: ~
+ (`string`) encoded string
- local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
- it:rfind(1)
- -- 5 1
- it:rfind(1)
- -- 1 1
-<
+vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()*
+ Gets a URI from a bufnr.
Parameters: ~
- • {f} (`any`)
+ • {bufnr} (`integer`)
Return: ~
- (`any`)
-
- See also: ~
- • |Iter:find()|
+ (`string`) URI
-Iter:rpeek() *Iter:rpeek()*
- Gets the last value of a |list-iterator| without consuming it.
+vim.uri_from_fname({path}) *vim.uri_from_fname()*
+ Gets a URI from a file path.
- Example: >lua
- local it = vim.iter({1, 2, 3, 4})
- it:rpeek()
- -- 4
- it:rpeek()
- -- 4
- it:pop()
- -- 4
-<
+ Parameters: ~
+ • {path} (`string`) Path to file
Return: ~
- (`any`)
+ (`string`) URI
- See also: ~
- • |Iter:last()|
+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.
-Iter:rskip({n}) *Iter:rskip()*
- Discards `n` values from the end of a |list-iterator| pipeline.
+ Parameters: ~
+ • {uri} (`string`)
- Example: >lua
- local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2)
- it:next()
- -- 1
- it:pop()
- -- 3
-<
+ Return: ~
+ (`integer`) bufnr
+
+vim.uri_to_fname({uri}) *vim.uri_to_fname()*
+ Gets a filename from a URI.
Parameters: ~
- • {n} (`number`) Number of values to skip.
+ • {uri} (`string`)
Return: ~
- (`Iter`)
+ (`string`) filename or unchanged URI for non-file URIs
-Iter:skip({n}) *Iter:skip()*
- Skips `n` values of an iterator pipeline, or all values satisfying a
- predicate of a |list-iterator|.
- Example: >lua
+==============================================================================
+Lua module: vim.version *vim.version*
- local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
- it:next()
- -- 9
+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.
- local function pred(x) return x < 10 end
- local it2 = vim.iter({ 3, 6, 9, 12 }):skip(pred)
- it2:next()
- -- 12
+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
<
- Parameters: ~
- • {n} (`integer|fun(...):boolean`) Number of values to skip or a
- predicate.
-
- Return: ~
- (`Iter`)
-
-Iter:slice({first}, {last}) *Iter:slice()*
- Sets the start and end of a |list-iterator| pipeline.
+*vim.version()* returns the version of the current Nvim process.
- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
+VERSION RANGE SPEC *version-range*
- Parameters: ~
- • {first} (`number`)
- • {last} (`number`)
+A version "range spec" defines a semantic version range which can be tested
+against a version, using |vim.version.range()|.
- Return: ~
- (`Iter`)
+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
-Iter:take({n}) *Iter:take()*
- Transforms an iterator to yield only the first n values, or all values
- satisfying a predicate.
+ 1.2.3 - 2.3.4 is >=1.2.3 <2.3.4
- Example: >lua
- local it = vim.iter({ 1, 2, 3, 4 }):take(2)
- it:next()
- -- 1
- it:next()
- -- 2
- it:next()
- -- nil
+ 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
- local function pred(x) return x < 2 end
- local it2 = vim.iter({ 1, 2, 3, 4 }):take(pred)
- it2:next()
- -- 1
- it2:next()
- -- nil
+ Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
+ 1.2 - 2.3.0 is 1.2.0 - 2.3.0
<
- Parameters: ~
- • {n} (`integer|fun(...):boolean`) Number of values to take or a
- predicate.
- Return: ~
- (`Iter`)
+*vim.VersionRange*
-Iter:totable() *Iter:totable()*
- Collect the iterator into a table.
+ Fields: ~
+ • {from} (`vim.Version`)
+ • {to}? (`vim.Version`)
+ • {has} (`fun(self: vim.VersionRange, version: string|vim.Version): boolean`)
+ See |VersionRange:has()|.
- The resulting table depends on the initial source in the iterator
- pipeline. Array-like tables and function iterators will be collected into
- an array-like table. If multiple values are returned from the final stage
- in the iterator pipeline, each value will be included in a table.
- Examples: >lua
- vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
- -- { 100, 20, 50 }
+VersionRange:has({version}) *VersionRange:has()*
+ Check if a version is in the range (inclusive `from`, exclusive `to`).
- vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
- -- { { 1, 2 }, { 2, 4 }, { 3, 6 } }
+ 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
+<
- vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
- -- { { 'a', 1 }, { 'c', 3 } }
+ 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))
<
- The generated table is an array-like table with consecutive, numeric
- indices. To create a map-like table with arbitrary keys, use
- |Iter:fold()|.
+ Attributes: ~
+ Since: 0.9.0
+
+ Parameters: ~
+ • {version} (`string|vim.Version`)
Return: ~
- (`table`)
+ (`boolean`)
+ See also: ~
+ • https://github.com/npm/node-semver#ranges
-==============================================================================
-Lua module: vim.snippet *vim.snippet*
+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}`).
-*vim.snippet.ActiveFilter*
+ 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
+<
- Fields: ~
- • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
- previous, 1 for next.
+ 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`.
-vim.snippet.active({filter}) *vim.snippet.active()*
- Returns `true` if there's an active snippet in the current buffer,
- applying the given filter if provided.
+ 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: ~
- • {filter} (`vim.snippet.ActiveFilter?`) Filter to constrain the search
- with:
- • `direction` (vim.snippet.Direction): Navigation direction.
- Will return `true` if the snippet can be jumped in the
- given direction. See |vim.snippet.ActiveFilter|.
+ • {v1} (`vim.Version|number[]|string`)
+ • {v2} (`vim.Version|number[]|string`)
Return: ~
(`boolean`)
-vim.snippet.expand({input}) *vim.snippet.expand()*
- Expands the given snippet text. Refer to
- https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax
- for the specification of valid input.
+vim.version.ge({v1}, {v2}) *vim.version.ge()*
+ Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
- Tabstops are highlighted with |hl-SnippetTabstop|.
+ Attributes: ~
+ Since: 0.10.0
Parameters: ~
- • {input} (`string`)
+ • {v1} (`vim.Version|number[]|string`)
+ • {v2} (`vim.Version|number[]|string`)
-vim.snippet.jump({direction}) *vim.snippet.jump()*
- Jumps to the next (or previous) placeholder in the current snippet, if
- possible.
+ Return: ~
+ (`boolean`)
- By default `<Tab>` is setup to jump if a snippet is active. The default
- mapping looks like: >lua
- vim.keymap.set({ 'i', 's' }, '<Tab>', function()
- if vim.snippet.active({ direction = 1 }) then
- return '<Cmd>lua vim.snippet.jump(1)<CR>'
- else
- return '<Tab>'
- end
- end, { descr = '...', expr = true, silent = true })
-<
+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: ~
- • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
- previous, 1 for next.
+ • {v1} (`vim.Version|number[]|string`)
+ • {v2} (`vim.Version|number[]|string`)
-vim.snippet.stop() *vim.snippet.stop()*
- Exits the current snippet.
+ Return: ~
+ (`boolean`)
+vim.version.intersect({r1}, {r2}) *vim.version.intersect()*
+ WARNING: This feature is experimental/unstable.
-==============================================================================
-Lua module: vim.text *vim.text*
+ Computes the common range shared by the given ranges.
-vim.text.diff({a}, {b}, {opts}) *vim.text.diff()*
- Run diff on strings {a} and {b}. Any indices returned by this function,
- either directly or via callback arguments, are 1-based.
+ Parameters: ~
+ • {r1} (`vim.VersionRange`) First range to intersect. See
+ |vim.VersionRange|.
+ • {r2} (`vim.VersionRange`) Second range to intersect. See
+ |vim.VersionRange|.
- Examples: >lua
- vim.text.diff('a\n', 'b\nc\n')
- -- =>
- -- @@ -1 +1,2 @@
- -- -a
- -- +b
- -- +c
+ Return: ~
+ (`vim.VersionRange?`) Maximal range that is present inside both `r1`
+ and `r2`. `nil` if such range does not exist. See |vim.VersionRange|.
- vim.text.diff('a\n', 'b\nc\n', {result_type = 'indices'})
- -- =>
- -- {
- -- {1, 1, 1, 2}
- -- }
-<
+vim.version.last({versions}) *vim.version.last()*
+ TODO: generalize this, move to func.lua
Parameters: ~
- • {a} (`string`) First string to compare
- • {b} (`string`) Second string to compare
- • {opts} (`table?`) Optional parameters:
- • {on_hunk}?
- (`fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?`)
- Invoked for each hunk in the diff. Return a negative number
- to cancel the callback for any remaining hunks. Arguments:
- • `start_a` (`integer`): Start line of hunk in {a}.
- • `count_a` (`integer`): Hunk size in {a}.
- • `start_b` (`integer`): Start line of hunk in {b}.
- • `count_b` (`integer`): Hunk size in {b}.
- • {result_type}? (`'unified'|'indices'`, default: `'unified'`)
- Form of the returned diff:
- • `unified`: String in unified format.
- • `indices`: Array of hunk locations. Note: This option is
- ignored if `on_hunk` is used.
- • {linematch}? (`boolean|integer`) Run linematch on the
- resulting hunks from xdiff. When integer, only hunks upto
- this size in lines are run through linematch. Requires
- `result_type = indices`, ignored otherwise.
- • {algorithm}? (`'myers'|'minimal'|'patience'|'histogram'`,
- default: `'myers'`) Diff algorithm to use. Values:
- • `myers`: the default algorithm
- • `minimal`: spend extra time to generate the smallest
- possible diff
- • `patience`: patience diff algorithm
- • `histogram`: histogram diff algorithm
- • {ctxlen}? (`integer`) Context length
- • {interhunkctxlen}? (`integer`) Inter hunk context length
- • {ignore_whitespace}? (`boolean`) Ignore whitespace
- • {ignore_whitespace_change}? (`boolean`) Ignore whitespace
- change
- • {ignore_whitespace_change_at_eol}? (`boolean`) Ignore
- whitespace change at end-of-line.
- • {ignore_cr_at_eol}? (`boolean`) Ignore carriage return at
- end-of-line
- • {ignore_blank_lines}? (`boolean`) Ignore blank lines
- • {indent_heuristic}? (`boolean`) Use the indent heuristic for
- the internal diff library.
+ • {versions} (`vim.Version[]`)
Return: ~
- (`string|integer[][]?`) See {opts.result_type}. `nil` if
- {opts.on_hunk} is given.
+ (`vim.Version?`)
-vim.text.hexdecode({enc}) *vim.text.hexdecode()*
- Hex decode a string.
+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: ~
- • {enc} (`string`) String to decode
+ • {v1} (`vim.Version|number[]|string`)
+ • {v2} (`vim.Version|number[]|string`)
- Return (multiple): ~
- (`string?`) Decoded string
- (`string?`) Error message, if any
+ Return: ~
+ (`boolean`)
-vim.text.hexencode({str}) *vim.text.hexencode()*
- Hex encode a string.
+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: ~
- • {str} (`string`) String to encode
+ • {v1} (`vim.Version|number[]|string`)
+ • {v2} (`vim.Version|number[]|string`)
Return: ~
- (`string`) Hex encoded string
+ (`boolean`)
-vim.text.indent({size}, {text}, {opts}) *vim.text.indent()*
- Sets the indent (i.e. the common leading whitespace) of non-empty lines in
- `text` to `size` spaces/tabs.
+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" }
+<
- Indent is calculated by number of consecutive indent chars.
- • The first indented, non-empty line decides the indent char (space/tab):
- • `SPC SPC TAB …` = two-space indent.
- • `TAB SPC …` = one-tab indent.
- • Set `opts.expandtab` to treat tabs as spaces.
+ Attributes: ~
+ Since: 0.9.0
- To "dedent" (remove the common indent), pass `size=0`: >lua
- vim.print(vim.text.indent(0, ' a\n b\n'))
-<
+ 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.
- To adjust relative-to an existing indent, call indent() twice: >lua
- local indented, old_indent = vim.text.indent(0, ' a\n b\n')
- indented = vim.text.indent(old_indent + 2, indented)
- vim.print(indented)
-<
+ Return: ~
+ (`vim.Version?`) `Version` object or `nil` if input is invalid.
- To ignore the final, blank line when calculating the indent, use gsub()
- before calling indent(): >lua
- local text = ' a\n b\n '
- vim.print(vim.text.indent(0, (text:gsub('\n[\t ]+\n?$', '\n'))))
-<
+ 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: ~
- • {size} (`integer`) Number of spaces.
- • {text} (`string`) Text to indent.
- • {opts} (`{ expandtab?: integer }?`)
+ • {spec} (`string`) Version range "spec"
- Return (multiple): ~
- (`string`) Indented text.
- (`integer`) Indent size before modification.
+ Return: ~
+ (`vim.VersionRange?`) See |vim.VersionRange|.
==============================================================================
@@ -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
@@ -1248,6 +1248,260 @@ register({lang}, {filetype}) *vim.treesitter.language.register()*
==============================================================================
+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<string,vim.treesitter.LanguageTree>`)
+
+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<integer, Range6[]>`)
+
+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<integer, TSTree>)?`)
+ 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<integer, TSTree>?`)
+
+ *LanguageTree:register_cbs()*
+LanguageTree:register_cbs({cbs}, {recursive})
+ Registers callbacks for the |LanguageTree|.
+
+ Parameters: ~
+ • {cbs} (`table<TSCallbackNameOn,function>`) 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<integer, TSTree>`)
+
+
+==============================================================================
Lua module: vim.treesitter.query *lua-treesitter-query*
This Lua |treesitter-query| interface allows you to create queries and use
@@ -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<string,vim.treesitter.LanguageTree>`)
-
-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<integer, Range6[]>`)
-
-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<integer, TSTree>)?`)
- 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<integer, TSTree>?`)
-
- *LanguageTree:register_cbs()*
-LanguageTree:register_cbs({cbs}, {recursive})
- Registers callbacks for the |LanguageTree|.
-
- Parameters: ~
- • {cbs} (`table<TSCallbackNameOn,function>`) 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<integer, TSTree>`)
-
-
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
@@ -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',
+
+ -- Sections in alphanumeric order:
+ 'autocmd.c',
'buffer.c',
+ 'command.c',
'extmark.c',
- 'window.c',
- 'win_config.c',
+ 'options.c',
'tabpage.c',
- 'autocmd.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/_system.lua',
- 'runtime/lua/vim/filetype.lua',
- 'runtime/lua/vim/keymap.lua',
- 'runtime/lua/vim/fs.lua',
- 'runtime/lua/vim/hl.lua',
- 'runtime/lua/vim/secure.lua',
- 'runtime/lua/vim/version.lua',
'runtime/lua/vim/_inspector.lua',
- 'runtime/lua/vim/snippet.lua',
- 'runtime/lua/vim/text.lua',
- 'runtime/lua/vim/glob.lua',
+ 'runtime/lua/vim/_meta/base64.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/mpack.lua',
'runtime/lua/vim/_meta/re.lua',
+ 'runtime/lua/vim/_meta/regex.lua',
'runtime/lua/vim/_meta/spell.lua',
- 'runtime/lua/tohtml.lua',
+ 'runtime/lua/vim/_options.lua',
+ 'runtime/lua/vim/_system.lua',
+ 'runtime/lua/vim/filetype.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/shared.lua',
+ 'runtime/lua/vim/snippet.lua',
+ 'runtime/lua/vim/text.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',
+ 'diagnostic.lua',
+ 'document_color.lua',
'folding_range.lua',
+ 'handlers.lua',
'inlay_hint.lua',
- 'tagfunc.lua',
- 'semantic_tokens.lua',
- 'document_color.lua',
'linked_editing_range.lua',
- 'handlers.lua',
- 'util.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 = {
